pi-workflow-engine 0.12.0 → 1.0.0

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

@@ -1,24 +1,25 @@
-import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, type AdvisoryCandidate, type AdvisoryFinding, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
-import { compactResults } from "./concurrency.ts";
+import { AdvisoryCandidatesSchema, AdvisoryVerdictSchema, formatAdvisoryLocation, type AdvisoryCandidate, type AdvisoryFinding, type IdentifiedAdvisoryCandidate, type AdvisoryLocation, type AdvisoryReport, type AdvisoryVerdict } from "./advisory-schema.ts";
+import { AdvisorySynthesisSchema, SYNTHESIS_ID_INSTRUCTIONS, withAdvisoryCoverage, collectAdvisoryStage, dedupeCandidates, identifyCandidates, uniqueLocations, type AdvisoryStageCoverage, type AdvisorySynthesis } from "./advisory-evidence.ts";
 import type { AgentOptions, WorkflowApi, WorkflowProgressEvent, WorkflowRunStats } from "./types.ts";
 
+
 export interface AdvisoryLens {
   label: string;
   category: string;
   text: string;
 }
 
-export type AdvisoryVerified<Candidate extends AdvisoryCandidate = AdvisoryCandidate> = Candidate & {
+export type AdvisoryVerified = IdentifiedAdvisoryCandidate & {
   verdict: AdvisoryVerdict["verdict"];
   evidence: string[];
-  confidence?: AdvisoryVerdict["confidence"];
+  challenge?: import("./advisory-challenge.ts").ChallengeRecord;
 };
 
-export interface LensVerificationPipelineResult<Verified> {
-  verified: Verified[];
+export interface LensVerificationPipelineResult {
+  verified: AdvisoryVerified[];
   rawCandidates: number;
   dropped: number;
-  refuted: number;
+  coverage: AdvisoryStageCoverage[];
 }
 
 /** Default concrete read/inspect tools for advisory workflows. */
@@ -47,20 +48,14 @@ export function publishVerifiedKeptProgress(
   api.log(`${verified} verified → ${kept} kept`);
 }
 
-export type AdvisorySchedulingMode = "pipeline" | "finder-barrier";
-
-export interface LensVerificationPipelineOptions<Lens extends AdvisoryLens, Verified extends AdvisoryVerified> {
-  api: Pick<WorkflowApi, "agent" | "parallel" | "pipeline" | "progress" | "log">;
-  lenses: readonly Lens[];
+export interface LensVerificationPipelineOptions {
+  api: Pick<WorkflowApi, "agent" | "parallel" | "phase" | "progress" | "log">;
+  lenses: readonly AdvisoryLens[];
   perLens: number;
-  tools?: AgentOptions["tools"];
-  toolHints?: AgentOptions["toolHints"];
-  finderPhase?: string;
-  verifierPhase?: string;
-  schedulingMode?: AdvisorySchedulingMode;
-  finderPrompt(lens: Lens): string;
-  verifierPrompt(candidate: AdvisoryCandidate): string;
-  makeVerified(candidate: AdvisoryCandidate, lens: Lens, verdict: AdvisoryVerdict): Verified;
+  finderPhase?: "Find" | "Hypothesize";
+  finderPrompt(lens: AdvisoryLens): string;
+  verifierPrompt(candidate: IdentifiedAdvisoryCandidate): string;
+  boundCandidate?(candidate: IdentifiedAdvisoryCandidate, lens: AdvisoryLens): IdentifiedAdvisoryCandidate | undefined;
 }
 
 export interface AdvisoryBackfillDefaults {
@@ -68,117 +63,124 @@ export interface AdvisoryBackfillDefaults {
   recommendation?: string;
 }
 
-interface FoundForLens<Lens> {
-  lens: Lens;
-  candidates: AdvisoryCandidate[];
-}
-
-interface NovelCandidate<Lens> {
-  lens: Lens;
-  candidate: AdvisoryCandidate;
-}
-
-export async function runLensVerificationPipeline<Lens extends AdvisoryLens, Verified extends AdvisoryVerified>(
-  options: LensVerificationPipelineOptions<Lens, Verified>,
-): Promise<LensVerificationPipelineResult<Verified>> {
-  const {
-    api,
-    lenses,
-    perLens,
-    tools = DEFAULT_ADVISORY_TOOLS,
-    toolHints = DEFAULT_ADVISORY_TOOL_HINTS,
-    finderPhase = "Find",
-    verifierPhase = "Verify",
-    schedulingMode = "pipeline",
-    finderPrompt,
-    verifierPrompt,
-    makeVerified,
-  } = options;
-  const seen = new Set<string>();
+/** Finish all discovery before verification competes for the shared agent limit. */
+export async function runLensVerificationPipeline(
+  options: LensVerificationPipelineOptions,
+): Promise<LensVerificationPipelineResult> {
+  const { api, lenses, perLens, finderPhase = "Find", finderPrompt, verifierPrompt, boundCandidate } = options;
+  const coverage: AdvisoryStageCoverage[] = [];
   let rawCandidates = 0;
-  let dropped = 0;
-  let refuted = 0;
-
-  const findForLens = async (lens: Lens): Promise<FoundForLens<Lens>> => {
-    const found = await api.agent(finderPrompt(lens), {
-      phase: finderPhase,
-      label: `find:${lens.label}`,
-      tools,
-      toolHints,
-      profile: "small",
-      schema: AdvisoryCandidatesSchema,
+  api.phase(finderPhase);
+  const found = await collectAdvisoryStage(api, "Find", lenses.map((lens) => ({ id: lens.label, run: async () => {
+    const result = await api.agent(finderPrompt(lens), {
+      phase: finderPhase, label: `${finderPhase.toLowerCase()}:${lens.label}`,
+      tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
+      profile: "small", schema: AdvisoryCandidatesSchema,
     });
-    const candidates = (found?.candidates ?? []).slice(0, perLens);
-    rawCandidates += candidates.length;
-    api.progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: candidates.length });
+    const raw = identifyCandidates(result.candidates.slice(0, perLens), lens.label);
+    rawCandidates += raw.length;
+    api.progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: raw.length });
+    const candidates = boundCandidate ? raw.flatMap((candidate) => {
+      const bounded = boundCandidate(candidate, lens);
+      return bounded ? [bounded] : [];
+    }) : raw;
     for (const candidate of candidates) {
-      api.progress({
-        type: "lane_item",
-        lane: "Candidates",
-        title: candidate.summary,
-        subtitle: formatLocation(candidate),
-        status: "pending",
-        details: candidate.impact,
-      });
+      api.progress({ type: "lane_item", lane: finderPhase === "Hypothesize" ? "Hypotheses" : "Candidates",
+        title: candidate.summary, subtitle: formatLocation(candidate), status: "pending", details: candidate.impact });
     }
-    return { lens, candidates };
-  };
+    return candidates;
+  } })), coverage);
+  const candidates = dedupeCandidates(found.flat());
+  const dropped = rawCandidates - candidates.length;
+  if (dropped > 0) {
+    api.progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
+    api.log(`Dropped ${dropped} duplicate or out-of-scope candidate(s)`);
+  }
+  api.phase("Verify");
+  const verified = await collectAdvisoryStage(api, "Verify", candidates.map((candidate) => ({
+    id: candidate.candidateId, candidate, run: async (): Promise<AdvisoryVerified> => {
+      const location = primaryLocation(candidate);
+      const judged = await api.agent(`${verifierPrompt(candidate)}\nCandidate record: ${JSON.stringify(candidate)}`, {
+        phase: "Verify", label: `verify:${location.file.split("/").pop() ?? location.file}`,
+        tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS,
+        profile: "small", schema: AdvisoryVerdictSchema,
+      });
+      recordVerdictProgress(api.progress, candidate, judged);
+      return { ...candidate, verdict: judged.verdict, evidence: judged.evidence };
+    },
+  })), coverage);
+  return { verified, rawCandidates, dropped, coverage };
+}
 
-  const dedupeFound = (found: FoundForLens<Lens>): NovelCandidate<Lens>[] => {
-    const novel = candidatesNovelToRun(found.candidates, seen).map((candidate) => ({ lens: found.lens, candidate }));
-    const droppedForLens = found.candidates.length - novel.length;
-    if (droppedForLens > 0) {
-      dropped += droppedForLens;
-      api.progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: droppedForLens });
-      api.log(`find:${found.lens.label}: dropped ${droppedForLens} duplicate candidate(s)`);
-    }
-    return novel;
-  };
+/** Stats for a lens review that stopped before discovery. */
+export const EMPTY_LENS_REVIEW_STATS: Readonly<WorkflowRunStats> = Object.freeze({ files: 0, candidates: 0, verified: 0, kept: 0, dropped: 0, refuted: 0 });
+
+export interface LensReviewConclusion {
+  /** Scoped file count reported in stats. */
+  files: number;
+  rank(finding: AdvisoryVerified): number;
+  /** One ranked finding's synthesis-prompt block, headed by the IDs synthesis selects; defaults to {@link formatRankedFinding}. */
+  formatFinding?(finding: AdvisoryVerified, index: number): string;
+  /** Report used when no finding survives verification and challenge. */
+  empty: { summary: string; nextSteps: string[] };
+  synthesisPrompt(block: string, ranked: readonly AdvisoryVerified[], refuted: readonly AdvisoryVerified[]): string;
+}
 
-  const verifyCandidate = async ({ lens, candidate }: NovelCandidate<Lens>): Promise<Verified | null> => {
-    const location = primaryLocation(candidate);
-    const judged = await api.agent(verifierPrompt(candidate), {
-      phase: verifierPhase,
-      label: `verify:${location.file.split("/").pop() ?? location.file}`,
-      tools,
-      toolHints,
-      profile: "small",
-      schema: AdvisoryVerdictSchema,
-    });
-    if (!judged) return null;
-    recordVerdictProgress(api.progress, candidate, judged, () => {
-      refuted += 1;
-    });
-    return makeVerified(candidate, lens, judged);
-  };
+export function formatRankedFinding(finding: AdvisoryVerified, index: number, recommendationLabel = "Recommendation"): string {
+  return `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}, ${finding.category})\n` +
+    `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}\n${recommendationLabel}: ${finding.recommendation ?? "(none supplied)"}`;
+}
 
-  if (schedulingMode === "finder-barrier") {
-    const found = await api.parallel(lenses.map((lens) => async () => findForLens(lens)));
-    const novel = compactResults(found).flatMap(dedupeFound);
-    const verdicts = await api.parallel(novel.map((entry) => async () => verifyCandidate(entry)));
-    return { verified: compactResults(verdicts), rawCandidates, dropped, refuted };
+/** Rank and synthesize the findings that survived verification and challenge into the final report. */
+export async function concludeLensReview(
+  api: Pick<WorkflowApi, "agent" | "parallel" | "phase" | "progress" | "log">,
+  pipeline: LensVerificationPipelineResult,
+  verified: AdvisoryVerified[],
+  conclusion: LensReviewConclusion,
+) {
+  const { coverage } = pipeline;
+  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
+  const stats: WorkflowRunStats = {
+    files: conclusion.files,
+    candidates: pipeline.rawCandidates,
+    verified: verified.length,
+    kept: surviving.length,
+    dropped: pipeline.dropped,
+    refuted: verified.length - surviving.length,
+  };
+  publishVerifiedKeptProgress(api, verified.length, surviving.length);
+  if (surviving.length === 0) {
+    return finishAdvisoryReport(emptyAdvisoryReport(conclusion.empty.summary, conclusion.empty.nextSteps, stats), coverage, verified);
   }
 
-  const perLensVerified = await api.pipeline(
-    lenses,
-    async (_prev, lens) => findForLens(lens),
-    async (found) => {
-      const novel = dedupeFound(found);
-      const verdicts = await api.parallel(novel.map((entry) => async () => verifyCandidate(entry)));
-      return compactResults(verdicts);
-    },
-  );
+  const ranked = [...surviving].sort((a, b) => conclusion.rank(a) - conclusion.rank(b));
+  const block = ranked.map((finding, index) => (conclusion.formatFinding ?? formatRankedFinding)(finding, index)).join("\n\n");
+  const refuted = verified.filter((finding) => finding.verdict === "REFUTED");
+  const resolved = await synthesizeAdvisoryReport(api, conclusion.synthesisPrompt(block, ranked, refuted), ranked, coverage);
+  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length } }, coverage, verified);
+}
 
