@osolmaz/pi-workflows 0.9.0 → 0.10.0

package/src/workflows/loader.ts

@@ -5,9 +5,19 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
 import type { BuiltinWorkflowCatalog } from "./catalog.js";
-import { isWorkflowDefinition } from "./definition.js";
+import {
+  compileWorkflowDefinition,
+  compositionMetadata,
+  type WorkflowCompositionSourceMap,
+} from "./composition.js";
+import { defineWorkflow, isWorkflowDefinition } from "./definition.js";
 import { WorkflowSourceChangedError } from "./errors.js";
-import type { WorkflowDefinition, WorkflowSource } from "./types.js";
+import type {
+  WorkflowDefinition,
+  WorkflowIncludeDefinition,
+  WorkflowMountedSource,
+  WorkflowSource,
+} from "./types.js";
 
 const WORKFLOW_FILE_SUFFIXES = [".workflow.ts", ".workflow.js", ".workflow.mts", ".workflow.mjs"];
 
@@ -25,9 +35,12 @@ export type WorkflowSearchPaths = {
 export type ResolvedWorkflow = {
   definition: WorkflowDefinition;
   source: WorkflowSource;
+  sources: WorkflowMountedSource[];
   sourceKind: DiscoveredWorkflow["source"];
 };
 
+type SingleResolvedWorkflow = Omit<ResolvedWorkflow, "sources">;
+
 /** Directories scanned for user workflow files, in precedence order. */
 export function workflowSearchDirs(
   options: WorkflowSearchPaths,
@@ -59,6 +72,12 @@ export function workflowFileStem(filePath: string): string {
 // Alias package imports to this process's workflow API. User files can reload,
 // but their node constructors and validators remain from one engine version.
 const SELF_ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), "index");
+const BUILTINS_ENTRY = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "builtins",
+  "index",
+);
 
 /** Load a user workflow module from disk. */
 export async function loadWorkflowFile(filePath: string): Promise<WorkflowDefinition> {
@@ -66,7 +85,11 @@ export async function loadWorkflowFile(filePath: string): Promise<WorkflowDefini
   const jiti = createJiti(pathToFileURL(absolutePath).href, {
     interopDefault: true,
     moduleCache: false,
-    alias: { "@osolmaz/pi-workflows": SELF_ENTRY },
+    alias: {
+      "@osolmaz/pi-workflows/builtins": BUILTINS_ENTRY,
+      "@osolmaz/pi-workflows": SELF_ENTRY,
+      "pi-workflows": SELF_ENTRY,
+    },
   });
   const loaded = (await jiti.import(absolutePath, { default: true })) as unknown;
   if (!isWorkflowDefinition(loaded)) {
@@ -111,12 +134,42 @@ async function listWorkflowFiles(dir: string): Promise<string[]> {
     .sort();
 }
 
-/** Resolve a workflow name, stable built-in ref, or direct user file path. */
+/** Resolve a workflow and every nested include before returning it. */
 export async function resolveWorkflowRef(
   ref: string,
   options: WorkflowSearchPaths,
   catalog?: BuiltinWorkflowCatalog,
 ): Promise<ResolvedWorkflow> {
+  const root = await resolveSingleWorkflowRef(ref, options, catalog, options.cwd);
+  const sourceMap: WorkflowCompositionSourceMap = new Map([[root.definition, root.source]]);
+  const activeSources: string[] = [];
+  const definition = await resolveIncludes(
+    root.definition,
+    sourceBaseDir(root.source),
+    options,
+    catalog,
+    sourceMap,
+    activeSources,
+    sourceKey(root.source),
+  );
+  const compiled = compileWorkflowDefinition(definition, {
+    rootSource: root.source,
+    sourceMap,
+  });
+  return {
+    definition: compiled,
+    source: root.source,
+    sources: compositionMetadata(compiled)?.sources ?? [],
+    sourceKind: root.sourceKind,
+  };
+}
+
+async function resolveSingleWorkflowRef(
+  ref: string,
+  options: WorkflowSearchPaths,
+  catalog: BuiltinWorkflowCatalog | undefined,
+  relativeBase: string,
+): Promise<SingleResolvedWorkflow> {
   if (ref.startsWith("builtin:")) {
     const id = ref.slice("builtin:".length);
     const builtin = catalog?.get(id);
@@ -128,7 +181,7 @@ export async function resolveWorkflowRef(
     };
   }
   if (looksLikePath(ref)) {
-    const absolutePath = path.resolve(options.cwd, ref);
+    const absolutePath = path.resolve(relativeBase, ref);
     await fs.access(absolutePath);
     return {
       definition: await loadWorkflowFile(absolutePath),
@@ -142,30 +195,145 @@ export async function resolveWorkflowRef(
     const available = discovered.map((workflow) => workflow.name).join(", ") || "(none)";
     throw new Error(`Unknown workflow ${JSON.stringify(ref)}. Available workflows: ${available}`);
   }
-  if (match.source === "builtin") return await resolveWorkflowRef(match.ref, options, catalog);
-  const absolutePath = path.resolve(match.ref);
-  return {
-    definition: await loadWorkflowFile(absolutePath),
-    source: { kind: "file", path: absolutePath, hash: await hashWorkflowSource(absolutePath) },
-    sourceKind: match.source,
-  };
+  const resolved = await resolveSingleWorkflowRef(match.ref, options, catalog, options.cwd);
+  return { ...resolved, sourceKind: match.source };
+}
+
+async function resolveIncludes(
+  workflow: WorkflowDefinition,
+  baseDir: string | undefined,
+  options: WorkflowSearchPaths,
+  catalog: BuiltinWorkflowCatalog | undefined,
+  sourceMap: WorkflowCompositionSourceMap,
+  activeSources: string[],
+  currentSourceKey: string,
+): Promise<WorkflowDefinition> {
+  const cycleAt = activeSources.indexOf(currentSourceKey);
+  if (cycleAt >= 0) {
+    throw new Error(
+      `Workflow include source cycle: ${[...activeSources.slice(cycleAt), currentSourceKey].join(" -> ")}`,
+    );
+  }
+  activeSources.push(currentSourceKey);
+  const resolvedIncludes: Record<string, WorkflowIncludeDefinition> = {};
+  for (const [mountName, include] of Object.entries(workflow.includes ?? {})) {
+    let child: WorkflowDefinition;
+    let childSource: WorkflowSource | undefined;
+    let childBaseDir = baseDir;
+    if (typeof include.workflow === "string") {
+      if (
+        baseDir === undefined &&
+        looksLikePath(include.workflow) &&
+        !path.isAbsolute(include.workflow)
+      ) {
+        throw new Error(
+          `Built-in workflow ${workflow.name} cannot resolve relative include ${include.workflow}`,
+        );
+      }
+      const resolved = await resolveSingleWorkflowRef(
+        include.workflow,
+        options,
+        catalog,
+        baseDir ?? options.cwd,
+      );
+      child = resolved.definition;
+      childSource = resolved.source;
+      childBaseDir = sourceBaseDir(resolved.source);
+    } else {
+      child = include.workflow;
+      childSource = await sourceForDirectDefinition(child, catalog);
+      childBaseDir = childSource ? sourceBaseDir(childSource) : baseDir;
+    }
+    if (childSource !== undefined) sourceMap.set(child, childSource);
+    assertContractCompatible(include, child, mountName);
+    const childKey = childSource ? sourceKey(childSource) : `memory:${child.name}`;
+    const resolvedChild = await resolveIncludes(
+      child,
+      childBaseDir,
+      options,
+      catalog,
+      sourceMap,
+      activeSources,
+      childKey,
+    );
+    if (childSource !== undefined) sourceMap.set(resolvedChild, childSource);
+    resolvedIncludes[mountName] = { ...include, workflow: resolvedChild };
+  }
+  activeSources.pop();
+  if (Object.keys(resolvedIncludes).length === 0) return workflow;
+  const resolved = defineWorkflow({ ...workflow, includes: resolvedIncludes });
+  const ownSource = sourceMap.get(workflow);
+  if (ownSource !== undefined) sourceMap.set(resolved, ownSource);
+  return resolved;
 }
 
-/** Resolve an already persisted canonical source. */
+async function sourceForDirectDefinition(
+  workflow: WorkflowDefinition,
+  catalog?: BuiltinWorkflowCatalog,
+): Promise<WorkflowSource | undefined> {
+  const builtin = catalog?.sourceForDefinition(workflow);
+  if (builtin !== undefined) return builtin;
+  if (workflow.source === undefined) return undefined;
+  let filePath: string;
+  try {
+    filePath = fileURLToPath(workflow.source);
+  } catch {
+    throw new Error(`Workflow ${workflow.name} source must be a file URL: ${workflow.source}`);
+  }
+  return { kind: "file", path: filePath, hash: await hashWorkflowSource(filePath) };
+}
+
+function assertContractCompatible(
+  include: WorkflowIncludeDefinition,
+  child: WorkflowDefinition,
+  mountName: string,
+): void {
+  if (include.contract === undefined) return;
+  if (
+    include.contract.contractId !== undefined &&
+    child.contractId !== include.contract.contractId
+  ) {
+    throw new Error(
+      `Workflow include ${mountName} contract mismatch: expected ${include.contract.contractId}; got ${child.contractId ?? "none"}`,
+    );
+  }
+  const expected = Object.keys(include.contract.exits ?? {}).sort();
+  const actual = Object.keys(child.exits ?? {}).sort();
+  if (JSON.stringify(expected) !== JSON.stringify(actual)) {
+    throw new Error(
+      `Workflow include ${mountName} exit contract mismatch: expected ${expected.join(", ") || "none"}; got ${actual.join(", ") || "none"}`,
+    );
+  }
+  if ((include.contract.input === undefined) !== (child.input === undefined)) {
+    throw new Error(`Workflow include ${mountName} input contract mismatch`);
+  }
+}
+
+function sourceBaseDir(source: WorkflowSource): string | undefined {
+  return source.kind === "file" ? path.dirname(source.path) : undefined;
+}
+
+function sourceKey(source: WorkflowSource): string {
+  return source.kind === "file"
+    ? `file:${source.path}:${source.hash}`
+    : `builtin:${source.id}:${source.revision}`;
+}
+
+/** Resolve an already persisted canonical source and its includes. */
 export async function resolveWorkflowSource(
   source: WorkflowSource,
   catalog?: BuiltinWorkflowCatalog,
   runId = source.kind === "builtin" ? `builtin:${source.id}` : source.path,
+  options: WorkflowSearchPaths = { cwd: process.cwd() },
 ): Promise<WorkflowDefinition> {
   if (source.kind === "builtin") {
     if (catalog === undefined) throw new Error(`No built-in workflow catalog for ${source.id}`);
-    return catalog.resolve(source, runId);
+    catalog.resolve(source, runId);
+    return (await resolveWorkflowRef(`builtin:${source.id}`, options, catalog)).definition;
   }
   const actualHash = await hashWorkflowSource(source.path);
-  if (actualHash !== source.hash) {
-    throw new WorkflowSourceChangedError(runId);
-  }
-  return await loadWorkflowFile(source.path);
+  if (actualHash !== source.hash) throw new WorkflowSourceChangedError(runId);
+  return (await resolveWorkflowRef(source.path, options, catalog)).definition;
 }
 
 function looksLikePath(ref: string): boolean {

package/src/workflows/schema.ts

@@ -199,7 +199,10 @@ function assertValidEdgeShape(edge: WorkflowEdge, index: number): void {
  */
 const RESERVED_WORKFLOW_NAMES = new Set(["answer", "cancel", "list", "pause", "resume", "status"]);
 
-export function assertValidWorkflowDefinitionShape(definition: WorkflowDefinition): void {
+export function assertValidWorkflowDefinitionShape(
+  definition: WorkflowDefinition,
+  options: { compiled?: boolean } = {},
+): void {
   assertRecord(definition, "workflow");
   if (typeof definition.name !== "string" || definition.name.length === 0) {
     fail("workflow requires a name");
@@ -207,6 +210,17 @@ export function assertValidWorkflowDefinitionShape(definition: WorkflowDefinitio
   if (RESERVED_WORKFLOW_NAMES.has(definition.name)) {
     fail(`workflow name ${JSON.stringify(definition.name)} is reserved for /workflow subcommands`);
   }
+  if (definition.source !== undefined && typeof definition.source !== "string") {
+    fail("workflow source must be a string");
+  }
+  if (
+    definition.contractId !== undefined &&
+    (typeof definition.contractId !== "string" ||
+      !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(definition.contractId))
+  ) {
+    fail("workflow contractId must be a stable identifier");
+  }
+  assertOptionalFunction(definition.input, "workflow input");
   if (
     definition.title !== undefined &&
     typeof definition.title !== "string" &&
@@ -237,7 +251,14 @@ export function assertValidWorkflowDefinitionShape(definition: WorkflowDefinitio
     fail("workflow requires at least one node");
   }
   for (const [nodeId, node] of Object.entries(definition.nodes)) {
-    if (!NODE_ID_PATTERN.test(nodeId)) {
+    const segments = nodeId.split("/");
+    if (
+      segments.some(
+        (segment) =>
+          !NODE_ID_PATTERN.test(segment) || (!options.compiled && segment.startsWith("__piw_")),
+      ) ||
+      (!options.compiled && segments.length !== 1)
+    ) {
       fail(`node id ${JSON.stringify(nodeId)} must match ${NODE_ID_PATTERN.source}`);
     }
     // Ids like __proto__ or toString would collide with Object prototype
@@ -248,6 +269,45 @@ export function assertValidWorkflowDefinitionShape(definition: WorkflowDefinitio
     assertRecord(node, `node ${nodeId}`);
     assertValidNode(node, nodeId);
   }
+  if (definition.includes !== undefined) {
+    assertRecord(definition.includes, "workflow includes");
+    for (const [mountName, include] of Object.entries(definition.includes)) {
+      if (!NODE_ID_PATTERN.test(mountName) || mountName.startsWith("__piw_")) {
+        fail(`include name ${JSON.stringify(mountName)} must match ${NODE_ID_PATTERN.source}`);
+      }
+      if (Object.hasOwn(definition.nodes, mountName)) {
+        fail(`include name ${JSON.stringify(mountName)} collides with a node id`);
+      }
+      assertRecord(include, `include ${mountName}`);
+      if (
+        typeof include.workflow !== "string" &&
+        (include.workflow === null || typeof include.workflow !== "object")
+      ) {
+        fail(`include ${mountName} requires a workflow definition or reference`);
+      }
+      assertOptionalFunction(include.input, `include ${mountName} input`);
+      if (
+        include.contract !== undefined &&
+        (include.contract === null || typeof include.contract !== "object")
+      ) {
+        fail(`include ${mountName} contract must be a workflow definition`);
+      }
+    }
+  }
+  if (definition.exits !== undefined) {
+    assertRecord(definition.exits, "workflow exits");
+    if (Object.keys(definition.exits).length === 0) fail("workflow exits must not be empty");
+    for (const [exitName, exit] of Object.entries(definition.exits)) {
+      if (!NODE_ID_PATTERN.test(exitName) || exitName.startsWith("__piw_")) {
+        fail(`exit name ${JSON.stringify(exitName)} must match ${NODE_ID_PATTERN.source}`);
+      }
+      assertRecord(exit, `exit ${exitName}`);
+      if (typeof exit.from !== "string" || exit.from.length === 0) {
+        fail(`exit ${exitName} requires from`);
+      }
+      assertOptionalFunction(exit.validate, `exit ${exitName} validate`);
+    }
+  }
   if (!Array.isArray(definition.edges)) {
     fail("workflow edges must be an array");
   }

package/src/workflows/store.ts

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { ArtifactWriter, encodeValue } from "./artifacts.js";
+import { compositionMetadata } from "./composition.js";
 import type {
   WorkflowDefinition,
   WorkflowDefinitionSnapshot,
@@ -1350,6 +1351,8 @@ function createManifest(
     workflowName: state.workflowName,
     ...(state.runTitle !== undefined ? { runTitle: state.runTitle } : {}),
     ...(state.workflowSource !== undefined ? { workflowSource: state.workflowSource } : {}),
+    ...(state.workflowSources !== undefined ? { workflowSources: state.workflowSources } : {}),
+    ...(state.definitionDigest !== undefined ? { definitionDigest: state.definitionDigest } : {}),
     startedAt: state.startedAt,
     ...(state.finishedAt !== undefined ? { finishedAt: state.finishedAt } : {}),
     status: state.status,
@@ -1368,20 +1371,52 @@ function createManifest(
 }
 
 export function createDefinitionSnapshot(workflow: WorkflowDefinition): WorkflowDefinitionSnapshot {
+  const composition = compositionMetadata(workflow)?.snapshot;
   return {
     schema: DEFINITION_SNAPSHOT_SCHEMA,
     name: workflow.name,
+    ...(workflow.contractId !== undefined ? { contractId: workflow.contractId } : {}),
     startAt: workflow.startAt,
     nodes: Object.fromEntries(
-      Object.entries(workflow.nodes).map(([nodeId, node]) => [nodeId, snapshotNode(node)]),
+      Object.entries(workflow.nodes).map(([nodeId, node]) => [
+        nodeId,
+        snapshotNode(workflow, nodeId, node),
+      ]),
     ),
     edges: structuredClone(workflow.edges),
+    ...(composition !== undefined ? { composition: structuredClone(composition) } : {}),
   };
 }
 
-function snapshotNode(node: WorkflowNodeDefinition): WorkflowNodeSnapshot {
+function snapshotNode(
+  workflow: WorkflowDefinition,
+  nodeId: string,
+  node: WorkflowNodeDefinition,
+): WorkflowNodeSnapshot {
+  const composition = compositionMetadata(workflow);
+  const entry = composition?.entries[nodeId];
+  const exit = composition?.exits[nodeId];
+  const scope = Object.values(composition?.scopes ?? {})
+    .filter((candidate) => candidate.path !== "" && nodeId.startsWith(`${candidate.path}/`))
+    .sort((a, b) => b.path.length - a.path.length)[0];
+  const mountPath = entry?.mountPath ?? exit?.mountPath ?? scope?.path;
+  const localNodeId =
+    entry !== undefined
+      ? entry.mountName
+      : exit !== undefined
+        ? exit.exitName
+        : scope !== undefined
+          ? nodeId.slice(scope.path.length + 1)
+          : undefined;
   const common: WorkflowNodeSnapshot = {
     nodeType: node.nodeType,
+    ...(mountPath !== undefined ? { mountPath: mountPath.split("/") } : {}),
+    ...(localNodeId !== undefined ? { localNodeId } : {}),
+    ...(entry !== undefined
+      ? { includeTransition: "entry" as const }
+      : exit !== undefined
+        ? { includeTransition: "exit" as const }
+        : {}),
     ...(typeof node.timeoutMs === "number" ? { timeoutMs: node.timeoutMs } : {}),
     ...(node.statusDetail !== undefined ? { statusDetail: node.statusDetail } : {}),
   };

package/src/workflows/types.ts

@@ -204,12 +204,88 @@ export type WorkflowPresentationContext = {
   signal: AbortSignal;
 };
 
-export type WorkflowDefinition = {
+/** Runtime parser that also carries its normalized TypeScript result type. */
+export type WorkflowValueParser<T> = (value: unknown) => MaybePromise<T>;
+
+export type WorkflowExitDefinition<TOutput = unknown> = {
+  /** Successful terminal node whose output leaves through this exit. */
+  from: string;
+  /** Optional runtime output normalizer and validator. */
+  validate?: WorkflowValueParser<TOutput>;
+};
+
+export type WorkflowExitMap = Record<string, WorkflowExitDefinition>;
+
+export type WorkflowInputOf<TWorkflow> =
+  TWorkflow extends WorkflowDefinition<infer TInput, any, any> ? TInput : unknown;
+
+export type WorkflowExitOutputs<TWorkflow> =
+  TWorkflow extends WorkflowDefinition<any, infer TExits, any>
+    ? {
+        [K in keyof TExits]: TExits[K] extends WorkflowExitDefinition<infer TOutput>
+          ? TOutput
+          : unknown;
+      }
+    : Record<string, unknown>;
+
+export type WorkflowIncludedResult<TWorkflow> = {
+  [K in keyof WorkflowExitOutputs<TWorkflow>]: {
+    exit: K;
+    output: WorkflowExitOutputs<TWorkflow>[K];
+  };
+}[keyof WorkflowExitOutputs<TWorkflow>];
+
+export type WorkflowIncludeDefinition<
+  TWorkflow extends WorkflowDefinition<any, any, any> = WorkflowDefinition<any, any, any>,
+> = {
+  /** Imported child definition or dynamic discovered name/path. */
+  workflow: TWorkflow | string;
+  /** Pure parent-to-child input mapping, evaluated on every mount entry. */
+  input?: (context: WorkflowNodeContext) => MaybePromise<WorkflowInputOf<TWorkflow>>;
+  /** Optional direct definition that supplies the contract for a dynamic reference. */
+  contract?: TWorkflow;
+};
+
+export type WorkflowIncludeMap = Record<string, WorkflowIncludeDefinition>;
+
+export type WorkflowIncludeExitReference<TIncludes extends WorkflowIncludeMap> = {
+  [K in keyof TIncludes & string]: TIncludes[K] extends WorkflowIncludeDefinition<infer TWorkflow>
+    ? `${K}.${Extract<keyof WorkflowExitOutputs<TWorkflow>, string>}`
+    : never;
+}[keyof TIncludes & string];
+
+export type WorkflowTypedEdge<
+  TNodes extends Record<string, WorkflowNodeDefinition>,
+  TIncludes extends WorkflowIncludeMap,
+> =
+  | {
+      from: (keyof TNodes & string) | WorkflowIncludeExitReference<TIncludes>;
+      to: (keyof TNodes & string) | (keyof TIncludes & string);
+    }
+  | {
+      from: keyof TNodes & string;
+      switch: {
+        on: string;
+        cases: Record<string, (keyof TNodes & string) | (keyof TIncludes & string)>;
+      };
+    };
+
+export type WorkflowDefinition<
+  TInput = any,
+  TExits extends WorkflowExitMap = WorkflowExitMap,
+  TIncludes extends WorkflowIncludeMap = WorkflowIncludeMap,
+> = {
   name: string;
+  /** Module URL used to attest directly imported child workflow files. */
+  source?: string;
+  /** Stable public input-and-exit contract identity for compatible overrides. */
+  contractId?: string;
+  /** Optional runtime input normalizer and validator. */
+  input?: WorkflowValueParser<TInput>;
   /** Optional human-readable run title (static or derived from input). */
   title?:
     | string
-    | ((context: { input: unknown; workflowName: string }) => MaybePromise<string | undefined>);
+    | ((context: { input: TInput; workflowName: string }) => MaybePromise<string | undefined>);
   /**
    * Optional instructions for a normal assistant response after the run ends.
    * The Pi extension resolves this only after the final state is persisted;
@@ -220,6 +296,8 @@ export type WorkflowDefinition = {
     | ((context: WorkflowPresentationContext) => MaybePromise<string | undefined>);
   startAt: string;
   nodes: Record<string, WorkflowNodeDefinition>;
+  includes?: TIncludes;
+  exits?: TExits;
   edges: WorkflowEdge[];
   /** Guard against unbounded loops. Defaults to the engine's maxSteps. */
   maxSteps?: number;
@@ -308,6 +386,24 @@ export type WorkflowSource =
   | { kind: "builtin"; id: string; revision: string }
   | { kind: "file"; path: string; hash: string };
 
+export type WorkflowMountedSource = {
+  mountPath: string[];
+  workflowName: string;
+  source: WorkflowSource;
+};
+
+export type WorkflowMountSnapshot = {
+  mountPath: string[];
+  workflowName: string;
+  entryNode: string;
+  exits: Record<string, string>;
+  maxSteps?: number;
+};
+
+export type WorkflowCompositionSnapshot = {
+  mounts: WorkflowMountSnapshot[];
+};
+
 export type WorkflowRunState = {
   schema: "pi-workflows.run-state.v1";
   /**
@@ -329,6 +425,10 @@ export type WorkflowRunState = {
   runTitle?: string;
   /** Stable built-in identity or immutable file source used by this run. */
   workflowSource?: WorkflowSource;
+  /** Sorted immutable sources used by included workflow mounts. */
+  workflowSources?: WorkflowMountedSource[];
+  /** SHA-256 of the fully resolved definition snapshot. */
+  definitionDigest?: string;
   /** Legacy fields accepted only by the bounded built-in migration. */
   workflowPath?: string;
   workflowHash?: string;
@@ -360,14 +460,19 @@ export type WorkflowNodeSnapshot = {
   summary?: string;
   expectedOutput?: string;
   actionExecution?: "function" | "shell";
+  mountPath?: string[];
+  localNodeId?: string;
+  includeTransition?: "entry" | "exit";
 };
 
 export type WorkflowDefinitionSnapshot = {
   schema: "pi-workflows.definition-snapshot.v1";
   name: string;
+  contractId?: string;
   startAt: string;
   nodes: Record<string, WorkflowNodeSnapshot>;
   edges: WorkflowEdge[];
+  composition?: WorkflowCompositionSnapshot;
 };
 
 export type WorkflowTraceEvent = {
@@ -460,6 +565,8 @@ export type WorkflowRunManifest = {
   workflowName: string;
   runTitle?: string;
   workflowSource?: WorkflowSource;
+  workflowSources?: WorkflowMountedSource[];
+  definitionDigest?: string;
   startedAt: string;
   finishedAt?: string;
   status: WorkflowRunStatus;