@xemahq/dsl 0.6.1 → 0.8.0

package/src/workflow/lib/compiler/review-step.ts

@@ -40,7 +40,10 @@
  * worker's runtime contract — they intentionally diverge.
  */
 
-import { WorkflowErrorCode } from '@xemahq/kernel-contracts/workflow';
+import {
+  WorkflowErrorCode,
+  type CompiledManifestSource,
+} from '@xemahq/kernel-contracts/workflow';
 
 import { WorkflowDslError } from '../errors';
 import {
@@ -379,6 +382,7 @@ export function rewriteReviewStepWith(
   jobKey: string,
   payload: WorkflowJobDeclaration,
   workflow: WorkflowDocument,
+  manifestSourcesByJob: Readonly<Record<string, CompiledManifestSource | null>>,
 ): Readonly<Record<string, unknown>> {
   if (!isReviewActionRef(payload.uses)) {
     return payload.with ?? {};
@@ -423,6 +427,11 @@ export function rewriteReviewStepWith(
       step: shape.redraft.step,
       uses: producer.uses,
       with: producer.with ?? {},
+      manifestSource: requireRedraftManifestSource(
+        jobKey,
+        shape.redraft.step,
+        manifestSourcesByJob,
+      ),
     };
     const strategy = compileRedraftStrategyIR(producer.strategy);
     if (strategy !== null) {
@@ -437,6 +446,26 @@ export function rewriteReviewStepWith(
   return out;
 }
 
+function requireRedraftManifestSource(
+  reviewJobKey: string,
+  producerJobKey: string,
+  manifestSourcesByJob: Readonly<Record<string, CompiledManifestSource | null>>,
+): CompiledManifestSource {
+  const source = manifestSourcesByJob[producerJobKey];
+  if (source === undefined || source === null) {
+    throw new WorkflowDslError(
+      WorkflowErrorCode.DSL_SEMANTIC_INVALID,
+      `Job '${reviewJobKey}' redraft producer '${producerJobKey}' has no compiled Agent revision source.`,
+      {
+        jobKey: reviewJobKey,
+        fieldPath: 'with.redraft.step',
+        referencedJob: producerJobKey,
+      },
+    );
+  }
+  return source;
+}
+
 /**
  * Pre-resolve a producer step's authored matrix strategy into a
  * JSON-serializable IR descriptor the worker carries through the
@@ -513,5 +542,7 @@ function expandStaticMatrixAxes(
     }
     entries = next;
   }
-  return entries.map(Object.freeze) as readonly Readonly<Record<string, unknown>>[];
+  return entries.map(Object.freeze) as readonly Readonly<
+    Record<string, unknown>
+  >[];
 }

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

@@ -14,13 +14,13 @@ import type { ActionManifest, WorkflowDocument } from '../types';
  *
  *   - `workflow` — validated WorkflowDocument (pass through
  *     `validateWorkflowDocument` first).
- *   - `workflowRef` — slug/version/isSystem, resolved from the DB.
+ *   - `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/...`).
- *   - `workflowDefinitionVersionSha256` — sha256 of the source YAML the
+ *   - `workflowDefinitionContentHash` — content hash of the immutable source revision the
  *     compiler is consuming. Emitted into CompiledRun for audit.
  */
 export interface CompileInput {
@@ -29,11 +29,10 @@ export interface CompileInput {
   readonly trigger: TriggerPayload;
   readonly resolvedRefs: Readonly<Record<string, ResolvedRef>>;
   /**
-   * Map of agent slug → agent metadata the compiler needs for
-   * validation, keyed by bare slug. The engine pre-fetches this from
-   * llm-registry-api. The compiler validates that every literal
-   * `with.agentRef` / `with.reviewers[].agentRef` value resolves —
-   * parsing the bare slug off the `<slug>@<version>` ref before lookup.
+   * 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.
@@ -53,7 +52,7 @@ export interface CompileInput {
   readonly resolvedDeliverableSpecs?: Readonly<
     Record<string, ResolvedDeliverableSpec>
   >;
-  readonly workflowDefinitionVersionSha256: string;
+  readonly workflowDefinitionContentHash: string;
   /**
    * Contents of every wallet referenced under `requires.wallets`, plus
    * any additional wallets a dispatch caller asked for. The compiler
@@ -129,7 +128,8 @@ export interface InstallationCompileScope {
  */
 export interface ResolvedAgentMeta {
   readonly slug: string;
-  readonly snapshotHash: string;
+  readonly agentRevisionId: string;
+  readonly agentContentHash: string;
 }
 
 /**

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

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

@@ -6,34 +6,91 @@
  * 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.
+ * 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`: parses a `z.object({ ... })`
- *     literal out of TypeScript Zod source. Same regex-based brace walker
- *     the deliverable-specs-api ZodSchemaHandler uses for harvest-time
- *     validation; single source of truth lives here so the DSL compiler
- *     and the harvester agree.
+ *   - `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 introspection fails so callers can skip the
- * field check (preview / specs without introspectable shape).
+ * 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';
+
 /**
- * Parse the FIRST `z.object({ ... })` literal in the source and return
- * the top-level field identifiers. Returns `null` when the literal is
- * absent or its braces are unbalanced — the spec layer fails fast on
- * such specs at content-validation time, but here in the compiler we
- * gracefully degrade so a malformed spec doesn't block unrelated
- * expression checks elsewhere.
+ * 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): readonly string[] | null {
+export function extractZodTopLevelObjectKeys(
+  source: string,
+  exportName?: string | null,
+): readonly string[] | null {
   if (!source || source.trim().length === 0) return null;
-  const body = sliceTopLevelObjectBody(source);
-  if (body === null) return null;
-  return Object.freeze(parseObjectKeysAtTopLevel(body));
+  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) },
+  );
 }
 
 /**
@@ -71,39 +128,20 @@ function isPlainObject(v: unknown): v is Record<string, unknown> {
   return v !== null && typeof v === 'object' && !Array.isArray(v);
 }
 
-/** Substring between matching braces of the first `z.object({ ... })`, or null. */
-function sliceTopLevelObjectBody(source: string): string | null {
-  const match = /z\.object\s*\(\s*\{/.exec(source);
-  if (!match) return null;
-  const start = match.index + match[0].length;
-  let depth = 1;
-  for (let i = start; i < source.length; i += 1) {
-    const ch = source[i];
-    if (ch === '{') depth += 1;
-    else if (ch === '}' && --depth === 0) return source.slice(start, i);
-  }
-  return null;
+function availableNames(
+  declarations: readonly TopLevelZodObjectDeclaration[],
+): readonly string[] {
+  return declarations
+    .map((d) => d.exportName)
+    .filter((n): n is string => n !== null);
 }
 
-/** Walk the body once, recording identifiers at brace+paren depth 0. */
-function parseObjectKeysAtTopLevel(body: string): string[] {
-  const keys: string[] = [];
-  const depth = { brace: 0, paren: 0 };
-  for (let i = 0; i < body.length; i += 1) {
-    if (updateDepth(depth, body[i])) continue;
-    if (depth.brace !== 0 || depth.paren !== 0) continue;
-    if (i !== 0 && body[i] !== '\n' && body[i] !== ',') continue;
-    const rest = body.slice(i === 0 ? 0 : i + 1);
-    const keyMatch = /^\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*:/.exec(rest);
-    if (keyMatch?.[1]) keys.push(keyMatch[1]);
+function describeDeclarations(
+  declarations: readonly TopLevelZodObjectDeclaration[],
+): string {
+  const names = availableNames(declarations);
+  if (names.length === 0) {
+    return 'The source declares no NAMED top-level schema.';
   }
-  return keys;
-}
-
-function updateDepth(depth: { brace: number; paren: number }, ch: string | undefined): boolean {
-  if (ch === '{') { depth.brace += 1; return true; }
-  if (ch === '}') { depth.brace = Math.max(0, depth.brace - 1); return true; }
-  if (ch === '(') { depth.paren += 1; return true; }
-  if (ch === ')') { depth.paren = Math.max(0, depth.paren - 1); return true; }
-  return false;
+  return `Top-level schemas in this source: ${names.join(', ')}.`;
 }

package/src/workflow/lib/deliverable-spec-source-scan.ts

@@ -0,0 +1,280 @@
+/**
+ * Character-level scanner over TypeScript Zod source, used to locate the
+ * `z.object({ … })` literals a deliverable spec declares at the TOP level
+ * and to read their field names.
+ *
+ * Deliberately NOT a TypeScript parse or a Zod evaluation: introspection
+ * runs inside the DSL compiler, the CI gate, and a request-scoped API
+ * handler, none of which may transpile or execute spec-authored code.
+ * A scanner is enough because the only question asked is "which
+ * identifiers sit at depth 0 of this object literal".
+ *
+ * What it tracks, and why the naive regex it replaced could not:
+ *   - comments, strings, template literals and regex literals, so a
+ *     `z.object(`, a brace, or a comma appearing INSIDE one of those is
+ *     never read as code;
+ *   - brace + paren depth, so a NESTED `z.object(` (a field's own shape)
+ *     is never confused with a top-level schema declaration;
+ *   - the `const <Name> =` binding preceding each top-level literal, so a
+ *     spec can name its contract instead of relying on source order.
+ *
+ * All three walkers below share ONE trivia primitive (`skipTriviaAt`) so
+ * they cannot drift into disagreeing about what counts as code.
+ */
+
+/** A `z.object({ … })` literal declared at the top level of the source. */
+export interface TopLevelZodObjectDeclaration {
+  /** Binding name (`export const Foo = z.object({…})` → `Foo`), or null when anonymous. */
+  readonly exportName: string | null;
+  /** Field identifiers at depth 0 of the literal, in source order, de-duplicated. */
+  readonly keys: readonly string[];
+}
+
+/**
+ * If a comment / string / template / regex literal STARTS at `index`,
+ * return the index just past its end; otherwise return `index` unchanged.
+ * An unterminated token consumes the rest of the source, which makes the
+ * callers treat it as "no readable shape from here" rather than
+ * re-entering code state mid-literal.
+ *
+ * Regex detection is bounded on purpose: a `/` is treated as a regex only
+ * when the previous non-whitespace code character is `(` or `,` — the only
+ * positions a regex occupies in a schema-declaration module
+ * (`.regex(/…/)`, `.refine(x, /…/)`). Division never appears in that
+ * position, so there is no ambiguous case to guess at.
+ */
+function skipTriviaAt(source: string, index: number, prevCode: string): number {
+  const ch = source[index];
+  const next = source[index + 1];
+
+  if (ch === '/' && next === '/') return endOfLineComment(source, index + 2);
+  if (ch === '/' && next === '*') return endOfBlockComment(source, index + 2);
+  if (ch === "'" || ch === '"' || ch === '`') {
+    return endOfQuoted(source, index + 1, ch);
+  }
+  if (ch === '/' && (prevCode === '(' || prevCode === ',')) {
+    return endOfQuoted(source, index + 1, '/');
+  }
+  return index;
+}
+
+function endOfLineComment(source: string, from: number): number {
+  const nl = source.indexOf('\n', from);
+  return nl === -1 ? source.length : nl + 1;
+}
+
+function endOfBlockComment(source: string, from: number): number {
+  const end = source.indexOf('*/', from);
+  return end === -1 ? source.length : end + 2;
+}
+
+/** End of a `'…'` / `"…"` / `` `…` `` / `/…/` token, honoring backslash escapes. */
+function endOfQuoted(source: string, from: number, terminator: string): number {
+  for (let i = from; i < source.length; i += 1) {
+    const ch = source[i];
+    if (ch === '\\') {
+      i += 1;
+      continue;
+    }
+    if (ch === terminator) return i + 1;
+  }
+  return source.length;
+}
+
+/** Nesting counters shared by the depth-tracking walkers. */
+interface Depths {
+  brace: number;
+  paren: number;
+  bracket: number;
+}
+
+function newDepths(): Depths {
+  return { brace: 0, paren: 0, bracket: 0 };
+}
+
+function applyDepth(depths: Depths, ch: string | undefined): void {
+  if (ch === '{') depths.brace += 1;
+  else if (ch === '}') depths.brace = Math.max(0, depths.brace - 1);
+  else if (ch === '(') depths.paren += 1;
+  else if (ch === ')') depths.paren = Math.max(0, depths.paren - 1);
+  else if (ch === '[') depths.bracket += 1;
+  else if (ch === ']') depths.bracket = Math.max(0, depths.bracket - 1);
+}
+
+function isAtTopLevel(depths: Depths): boolean {
+  return (
+    depths.brace === 0 && depths.paren === 0 && depths.bracket === 0
+  );
+}
+
+/**
+ * Find every `z.object({ … })` literal that sits at depth 0 — i.e. every
+ * schema the module declares in its own right, as opposed to a shape
+ * nested inside another schema.
+ *
+ * Literals whose braces never close are skipped: an unbalanced source has
+ * no readable shape, and reporting a truncated key list would be worse
+ * than reporting none.
+ */
+export function scanTopLevelZodObjectDeclarations(
+  source: string,
+): readonly TopLevelZodObjectDeclaration[] {
+  const out: TopLevelZodObjectDeclaration[] = [];
+  const depths = newDepths();
+  let prevCode = '';
+  let i = 0;
+
+  while (i < source.length) {
+    const afterTrivia = skipTriviaAt(source, i, prevCode);
+    if (afterTrivia !== i) {
+      i = afterTrivia;
+      continue;
+    }
+
+    if (isAtTopLevel(depths) && matchesZodObjectAt(source, i)) {
+      const bodyStart = openingBraceIndexAfterZodObject(source, i);
+      const bodyEnd =
+        bodyStart === null ? null : matchingBraceIndex(source, bodyStart);
+      if (bodyStart !== null && bodyEnd !== null) {
+        out.push({
+          exportName: bindingNameBefore(source, i),
+          keys: parseObjectKeysAtTopLevel(source.slice(bodyStart, bodyEnd)),
+        });
+        // Resume AFTER the literal: its interior is already accounted
+        // for, and re-walking it could only produce nested matches we
+        // deliberately exclude.
+        i = bodyEnd + 1;
+        prevCode = '}';
+        continue;
+      }
+    }
+
+    const ch = source[i];
+    applyDepth(depths, ch);
+    if (ch !== undefined && !/\s/.test(ch)) prevCode = ch;
+    i += 1;
+  }
+
+  return out;
+}
+
+/** True when `z.object` starts exactly at `index` and is not part of a longer identifier. */
+function matchesZodObjectAt(source: string, index: number): boolean {
+  if (!source.startsWith('z.object', index)) return false;
+  const prev = index > 0 ? (source[index - 1] ?? '') : '';
+  return !/[A-Za-z0-9_$.]/.test(prev);
+}
+
+/** Index just past the `{` of `z.object ( {`, or null when the call is not an object literal. */
+function openingBraceIndexAfterZodObject(
+  source: string,
+  index: number,
+): number | null {
+  let i = skipWhitespace(source, index + 'z.object'.length);
+  if (source[i] !== '(') return null;
+  i = skipWhitespace(source, i + 1);
+  if (source[i] !== '{') return null;
+  return i + 1;
+}
+
+/**
+ * Index of the `}` closing the literal that starts at `bodyStart`, or null
+ * when it never closes.
+ */
+function matchingBraceIndex(source: string, bodyStart: number): number | null {
+  let depth = 1;
+  let prevCode = '{';
+  let i = bodyStart;
+
+  while (i < source.length) {
+    const afterTrivia = skipTriviaAt(source, i, prevCode);
+    if (afterTrivia !== i) {
+      i = afterTrivia;
+      continue;
+    }
+    const ch = source[i];
+    if (ch === '{') depth += 1;
+    else if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) return i;
+    }
+    if (ch !== undefined && !/\s/.test(ch)) prevCode = ch;
+    i += 1;
+  }
+  return null;
+}
+
+const BINDING_LOOKBEHIND = 400;
+const BINDING_TAIL =
+  /(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*(?::[^=]*)?=\s*$/;
+
+/** Name bound to the literal starting at `index` (`export const Foo = z.object(`), or null. */
+function bindingNameBefore(source: string, index: number): string | null {
+  const from = Math.max(0, index - BINDING_LOOKBEHIND);
+  return BINDING_TAIL.exec(source.slice(from, index))?.[1] ?? null;
+}
+
+function skipWhitespace(source: string, index: number): number {
+  let i = index;
+  while (i < source.length && /\s/.test(source[i]!)) i += 1;
+  return i;
+}
+
+/**
+ * Field identifiers at depth 0 of an object-literal body.
+ *
+ * Splits on depth-0 commas and reads the leading key of each segment, so
+ * a key is recorded exactly once. (The predecessor scanned for a key after
+ * BOTH the comma and the newline that followed it, emitting every
+ * multi-line key twice — harmless for a set-membership test, but the
+ * duplicates leaked into compiler error messages and the "known fields"
+ * preview shown to authors.)
+ */
+function parseObjectKeysAtTopLevel(body: string): readonly string[] {
+  const keys: string[] = [];
+  const seen = new Set<string>();
+  for (const segment of splitTopLevelSegments(body)) {
+    const key = leadingKeyOf(segment);
+    if (key !== null && !seen.has(key)) {
+      seen.add(key);
+      keys.push(key);
+    }
+  }
+  return Object.freeze(keys);
+}
+
+function splitTopLevelSegments(body: string): readonly string[] {
+  const segments: string[] = [];
+  const depths = newDepths();
+  let prevCode = '';
+  let start = 0;
+  let i = 0;
+
+  while (i < body.length) {
+    const afterTrivia = skipTriviaAt(body, i, prevCode);
+    if (afterTrivia !== i) {
+      i = afterTrivia;
+      continue;
+    }
+    const ch = body[i];
+    if (ch === ',' && isAtTopLevel(depths)) {
+      segments.push(body.slice(start, i));
+      start = i + 1;
+    } else {
+      applyDepth(depths, ch);
+    }
+    if (ch !== undefined && !/\s/.test(ch)) prevCode = ch;
+    i += 1;
+  }
+  segments.push(body.slice(start));
+  return segments;
+}
+
+const LEADING_TRIVIA = /^(?:\s|\/\/[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)+/;
+const LEADING_KEY = /^(?:([A-Za-z_$][A-Za-z0-9_$]*)|'([^']+)'|"([^"]+)")\s*:/;
+
+function leadingKeyOf(segment: string): string | null {
+  const match = LEADING_KEY.exec(segment.replace(LEADING_TRIVIA, ''));
+  if (!match) return null;
+  return match[1] ?? match[2] ?? match[3] ?? null;
+}

package/src/workflow/lib/expression/context.ts

@@ -85,7 +85,7 @@ export interface XemaContext {
   };
   readonly workflow: {
     readonly key: string;
-    readonly version: string;
+    readonly revisionNumber: number;
   };
   readonly job: {
     readonly key: string;
@@ -142,7 +142,7 @@ export const EMPTY_CONTEXT_SEEDS = {
       correlationId: '',
       actor: Object.freeze({ subject: null, kind: XemaActorKind.System }),
     }),
-    workflow: Object.freeze({ key: '', version: '' }),
+    workflow: Object.freeze({ key: '', revisionNumber: 0 }),
     job: Object.freeze({ key: '', attempt: 0 }),
   }) as XemaContext,
 } as const;