pi-workflow-engine 0.10.2 → 0.11.0

package/.pi/extensions/pi-workflow-engine/src/engine.ts

@@ -1,19 +1,22 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { bindPipeline, parallel, Semaphore } from "./concurrency.ts";
-import { linkAbortSignal } from "./cancellation.ts";
+import { bindParallel, bindPipeline, Semaphore } from "./concurrency.ts";
+import { linkAbortSignal, throwIfAborted } from "./cancellation.ts";
 import { createBudget } from "./budget.ts";
-import { runAgent, type RunContext } from "./agent-runner.ts";
+import { runAgent, type AgentExecutionOptions, type RunContext } from "./agent-runner.ts";
 import { ProgressTracker } from "./progress.ts";
-import { createPerfRecorder, type PerfSnapshot } from "./perf.ts";
-import { createWorkflowUsageRecorder } from "./usage.ts";
-import { defaultConcurrency, resolveWorkflowRunOptions } from "./options.ts";
-import type { AgentOptions, WorkflowApi, WorkflowModule, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
+import { createPerfRecorder, type PerfSink, type PerfSnapshot } from "./perf.ts";
+import { createWorkflowUsageRecorder, type WorkflowUsageSink } from "./usage.ts";
+import { resolveWorkflowRunOptions, type ResolvedWorkflowRunOptions } from "./options.ts";
+import type { AgentOptions, LoadedWorkflow, WorkflowApi, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
 import { WorkflowInspector } from "./ui/workflow-inspector.ts";
 import { createWorkflowJournal, createWorkflowRunId, pruneWorkflowJournals, workflowJournalPath } from "./journal.ts";
 import { WorktreeRegistry } from "./worktree.ts";
-
-/** Default global cap on concurrent agents per run. */
-const DEFAULT_CONCURRENCY = defaultConcurrency();
+import { runFinalizers } from "./finalizers.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import {
+  captureWorkflowResumeContext,
+  type AgentResumeBaseContext,
+} from "./resume-context.ts";
 
 /** The workflow-facing slice of the progress tracker (satisfied by `ProgressTracker`). */
 export interface WorkflowProgress {
@@ -22,6 +25,9 @@ export interface WorkflowProgress {
   event(event: WorkflowProgressEvent): void;
 }
 
+/** Engine state shared by the workflow and its individual agent calls. */
+export type WorkflowRunContext = RunContext;
+
 /** Per-context knobs threaded through `runWorkflowWithContext` (and re-derived for each sub-workflow). */
 export interface WorkflowContextOptions {
   /** Controller whose `.signal` equals `rc.signal`; aborts in-flight `parallel` siblings on failure. */
@@ -29,7 +35,7 @@ export interface WorkflowContextOptions {
   /** Eager-submission cap for `parallel`. */
   submissionLimit: number;
   /** Resolve a sub-workflow reference for `api.workflow()`. Omit to disable composition. */
-  resolveWorkflow?: (ref: WorkflowRef) => Promise<WorkflowModule>;
+  resolveWorkflow?: (ref: WorkflowRef) => Promise<LoadedWorkflow>;
   /** Nesting depth. Sub-workflows run at depth >= 1, where `api.workflow()` rejects. */
   depth?: number;
   /** Prefix applied to phase titles so sub-workflow phases nest as "<name> ▸ <title>". */
@@ -38,59 +44,86 @@ export interface WorkflowContextOptions {
   progressNamespace?: string;
 }
 
+type Outcome<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: unknown };
+
+export interface WorkflowEngineDependencies {
+  readonly worktrees?: WorktreeRegistry;
+}
+
 /**
  * Run a workflow module: build the per-run primitives (binding agent/parallel/pipeline
  * to a shared semaphore + progress tracker), invoke the workflow, return its result.
  */
 export async function runWorkflow(
   ctx: ExtensionContext,
-  mod: WorkflowModule,
+  mod: LoadedWorkflow,
   args: string,
   options: WorkflowRunOptions = {},
+  dependencies: WorkflowEngineDependencies = {},
+): Promise<unknown> {
+  return await runResolvedWorkflow(ctx, mod, args, resolveWorkflowRunOptions(options), dependencies);
+}
+
+/** Execute an options-normalized workflow without re-reading environment defaults. */
+export async function runResolvedWorkflow(
+  ctx: ExtensionContext,
+  mod: LoadedWorkflow,
+  args: string,
+  resolvedOptions: ResolvedWorkflowRunOptions,
+  dependencies: WorkflowEngineDependencies = {},
 ): Promise<unknown> {
-  const resolvedOptions = resolveWorkflowRunOptions(options);
   const progress = new ProgressTracker(ctx, mod.meta.name);
   const progressSource = { snapshot: () => progress.snapshot() };
-  resolvedOptions.onProgressSource?.(progressSource);
-  if (resolvedOptions.inspect && ctx.hasUI) {
-    void ctx.ui
-      .custom<void>(
-        (tui, theme, _keybindings, done) => new WorkflowInspector(() => progress.snapshot(), tui, theme, () => done(undefined)),
-        { overlay: true, overlayOptions: { anchor: "right-center", width: "60%", maxHeight: "80%", margin: 1 } },
-      )
-      .catch((error: unknown) => progress.log(`inspector failed: ${error instanceof Error ? error.message : String(error)}`));
-  }
-
   const perf = resolvedOptions.perfRecorder ?? createPerfRecorder(resolvedOptions.perf);
   const usage = createWorkflowUsageRecorder();
-  const budget = createBudget(resolvedOptions.budget ?? null, usage);
+  const budget = createBudget(resolvedOptions.budget, usage);
   const runId = resolvedOptions.runId ?? createWorkflowRunId();
   const journalPath = workflowJournalPath(ctx.cwd, runId);
   const resumePath = resolvedOptions.resumeFromRunId ? workflowJournalPath(ctx.cwd, resolvedOptions.resumeFromRunId) : undefined;
-  const journal = await createWorkflowJournal({ resumePath, writePath: journalPath });
-  const worktrees = new WorktreeRegistry(ctx.cwd);
-  resolvedOptions.onRunMetadata?.({ runId, resumedFromRunId: resolvedOptions.resumeFromRunId, journalPath });
-  progress.log(resolvedOptions.resumeFromRunId ? `run id: ${runId} (resuming from ${resolvedOptions.resumeFromRunId})` : `run id: ${runId}`);
+  const worktrees = dependencies.worktrees ?? new WorktreeRegistry(ctx.cwd);
   const runAbortController = new AbortController();
   const unlinkContextAbortSignal = linkAbortSignal(ctx.signal, runAbortController);
   const unlinkOptionAbortSignal = linkAbortSignal(resolvedOptions.signal, runAbortController);
-  const rc: RunContext = {
-    cwd: ctx.cwd,
-    hostModel: ctx.model,
-    modelRegistry: ctx.modelRegistry,
-    semaphore: new Semaphore(resolvedOptions.concurrency ?? DEFAULT_CONCURRENCY),
-    progress,
-    signal: runAbortController.signal,
-    perf,
-    usage,
-    budget,
-    journal,
-    worktrees,
-  };
+  const workflowOutcome = await captureOutcome(async () => {
+    await notifyLifecycleObserver(progress, "progress source callback", () => resolvedOptions.onProgressSource?.(progressSource));
+    if (resolvedOptions.inspect && ctx.hasUI) {
+      void ctx.ui
+        .custom<void>(
+          (tui, theme, _keybindings, done) => new WorkflowInspector(() => progress.snapshot(), tui, theme, () => done(undefined)),
+          { overlay: true, overlayOptions: { anchor: "right-center", width: "60%", maxHeight: "80%", margin: 1 } },
+        )
+        .catch((error: unknown) => {
+          try {
+            progress.log(`inspector failed: ${unknownErrorMessage(error)}`);
+          } catch {
+            // Inspector reporting is detached and must never become another rejection.
+          }
+        });
+    }
+
+    const journal = await createWorkflowJournal({ resumePath, writePath: journalPath });
+    await notifyLifecycleObserver(progress, "run metadata callback", () =>
+      resolvedOptions.onRunMetadata?.({ runId, resumedFromRunId: resolvedOptions.resumeFromRunId, journalPath }),
+    );
+    progress.log(resolvedOptions.resumeFromRunId ? `run id: ${runId} (resuming from ${resolvedOptions.resumeFromRunId})` : `run id: ${runId}`);
+    const rc: WorkflowRunContext = {
+      cwd: ctx.cwd,
+      hostModel: ctx.model,
+      modelRegistry: ctx.modelRegistry,
+      semaphore: new Semaphore(resolvedOptions.concurrency),
+      progress,
+      signal: runAbortController.signal,
+      perf,
+      usage,
+      budget,
+      journal,
+      worktrees,
+    };
 
-  try {
     // perf.total_ms wraps the whole tree: sub-workflows run inside this span via api.workflow().
-    return await perf.time("workflow.total_ms", () =>
+    return perf.time("workflow.total_ms", () =>
       runWorkflowWithContext(rc, progress, mod, args, {
         abortController: runAbortController,
         submissionLimit: resolvedOptions.parallelSubmissionLimit ?? resolvedOptions.concurrency * 2,
@@ -99,47 +132,132 @@ export async function runWorkflow(
         progressPrefix: "",
       }),
     );
-  } finally {
-    try {
-      resolvedOptions.onUsageSnapshot?.(usage.snapshot());
-      const snapshot = perf.snapshot();
-      if (resolvedOptions.perf) {
-        resolvedOptions.onPerfSnapshot?.(snapshot);
-        progress.log(formatPerfSummary(snapshot));
-      }
-      progress.done();
-      resolvedOptions.onProgressSnapshot?.(progress.snapshot());
-    } finally {
-      resolvedOptions.onProgressSource?.(undefined);
-      unlinkContextAbortSignal();
-      unlinkOptionAbortSignal();
-      const cleanupResults = await worktrees.removeAll();
-      for (const result of cleanupResults) {
-        if (!result.ok) {
-          progress.log(`failed to remove isolated worktree ${result.path} (${result.error ?? (result.stderr.trim() || "unknown error")})`);
-        }
-      }
-      await pruneWorkflowJournals(ctx.cwd);
-    }
+  });
+
+  const finalizationOutcome = await captureOutcome(() =>
+    finalizeWorkflowRun({
+      cwd: ctx.cwd,
+      options: resolvedOptions,
+      perf,
+      usage,
+      progress,
+      worktrees,
+      unlinkSignals: [unlinkContextAbortSignal, unlinkOptionAbortSignal],
+    }),
+  );
+
+  if (workflowOutcome.ok) {
+    if (finalizationOutcome.ok) return workflowOutcome.value;
+    throw finalizationOutcome.error;
+  }
+  if (finalizationOutcome.ok) throw workflowOutcome.error;
+  throw combinedWorkflowError(workflowOutcome.error, finalizationOutcome.error);
+}
+
+async function captureOutcome<T>(operation: () => Promise<T>): Promise<Outcome<T>> {
+  try {
+    return { ok: true, value: await operation() };
+  } catch (error) {
+    return { ok: false, error };
   }
 }
 
+interface WorkflowFinalizationInput {
+  readonly cwd: string;
+  readonly options: ResolvedWorkflowRunOptions;
+  readonly perf: PerfSink;
+  readonly usage: WorkflowUsageSink;
+  readonly progress: ProgressTracker;
+  readonly worktrees: WorktreeRegistry;
+  readonly unlinkSignals: readonly (() => void)[];
+}
+
+async function finalizeWorkflowRun(input: WorkflowFinalizationInput): Promise<void> {
+  await runFinalizers(
+    [
+      {
+        name: "usage snapshot callback",
+        criticality: "best-effort",
+        run: () => input.options.onUsageSnapshot?.(input.usage.snapshot()),
+      },
+      {
+        name: "performance snapshot callback",
+        criticality: "best-effort",
+        run: async () => {
+          if (!input.options.perf) return;
+          const snapshot = input.perf.snapshot();
+          await input.options.onPerfSnapshot?.(snapshot);
+          input.progress.log(formatPerfSummary(snapshot));
+        },
+      },
+      ...input.unlinkSignals.map((run, index) => ({
+        name: `abort signal unlink ${index + 1}`,
+        criticality: "required" as const,
+        run,
+      })),
+      {
+        name: "worktree cleanup",
+        criticality: "required",
+        run: () => input.worktrees.removeAll(),
+      },
+      { name: "journal pruning", criticality: "best-effort", run: () => pruneWorkflowJournals(input.cwd) },
+      { name: "progress completion", criticality: "best-effort", run: () => input.progress.done() },
+      {
+        name: "progress snapshot callback",
+        criticality: "best-effort",
+        run: () => input.options.onProgressSnapshot?.(input.progress.snapshot()),
+      },
+      {
+        name: "progress source clear",
+        criticality: "best-effort",
+        run: () => input.options.onProgressSource?.(undefined),
+      },
+    ],
+    {
+      onBestEffortFailure: (failure) => {
+        try {
+          input.progress.log(`${failure.name} failed: ${unknownErrorMessage(failure.error)}`);
+        } catch {
+          // Observer failures must never replace the workflow outcome.
+        }
+      },
+    },
+  );
+}
+
+function combinedWorkflowError(workflowError: unknown, finalizationError: unknown): AggregateError {
+  return new AggregateError(
+    [workflowError, finalizationError],
+    `Workflow failed: ${unknownErrorMessage(workflowError)}; finalization also failed: ${unknownErrorMessage(finalizationError)}`,
+  );
+}
+
 /**
  * Build the `WorkflowApi` from an existing run context and invoke the module. Reused for both
  * the top-level run and every `api.workflow()` sub-step, so children share the parent's semaphore,
  * abort signal, and perf sink. No setup/teardown of its own — that belongs to `runWorkflow`.
  */
 export async function runWorkflowWithContext(
-  rc: RunContext,
+  rc: WorkflowRunContext,
   progress: WorkflowProgress,
-  mod: WorkflowModule,
+  mod: LoadedWorkflow,
   args: string,
   opts: WorkflowContextOptions,
 ): Promise<unknown> {
   const depth = opts.depth ?? 0;
   const scope = createWorkflowScope(progress, opts.progressPrefix ?? "", opts.progressNamespace);
+  const resumeContext: AgentResumeBaseContext = {
+    workflow: await captureWorkflowResumeContext(mod, rc.signal),
+  };
 
-  const agent = ((prompt: string, agentOpts?: AgentOptions) => runAgent(rc, prompt, scope.agentOptions(agentOpts))) as WorkflowApi["agent"];
+  const agent = ((prompt: string, agentOpts?: AgentOptions) => {
+    const scopedOptions = scope.agentOptions(agentOpts);
+    const executionOptions: AgentExecutionOptions =
+      scopedOptions.isolation === "worktree" && mod.isolatedWorktreeBaseline !== undefined
+        ? { ...scopedOptions, worktreeBaseline: mod.isolatedWorktreeBaseline }
+        : scopedOptions;
+    return runAgent(rc, prompt, executionOptions, resumeContext);
+  }) as WorkflowApi["agent"];
 
   const workflow: WorkflowApi["workflow"] =
     depth >= 1
@@ -171,12 +289,11 @@ export async function runWorkflowWithContext(
   const api: WorkflowApi = {
     agent,
     workflow,
-    parallel: (thunks) =>
-      parallel(thunks, {
-        signal: rc.signal,
-        abortController: opts.abortController,
-        limit: opts.submissionLimit,
-      }),
+    parallel: bindParallel({
+      signal: rc.signal,
+      abortController: opts.abortController,
+      limit: opts.submissionLimit,
+    }),
     pipeline: bindPipeline({ signal: rc.signal, abortController: opts.abortController }),
     phase: scope.phase,
     log: scope.log,
@@ -187,6 +304,7 @@ export async function runWorkflowWithContext(
     signal: rc.signal,
   };
 
+  throwIfAborted(rc.signal);
   return await mod.default(api);
 }
 
@@ -242,3 +360,19 @@ function formatPerfSummary(snapshot: PerfSnapshot): string {
     .map((aggregate) => `${aggregate.name} ${Math.round(aggregate.total)}ms`);
   return parts.length > 0 ? `perf: ${parts.join(", ")}` : "perf: no samples";
 }
+
+async function notifyLifecycleObserver(
+  progress: ProgressTracker,
+  name: string,
+  notify: () => void | Promise<void>,
+): Promise<void> {
+  try {
+    await notify();
+  } catch (error) {
+    try {
+      progress.log(`${name} failed: ${unknownErrorMessage(error)}`);
+    } catch {
+      // Lifecycle observers are advisory and must not replace the workflow outcome.
+    }
+  }
+}

package/.pi/extensions/pi-workflow-engine/src/finalizers.ts

@@ -0,0 +1,66 @@
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+export type FinalizerCriticality = "required" | "best-effort";
+
+export interface Finalizer {
+  readonly name: string;
+  readonly criticality: FinalizerCriticality;
+  readonly run: () => void | Promise<void>;
+}
+
+export interface FinalizerFailure {
+  readonly name: string;
+  readonly criticality: FinalizerCriticality;
+  readonly error: unknown;
+}
+
+export interface RunFinalizersOptions {
+  readonly onBestEffortFailure?: (failure: FinalizerFailure) => void;
+}
+
+export class RequiredFinalizerError extends AggregateError {
+  readonly failures: readonly FinalizerFailure[];
+
+  constructor(failures: readonly FinalizerFailure[]) {
+    super(
+      failures.map((failure) => failure.error),
+      `Required workflow finalization failed: ${failures.map((failure) => `${failure.name} (${unknownErrorMessage(failure.error)})`).join(", ")}`,
+    );
+    this.name = "RequiredFinalizerError";
+    this.failures = failures;
+  }
+}
+
+/** Execute every finalizer once, reporting advisory failures and aggregating only required failures. */
+export async function runFinalizers(
+  finalizers: readonly Finalizer[],
+  options: RunFinalizersOptions = {},
+): Promise<readonly FinalizerFailure[]> {
+  const requiredFailures: FinalizerFailure[] = [];
+  const bestEffortFailures: FinalizerFailure[] = [];
+
+  for (const finalizer of finalizers) {
+    try {
+      await finalizer.run();
+    } catch (error) {
+      const failure: FinalizerFailure = {
+        name: finalizer.name,
+        criticality: finalizer.criticality,
+        error,
+      };
+      if (finalizer.criticality === "required") {
+        requiredFailures.push(failure);
+        continue;
+      }
+      bestEffortFailures.push(failure);
+      try {
+        options.onBestEffortFailure?.(failure);
+      } catch {
+        // Failure observers are advisory and must not change finalization semantics.
+      }
+    }
+  }
+
+  if (requiredFailures.length > 0) throw new RequiredFinalizerError(requiredFailures);
+  return bestEffortFailures;
+}

package/.pi/extensions/pi-workflow-engine/src/identity-canonicalization.ts

@@ -0,0 +1,138 @@
+export type IdentityCanonicalization =
+  | { readonly kind: "verified"; readonly value: string }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export interface IdentityCanonicalizationOptions {
+  readonly maxBytes?: number;
+  readonly maxDepth?: number;
+  readonly maxNodes?: number;
+}
+
+const DEFAULT_MAX_BYTES = 1 << 20;
+const DEFAULT_MAX_DEPTH = 64;
+const DEFAULT_MAX_NODES = 16_384;
+
+/**
+ * Produce a deterministic, bounded identity for JSON-like data.
+ *
+ * Replay inputs are not trusted: schemas and tool metadata can contain cycles,
+ * accessors, proxies, or values JSON cannot represent. Those inputs disable
+ * replay instead of throwing or being silently collapsed to the same key.
+ */
+export function canonicalizeIdentity(
+  value: unknown,
+  options: IdentityCanonicalizationOptions = {},
+): IdentityCanonicalization {
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
+  const active = new WeakSet<object>();
+  const chunks: string[] = [];
+  let bytes = 0;
+  let nodes = 0;
+
+  const append = (chunk: string): void => {
+    bytes += Buffer.byteLength(chunk);
+    if (bytes > maxBytes) throw new IdentityCanonicalizationError(`identity exceeded ${maxBytes} bytes`);
+    chunks.push(chunk);
+  };
+
+  const visit = (current: unknown, depth: number): void => {
+    nodes += 1;
+    if (nodes > maxNodes) throw new IdentityCanonicalizationError(`identity exceeded ${maxNodes} values`);
+    if (depth > maxDepth) throw new IdentityCanonicalizationError(`identity exceeded ${maxDepth} levels`);
+
+    if (current === null) {
+      append("n;");
+      return;
+    }
+    switch (typeof current) {
+      case "undefined":
+        append("u;");
+        return;
+      case "boolean":
+        append(current ? "b1;" : "b0;");
+        return;
+      case "number":
+        if (!Number.isFinite(current)) throw new IdentityCanonicalizationError("identity contains a non-finite number");
+        append(`d${Object.is(current, -0) ? "-0" : String(current)};`);
+        return;
+      case "string":
+        append(`s${Buffer.byteLength(current)}:${current};`);
+        return;
+      case "bigint":
+      case "function":
+      case "symbol":
+        throw new IdentityCanonicalizationError(`identity contains unsupported ${typeof current} data`);
+      case "object":
+        break;
+    }
+
+    if (active.has(current)) throw new IdentityCanonicalizationError("identity contains a cycle");
+    active.add(current);
+    try {
+      const prototype = Object.getPrototypeOf(current);
+      if (Array.isArray(current)) {
+        if (prototype !== Array.prototype) throw new IdentityCanonicalizationError("identity contains an array with a custom prototype");
+        const descriptors = Object.getOwnPropertyDescriptors(current);
+        const ownKeys = Reflect.ownKeys(current);
+        if (ownKeys.some((key) => typeof key === "symbol")) {
+          throw new IdentityCanonicalizationError("identity contains symbol keys");
+        }
+        if (ownKeys.some((key) => typeof key === "string" && key !== "length" && !isArrayIndex(key, current.length))) {
+          throw new IdentityCanonicalizationError("identity array contains custom properties");
+        }
+        append(`a${current.length}[`);
+        for (let index = 0; index < current.length; index++) {
+          const descriptor = descriptors[String(index)];
+          if (!descriptor) {
+            append("h;");
+            continue;
+          }
+          if (!("value" in descriptor)) throw new IdentityCanonicalizationError("identity contains an array accessor");
+          visit(descriptor.value, depth + 1);
+        }
+        append("];");
+        return;
+      }
+
+      if (prototype !== Object.prototype && prototype !== null) {
+        throw new IdentityCanonicalizationError("identity contains an object with a custom prototype");
+      }
+      const descriptors = Object.getOwnPropertyDescriptors(current);
+      const ownKeys = Reflect.ownKeys(current);
+      if (ownKeys.some((key) => typeof key === "symbol")) {
+        throw new IdentityCanonicalizationError("identity contains symbol keys");
+      }
+      const keys = Object.keys(descriptors).sort();
+      append(`o${keys.length}{`);
+      for (const key of keys) {
+        const descriptor = descriptors[key]!;
+        if (!("value" in descriptor)) throw new IdentityCanonicalizationError(`identity property ${key} is an accessor`);
+        append(`k${Buffer.byteLength(key)}:${key};`);
+        append(`p${descriptor.enumerable ? 1 : 0}${descriptor.configurable ? 1 : 0}${descriptor.writable ? 1 : 0};`);
+        visit(descriptor.value, depth + 1);
+      }
+      append("};");
+    } finally {
+      active.delete(current);
+    }
+  };
+
+  try {
+    visit(value, 0);
+    return { kind: "verified", value: chunks.join("") };
+  } catch (error) {
+    return {
+      kind: "unverifiable",
+      reason: error instanceof IdentityCanonicalizationError ? error.message : "identity inspection failed",
+    };
+  }
+}
+
+class IdentityCanonicalizationError extends Error {}
+
+function isArrayIndex(key: string, length: number): boolean {
+  const index = Number(key);
+  return Number.isInteger(index) && index >= 0 && index < length && String(index) === key;
+}

package/.pi/extensions/pi-workflow-engine/src/identity-fingerprint.ts

@@ -0,0 +1,15 @@
+import { createHash } from "node:crypto";
+import { canonicalizeIdentity } from "./identity-canonicalization.ts";
+
+export function hashIdentity(value: unknown): string {
+  const canonical = canonicalizeIdentity(value);
+  if (canonical.kind === "unverifiable") throw new Error(canonical.reason);
+  return `sha256:${createHash("sha256").update(canonical.value).digest("hex")}`;
+}
+
+export function inspectableFunctionSource(value: unknown, label: string): string {
+  if (typeof value !== "function") throw new Error(`${label} is not a function`);
+  const source = Function.prototype.toString.call(value);
+  if (source.length === 0 || source.includes("[native code]")) throw new Error(`${label} has no inspectable source`);
+  return source;
+}

package/.pi/extensions/pi-workflow-engine/src/inline-workflow.ts

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
-import type { WorkflowApi, WorkflowMeta, WorkflowModule } from "./types.ts";
+import { createHash } from "node:crypto";
+import type { LoadedWorkflow, WorkflowApi } from "./types.ts";
 import { parseWorkflowMeta } from "./workflow-module.ts";
 
 /**
@@ -28,7 +29,7 @@ type AsyncFunctionConstructor = new (...args: string[]) => InlineWorkflowExecuto
 
 const AsyncFunction = Object.getPrototypeOf(async function inlineWorkflowCompilerSentinel() {}).constructor as AsyncFunctionConstructor;
 
-export function compileInlineWorkflow(source: string): WorkflowModule {
+export function compileInlineWorkflow(source: string): LoadedWorkflow {
   rejectForbiddenModuleSyntax(source);
   const metaLiteral = extractMetaLiteral(source);
   const parsedMeta = parseWorkflowMeta(metaLiteral.value);
@@ -36,7 +37,11 @@ export function compileInlineWorkflow(source: string): WorkflowModule {
 
   const defaultExpression = extractDefaultWorkflowExpression(source, metaLiteral.endOffset);
   const executor = compileExecutor(defaultExpression);
-  return { meta: parsedMeta.meta, default: (api) => executor(api, Type) };
+  return {
+    meta: parsedMeta.meta,
+    default: (api) => executor(api, Type),
+    source: { kind: "fingerprint", fingerprint: createHash("sha256").update(source).digest("hex") },
+  };
 }
 
 export function extractMetaLiteral(source: string): InlineMetaLiteral {