Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: satisfy the export-JSDoc gate across the workflow packages

Browse Source 
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).
This commit is contained in:
Tianyi Cui
2026-07-07 22:39:05 +08:00
parent 8db99d36e8
commit 1f5db6e0b0
4 changed files with 15 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/cordis-catalog/services.md
View File

@@ -243,7 +243,7 @@ Semantics every implementation must honor:
abstract start(request: WorkflowStartRequest): WorkflowRun 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) ## Inherited `ctx` members (cordis core + loader/hmr/timer)

4
packages/workflow/workflow-vm/src/runtime.ts
View File

@@ -225,6 +225,8 @@ export class WorkflowExecution {
* `disposeGraceMs` (parked on a promise no hook owns) is abandoned so * `disposeGraceMs` (parked on a promise no hook owns) is abandoned so
* `result` settles regardless (see {@link abandoned}). Idempotent; the * `result` settles regardless (see {@link abandoned}). Idempotent; the
* first reason wins. * 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 { cancel(reason?: string): void {
if (this.cancelReason !== undefined) return if (this.cancelReason !== undefined) return
@@ -244,6 +246,8 @@ export class WorkflowExecution {
* cancellation (or outlived its post-cancel grace and was abandoned — see * cancellation (or outlived its post-cancel grace and was abandoned — see
* {@link abandoned}). After settlement, any stray children a script fired * {@link abandoned}). After settlement, any stray children a script fired
* without awaiting are aborted (their `agent()` wrappers dispose them). * 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> { async drive(): Promise<WorkflowResult> {
try { try {

6
packages/workflow/workflow/src/index.ts
View File

@@ -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 { export function isFatalWorkflowError(error: unknown): boolean {
return error instanceof WorkflowError && error.fatal return error instanceof WorkflowError && error.fatal
} }

6
packages/workflow/workflow/src/types.ts
View File

@@ -12,7 +12,11 @@ import type { Agent, AgentId } from '@deepseek-ai/dsh-agent'
/** Identifies one workflow run. */ /** Identifies one workflow run. */
export type WorkflowRunId = Branded<'WorkflowRunId'> 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 { export function WorkflowRunId(id: string): WorkflowRunId {
return id as WorkflowRunId return id as WorkflowRunId
} }