From 1f5db6e0b0ce3b7ee055a6712167ee474910b1e7 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 7 Jul 2026 22:39:05 +0800
Subject: [PATCH] docs: satisfy the export-JSDoc gate across the workflow
 packages

Master's verify-export-jsdoc landed mid-stack; complete the six missing
@param/@returns on the workflow trio's public surface (and the services
catalog they regenerate into).
---
 docs/cordis-catalog/services.md              | 2 +-
 packages/workflow/workflow-vm/src/runtime.ts | 4 ++++
 packages/workflow/workflow/src/index.ts      | 6 +++++-
 packages/workflow/workflow/src/types.ts      | 6 +++++-
 4 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index f292045c69..3e991726d4 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -243,7 +243,7 @@ Semantics every implementation must honor:
 abstract start(request: WorkflowStartRequest): WorkflowRun
 ```
 
-Source: [`packages/workflow/workflow/src/index.ts:198`](../../packages/workflow/workflow/src/index.ts)
+Source: [`packages/workflow/workflow/src/index.ts:202`](../../packages/workflow/workflow/src/index.ts)
 
 ## Inherited `ctx` members (cordis core + loader/hmr/timer)
 
diff --git a/packages/workflow/workflow-vm/src/runtime.ts b/packages/workflow/workflow-vm/src/runtime.ts
index f1901ffaf7..0938b7f2c9 100644
--- a/packages/workflow/workflow-vm/src/runtime.ts
+++ b/packages/workflow/workflow-vm/src/runtime.ts
@@ -225,6 +225,8 @@ export class WorkflowExecution {
    * `disposeGraceMs` (parked on a promise no hook owns) is abandoned so
    * `result` settles regardless (see {@link abandoned}). Idempotent; the
    * first reason wins.
+   * @param reason - human-readable cause, carried on the CANCELLED error and
+   * into child `run.cancel()` calls (default `'workflow cancelled'`).
    */
   cancel(reason?: string): void {
     if (this.cancelReason !== undefined) return
@@ -244,6 +246,8 @@ export class WorkflowExecution {
    * cancellation (or outlived its post-cancel grace and was abandoned — see
    * {@link abandoned}). After settlement, any stray children a script fired
    * without awaiting are aborted (their `agent()` wrappers dispose them).
+   * @returns the settled outcome — this promise NEVER rejects (the seam's
+   * `result`-never-rejects contract); every failure maps to a variant.
    */
   async drive(): Promise<WorkflowResult> {
     try {
diff --git a/packages/workflow/workflow/src/index.ts b/packages/workflow/workflow/src/index.ts
index 31b9eed038..288f6af952 100644
--- a/packages/workflow/workflow/src/index.ts
+++ b/packages/workflow/workflow/src/index.ts
@@ -168,7 +168,11 @@ export class WorkflowError extends HarnessError {
   }
 }
 
-/** Whether combinators must re-throw `error` instead of mapping the item to `null`. */
+/**
+ * Whether combinators must re-throw `error` instead of mapping the item to `null`.
+ * @param error - any thrown value; fatality is host `instanceof` (unforgeable from a script realm).
+ * @returns true iff `error` is a {@link WorkflowError} whose `fatal` flag is set.
+ */
 export function isFatalWorkflowError(error: unknown): boolean {
   return error instanceof WorkflowError && error.fatal
 }
diff --git a/packages/workflow/workflow/src/types.ts b/packages/workflow/workflow/src/types.ts
index 01e5d08bf0..767fb8257b 100644
--- a/packages/workflow/workflow/src/types.ts
+++ b/packages/workflow/workflow/src/types.ts
@@ -12,7 +12,11 @@ import type { Agent, AgentId } from '@deepseek-ai/dsh-agent'
 /** Identifies one workflow run. */
 export type WorkflowRunId = Branded<'WorkflowRunId'>
 
-/** Brand a string as a {@link WorkflowRunId}. */
+/**
+ * Brand a string as a {@link WorkflowRunId}.
+ * @param id - the raw id string (the engine mints UUIDs; tests may pass fixtures).
+ * @returns the same string, branded.
+ */
 export function WorkflowRunId(id: string): WorkflowRunId {
   return id as WorkflowRunId
 }