-  return { verified: compactResults(perLensVerified).flat(), rawCandidates, dropped, refuted };
+export async function synthesizeAdvisoryReport(
+  api: Pick<WorkflowApi, "agent" | "parallel" | "phase">,
+  prompt: string,
+  ranked: readonly AdvisoryVerified[],
+  coverage: AdvisoryStageCoverage[],
+): Promise<AdvisoryReport> {
+  api.phase("Synthesize");
+  const [report] = await collectAdvisoryStage(api, "Synthesize", [{ id: "synthesize", run: () => api.agent(
+    SYNTHESIS_ID_INSTRUCTIONS + prompt,
+    { phase: "Synthesize", label: "synthesize", tools: [], skills: [], profile: "medium", resume: "read-only", schema: AdvisorySynthesisSchema },
+  ) }], coverage);
+  return resolveAdvisorySynthesis(report, ranked, {
+    impact: "Impact not restated by verification.",
+    recommendation: "Inspect the cited evidence and validate the smallest repair.",
+  }, coverage);
 }
 
-function candidatesNovelToRun(candidates: readonly AdvisoryCandidate[], seen: Set<string>): AdvisoryCandidate[] {
-  return candidates.filter((candidate) => {
-    const key = advisoryDedupKey(candidate);
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
+export function finishAdvisoryReport<T extends AdvisoryReport>(
+  report: T, coverage: AdvisoryStageCoverage[], verification: AdvisoryVerified[] = [],
+) {
+  return { ...withAdvisoryCoverage(report, coverage), verification };
 }
 
 export function primaryLocation(candidate: Pick<AdvisoryCandidate, "locations">): AdvisoryLocation {
@@ -186,107 +188,95 @@ export function primaryLocation(candidate: Pick<AdvisoryCandidate, "locations">)
 }
 
 export function formatLocation(candidate: Pick<AdvisoryCandidate, "locations">): string {
-  const location = primaryLocation(candidate);
-  const line = location.line != null ? `:${location.line}` : "";
-  const symbol = location.symbol ? ` (${location.symbol})` : "";
-  return `${location.file}${line}${symbol}`;
+  return formatAdvisoryLocation(primaryLocation(candidate));
 }
 
 export function formatEvidence(evidence: readonly string[]): string {
   return evidence.join("; ");
 }
 
-export function normalizePath(path: string): string {
-  return path.replace(/^\.\//, "").replace(/^[ab]\//, "");
-}
-
-export function advisoryDedupKey(candidate: AdvisoryCandidate): string {
-  const location = primaryLocation(candidate);
-  const lineKey = location.line != null ? Math.round(location.line / 5) * 5 : "file";
-  return `${candidate.category}:${normalizePath(location.file)}:${lineKey}:${candidate.summary.slice(0, 60).toLowerCase()}`;
-}
-
-export function verdictLane(verdict: AdvisoryVerdict["verdict"]): string {
-  switch (verdict) {
-    case "CONFIRMED":
-      return "Confirmed";
-    case "PLAUSIBLE":
-      return "Plausible";
-    case "REFUTED":
-      return "Refuted";
-  }
-}
-
-export function verdictStatus(verdict: AdvisoryVerdict["verdict"]): "success" | "warning" | "error" {
-  switch (verdict) {
-    case "CONFIRMED":
-      return "success";
-    case "PLAUSIBLE":
-      return "warning";
-    case "REFUTED":
-      return "error";
-  }
-}
+const VERDICT_PRESENTATION = {
+  CONFIRMED: { lane: "Confirmed", status: "success", confidence: "high" },
+  PLAUSIBLE: { lane: "Plausible", status: "warning", confidence: "medium" },
+  NOT_SUBSTANTIATED: { lane: "Unresolved", status: "warning", confidence: "medium" },
+  REFUTED: { lane: "Refuted", status: "error", confidence: "low" },
+} satisfies Record<AdvisoryVerdict["verdict"], {
+  lane: string; status: "success" | "warning" | "error"; confidence: AdvisoryFinding["confidence"];
+}>;
 
 export function verdictConfidence(verdict: AdvisoryVerdict["verdict"]): "high" | "medium" | "low" {
-  switch (verdict) {
-    case "CONFIRMED":
-      return "high";
-    case "PLAUSIBLE":
-      return "medium";
-    case "REFUTED":
-      return "low";
-  }
-}
-
-export function sameFinding(candidate: Pick<AdvisoryCandidate, "locations">, finding: Pick<AdvisoryFinding, "locations" | "summary">): boolean {
-  return findingLocationKey(candidate) === findingLocationKey(finding);
-}
-
-export function findingLocationKey(value: Pick<AdvisoryCandidate, "locations"> | Pick<AdvisoryFinding, "locations">): string {
-  const location = primaryLocation(value);
-  return `${normalizePath(location.file)}:${location.line ?? "file"}`;
+  return VERDICT_PRESENTATION[verdict].confidence;
 }
 
 export function recordVerdictProgress(
   progress: (event: WorkflowProgressEvent) => void,
   candidate: Pick<AdvisoryCandidate, "locations" | "summary">,
   verdict: Pick<AdvisoryVerdict, "verdict" | "evidence">,
-  onRefuted?: () => void,
 ): void {
   progress({ type: "counter_delta", key: `verdict.${verdict.verdict.toLowerCase()}`, label: verdict.verdict, delta: 1 });
   if (verdict.verdict === "REFUTED") {
-    onRefuted?.();
     progress({ type: "counter_delta", key: "refuted", label: "refuted", delta: 1 });
   }
   progress({
     type: "lane_item",
-    lane: verdictLane(verdict.verdict),
+    lane: VERDICT_PRESENTATION[verdict.verdict].lane,
     title: candidate.summary,
     subtitle: formatLocation(candidate),
-    status: verdictStatus(verdict.verdict),
+    status: VERDICT_PRESENTATION[verdict.verdict].status,
     details: formatEvidence(verdict.evidence),
   });
 }
 
 export function backfillAdvisoryFindings<Source extends AdvisoryVerified>(
-  findings: AdvisoryReport["findings"],
+  findings: AdvisorySynthesis["findings"],
   ranked: readonly Source[],
   defaults: AdvisoryBackfillDefaults,
 ): AdvisoryReport["findings"] {
-  const rankedByLocation = new Map<string, Source>();
-  for (const candidate of ranked) {
-    const key = findingLocationKey(candidate);
-    if (!rankedByLocation.has(key)) rankedByLocation.set(key, candidate);
-  }
+  const sources = new Map(ranked.flatMap((source) => source.sourceCandidateIds.map((id) => [id, source] as const)));
+  const used = new Set<string>();
+  return findings.flatMap((selection) => {
+    const ids = [...new Set(selection.sourceCandidateIds)];
+    if (ids.length === 0 || ids.some((id) => !sources.has(id) || used.has(id))) return [];
+    const records = [...new Set(ids.map((id) => sources.get(id)!))];
+    if (records.some((record) => record.verdict === "REFUTED")) return [];
+    const sourceCandidateIds = [...new Set(records.flatMap((record) => record.sourceCandidateIds))];
+    if (sourceCandidateIds.some((id) => used.has(id))) return [];
+    sourceCandidateIds.forEach((id) => used.add(id));
+    const first = records[0]!;
+    return [{
+      sourceCandidateIds,
+      summary: [...new Set(records.map((record) => record.summary))].join("; "),
+      category: first.category,
+      severity: selection.severity,
+      verdict: records.some((record) => record.verdict === "NOT_SUBSTANTIATED") ? "NOT_SUBSTANTIATED" as const : records.some((record) => record.verdict === "PLAUSIBLE") ? "PLAUSIBLE" as const : "CONFIRMED" as const,
+      confidence: records.every((record) => record.verdict === "CONFIRMED") ? "high" as const : "medium" as const,
+      locations: uniqueLocations(records.flatMap((record) => record.locations)),
+      ...(first.reviewAnchor ? { reviewAnchor: first.reviewAnchor } : {}),
+      evidence: [...new Set(records.flatMap((record) => [...(record.discoveryEvidence ?? []), ...record.evidence]))],
+      impact: [...new Set(records.map((record) => record.impact || defaults.impact))].join("\n"),
+      recommendation: selection.recommendation || first.recommendation || defaults.recommendation || "",
+    }];
+  });
+}
 
-  return findings.map((finding) => {
-    const source = rankedByLocation.get(findingLocationKey(finding));
+/** Retain verified records if synthesis fails, and expose invalid ID selections as a gap. */
+export function resolveAdvisorySynthesis<Source extends AdvisoryVerified>(
+  report: AdvisorySynthesis | undefined,
+  ranked: readonly Source[],
+  defaults: AdvisoryBackfillDefaults,
+  coverage: AdvisoryStageCoverage[],
+): AdvisoryReport {
+  if (!report) {
     return {
-      ...finding,
-      evidence: finding.evidence.length > 0 ? finding.evidence : (source?.evidence ?? []),
-      impact: finding.impact || source?.impact || defaults.impact,
-      recommendation: finding.recommendation || source?.recommendation || defaults.recommendation || "",
+      summary: "Synthesis unavailable; verified records retained.",
+      findings: backfillAdvisoryFindings(ranked.map((finding) => ({ sourceCandidateIds: finding.sourceCandidateIds, severity: "medium", recommendation: finding.recommendation ?? defaults.recommendation ?? "Inspect verifier evidence." })), ranked, defaults),
+      nextSteps: ["Inspect verifier evidence or rerun synthesis."],
     };
-  });
+  }
+  const findings = backfillAdvisoryFindings(report.findings, ranked, defaults);
+  if (findings.length !== report.findings.length) {
+    coverage.push({ stage: "Synthesis provenance", expected: report.findings.length, completed: findings.length,
+      failed: report.findings.length - findings.length, failures: [{ branch: "synthesize", reason: "Discarded invalid, repeated, or unverified candidate IDs." }] });
+  }
+  return { ...report, findings };
 }

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

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isRecord } from "./guards.ts";
 import type { ResolvedWorkflowRunOptions } from "./options.ts";
 import type { PerfAggregate, PerfSink, PerfSnapshot } from "./perf.ts";
 import type { WorkflowProgressSnapshot } from "./progress-types.ts";
@@ -11,14 +12,14 @@ import type {
 import type { WorkflowUsageSnapshot } from "./usage.ts";
 
 export interface WorkflowPerfDetails {
-  readonly enabled: boolean;
-  readonly startedAt: number;
   readonly aggregates: readonly PerfAggregate[];
 }
 
 export interface WorkflowResultEnvelope {
   readonly name: string;
   readonly result: unknown;
+  /** Optional so envelopes persisted before it existed still render. */
+  readonly startedAt?: number;
   readonly completedAt: number;
   readonly usage?: WorkflowUsageSnapshot;
   readonly perf?: WorkflowPerfDetails;
@@ -26,6 +27,12 @@ export interface WorkflowResultEnvelope {
   readonly resumedFromRunId?: string;
 }
 
+/** A workflow result's own summary: the result itself when it is a string, else its string `summary` field. */
+export function workflowResultSummary(result: unknown): string | undefined {
+  if (typeof result === "string") return result;
+  return isRecord(result) && typeof result.summary === "string" ? result.summary : undefined;
+}
+
 export type ResolvedWorkflowRunner = (
   ctx: ExtensionContext,
   mod: LoadedWorkflow,
@@ -46,13 +53,8 @@ export interface WorkflowExecutionInput {
   readonly onProgressSnapshot?: (snapshot: WorkflowProgressSnapshot) => void | Promise<void>;
 }
 
-export interface WorkflowExecution {
-  readonly metadata?: WorkflowRunMetadata;
-  readonly envelope: WorkflowResultEnvelope;
-}
-
 /** Shared command/tool execution path. The engine remains lazy-loaded by the caller. */
-export async function executeWorkflowInvocation(input: WorkflowExecutionInput): Promise<WorkflowExecution> {
+export async function executeWorkflowInvocation(input: WorkflowExecutionInput): Promise<WorkflowResultEnvelope> {
   let perfSnapshot: PerfSnapshot | undefined;
   let usageSnapshot: WorkflowUsageSnapshot | undefined;
   let runMetadata: WorkflowRunMetadata | undefined;
@@ -86,27 +88,20 @@ export async function executeWorkflowInvocation(input: WorkflowExecutionInput):
       );
     },
   };
+  const startedAt = Date.now();
   const result = await input.runResolvedWorkflow(input.ctx, input.mod, input.args, runOptions);
-  const perf = compactPerfSnapshot(perfSnapshot);
   return {
-    metadata: runMetadata,
-    envelope: {
-      name: input.name,
-      result,
-      completedAt: Date.now(),
-      usage: usageSnapshot,
-      perf,
-      runId: runMetadata?.runId,
-      resumedFromRunId: runMetadata?.resumedFromRunId,
-    },
+    name: input.name,
+    result,
+    startedAt,
+    completedAt: Date.now(),
+    usage: usageSnapshot,
+    perf: perfSnapshot?.enabled ? { aggregates: perfSnapshot.aggregates } : undefined,
+    runId: runMetadata?.runId,
+    resumedFromRunId: runMetadata?.resumedFromRunId,
   };
 }
 
-function compactPerfSnapshot(snapshot: PerfSnapshot | undefined): WorkflowPerfDetails | undefined {
-  if (!snapshot?.enabled) return undefined;
-  return { enabled: true, startedAt: snapshot.startedAt, aggregates: snapshot.aggregates };
-}
-
 async function notifyLifecycleObservers(...observers: ReadonlyArray<() => void | Promise<void>>): Promise<void> {
   const failures: unknown[] = [];
   for (const observer of observers) {

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

@@ -5,35 +5,33 @@ import type {
   WorkflowSourceIdentity,
 } from "./types.ts";
 import type { WorktreeBaseline } from "./worktree.ts";
+import { isRecord } from "./guards.ts";
 
-type WorkflowMetaCandidate = {
-  readonly name?: unknown;
-  readonly description?: unknown;
-  readonly phases?: unknown;
-};
+/** Validate and normalize workflow metadata without executing workflow code. */
+export function parseWorkflowMeta(meta: unknown): { meta: WorkflowMeta } | { reason: string } {
+  if (!isRecord(meta)) return { reason: "meta export must be an object" };
+  if (typeof meta.name !== "string") return { reason: "meta.name must be a string" };
 
-type WorkflowModuleCandidate = {
-  readonly meta?: unknown;
-  readonly default?: unknown;
-};
+  const description = meta.description;
+  if (description !== undefined && typeof description !== "string") return { reason: "meta.description must be a string when provided" };
 
-/** Validate and normalize workflow metadata without executing workflow code. */
-export function parseWorkflowMeta(value: unknown): { meta: WorkflowMeta } | { reason: string } {
-  if (!isRecord(value)) return { reason: "meta export must be an object" };
-  return parseWorkflowMetaObject(value);
+  const phases = meta.phases;
+  if (phases !== undefined && !isWorkflowPhases(phases)) return { reason: "meta.phases must be an array of { title: string }" };
+
+  const workflowMeta: WorkflowMeta = { name: meta.name, description: description ?? "" };
+  if (phases !== undefined) workflowMeta.phases = phases;
+  return { meta: workflowMeta };
 }
 
 export function parseWorkflowModule(value: unknown): { module: WorkflowModule } | { reason: string } {
   if (!isRecord(value)) return { reason: "module export is not an object" };
-  const candidate = value as WorkflowModuleCandidate;
-  const meta = candidate.meta;
-  if (!isRecord(meta)) return { reason: "missing meta export" };
+  if (value.meta === undefined) return { reason: "missing meta export" };
 
-  const parsedMeta = parseWorkflowMetaObject(meta);
+  const parsedMeta = parseWorkflowMeta(value.meta);
   if ("reason" in parsedMeta) return parsedMeta;
-  if (!isWorkflowRun(candidate.default)) return { reason: "default export must be a function" };
+  if (!isWorkflowRun(value.default)) return { reason: "default export must be a function" };
 
-  return { module: { meta: parsedMeta.meta, default: candidate.default } };
+  return { module: { meta: parsedMeta.meta, default: value.default } };
 }
 
 /** Attach engine-owned source provenance after an authored module has been validated. */
@@ -48,20 +46,6 @@ export function loadWorkflow(
     : { ...loaded, isolatedWorktreeBaseline };
 }
 
-function parseWorkflowMetaObject(meta: WorkflowMetaCandidate): { meta: WorkflowMeta } | { reason: string } {
-  if (typeof meta.name !== "string") return { reason: "meta.name must be a string" };
-
-  const description = meta.description;
-  if (description !== undefined && typeof description !== "string") return { reason: "meta.description must be a string when provided" };
-
-  const phases = meta.phases;
-  if (phases !== undefined && !isWorkflowPhases(phases)) return { reason: "meta.phases must be an array of { title: string }" };
-
-  const workflowMeta: WorkflowMeta = { name: meta.name, description: description ?? "" };
-  if (phases !== undefined) workflowMeta.phases = phases;
-  return { meta: workflowMeta };
-}
-
 function isWorkflowRun(value: unknown): value is WorkflowModule["default"] {
   return typeof value === "function";
 }
@@ -69,7 +53,3 @@ function isWorkflowRun(value: unknown): value is WorkflowModule["default"] {
 function isWorkflowPhases(value: unknown): value is Array<{ title: string }> {
   return Array.isArray(value) && value.every((phase) => isRecord(phase) && typeof phase.title === "string");
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}