docs: make technical prose concrete

packages/workflow/tool-workflow/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workflow/tool-workflow/README.md
-README.md: 4b75ce5b6a248949f135bfe1883680a645a4c774
-README.zh.md: 930da9d0975cd334a7a7cabf59958a9e11106861
+README.md: 29896bee0f78a1d1764c3908965325fcecbf7b53
+README.zh.md: 12e1ecd8932120c74384a289530954422ba145f2

packages/workflow/tool-workflow/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The model-facing **`workflow` tool**: run a JavaScript orchestration script that fans out subagents, and return the script's final value. This package owns schema and lifecycle shaping over [`ctx.workflows`](../workflow/README.md); script parsing, execution, caps, and cancellation live behind the seam, while the consumer retains ownership of the parent-facing schema and result envelope.
+The model-facing **`workflow` tool**: run a JavaScript orchestration script that fans out subagents, and return the script's final value. This package owns the model-facing schema and run lifecycle over [`ctx.workflows`](../workflow/README.md); script parsing, execution, caps, and cancellation live behind the seam, while the consumer retains ownership of the parent-facing schema and result envelope.
 
 ## What the model sees
 

packages/workflow/tool-workflow/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-面向模型的 **`workflow` 工具**：运行一段扇出 subagent 的 JavaScript 编排脚本，并返回脚本的最终值。本包负责基于 [`ctx.workflows`](../workflow/README.md) 塑造 schema 和生命周期；脚本解析、执行、上限与取消位于 seam 之后，消费方仍负责面向父级的 schema 和结果包络。
+面向模型的 **`workflow` 工具**：运行一段扇出 subagent 的 JavaScript 编排脚本，并返回脚本的最终值。本包负责基于 [`ctx.workflows`](../workflow/README.md) 定义面向模型的 schema 和运行生命周期；脚本解析、执行、上限与取消位于 seam 之后，消费方仍负责面向父级的 schema 和结果包络。
 
 ## 模型看到的内容
 

packages/workflow/tool-workflow/src/index.ts

@@ -1,6 +1,6 @@
 /**
  * The model-facing `workflow` tool: run a JavaScript orchestration script that fans out
- * subagents, and return the script's final value. Pure schema + lifecycle shaping — script
+ * subagents, and return the script's final value. It owns the model-facing schema and run lifecycle; script
  * parsing, execution, caps, and cancellation live behind `ctx.workflows`
  * (`@deepseek-ai/dsh-workflow`), so a hardened engine swaps in without touching what the model
  * sees. Execution awaits `run.result` and always disposes the run; non-completed reasons become tool

packages/workflow/workflow-workerthread/src/meta.ts

@@ -1,6 +1,6 @@
 /**
- * Meta validation: check the caller-provided {@link WorkflowMeta} DATA against the shape
- * contract and reject everything else loud, every violation named. Meta arrives as schema-checked
+ * Meta validation checks caller-provided DATA against the {@link WorkflowMeta}
+ * contract and rejects every violation by name. Meta arrives as schema-checked
  * JSON data, never evaluated script text; evaluating it on the host could run getters outside the
  * worker timeout that exists to isolate model-written code.
  * @module @deepseek-ai/dsh-workflow-workerthread/meta

packages/workflow/workflow-workerthread/src/realm.ts

@@ -1,7 +1,7 @@
 /**
  * Materializes values leaving the script vm into plain JSON before they cross the worker
  * boundary, and renders thrown script values without rejecting the run. The walk rejects
- * lossy JSON shapes but trusts model-written workflow scripts: getters and proxy traps may
+ * values that JSON cannot preserve but trusts model-written workflow scripts: getters and proxy traps may
  * run, and the vm is not a security boundary. The worker provides host-loop isolation and
  * forced termination, not hostile-value containment. See
  * .agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md for the isolation rationale.
@@ -22,7 +22,7 @@ export class MaterializeError extends Error {
  * fall back to `message`, then `String()`. Reading those properties MAY run
  * script code (a getter, `toString`) — accepted under the module's trust
  * premise; if that code itself throws, a fixed label is returned instead.
- * @param error - the thrown value, of any shape and any realm.
+ * @param error - any value thrown in the host or worker realm.
  * @returns human-readable text for the failure report; prefers the stack.
  */
 export function renderThrown(error: unknown): string {
@@ -40,7 +40,7 @@ export function renderThrown(error: unknown): string {
 }
 
 /**
- * Whether an object's prototype chain is data-shaped: `null`, or a prototype
+ * Whether an object's prototype chain represents a plain data object: `null`, or a prototype
  * whose own prototype is `null` (the realm's `Object.prototype` — which we
  * cannot compare by identity across realms). A `Date`/`Map`/class instance
  * has a longer chain and is rejected.
@@ -87,9 +87,9 @@ function materialize(value: unknown, path: string, seen: Set<object>): unknown {
     case 'bigint':
       throw new MaterializeError(path, 'bigints are not JSON data')
     case 'function':
-      throw new MaterializeError(path, 'functions cannot cross the workflow value boundary')
+      throw new MaterializeError(path, 'functions are not plain JSON data')
     case 'symbol':
-      throw new MaterializeError(path, 'symbols cannot cross the workflow value boundary')
+      throw new MaterializeError(path, 'symbols are not plain JSON data')
     case 'undefined':
       throw new MaterializeError(path, 'undefined is not JSON data')
     case 'object':
@@ -122,7 +122,7 @@ function materializeArray(value: unknown[], path: string, seen: Set<object>): un
     }
   }
   if (Object.getOwnPropertySymbols(value).length > 0) {
-    throw new MaterializeError(path, 'symbol-keyed properties cannot cross the workflow value boundary')
+    throw new MaterializeError(path, 'symbol-keyed properties are not plain JSON data')
   }
   return out
 }
@@ -132,7 +132,7 @@ function materializeObject(value: object, path: string, seen: Set<object>): Reco
     throw new MaterializeError(path, 'only plain objects and arrays are JSON data (exotic prototype)')
   }
   if (Object.getOwnPropertySymbols(value).length > 0) {
-    throw new MaterializeError(path, 'symbol-keyed properties cannot cross the workflow value boundary')
+    throw new MaterializeError(path, 'symbol-keyed properties are not plain JSON data')
   }
   const out: Record<string, unknown> = {}
   // Object.keys = own enumerable string keys, matching JSON.stringify's

packages/workflow/workflow-workerthread/src/runtime.ts

@@ -1,5 +1,5 @@
 /**
- * Per-run worker-side vm hooks, child RPC, concurrency/caps, cancellation, and result shaping; it
+ * Per-run worker-side vm hooks, child RPC, concurrency/caps, cancellation, and result serialization; it
  * never touches Cordis. Script values leaving the realm are materialized as plain JSON before
  * messaging. Values entering the trusted model-written realm are passed directly; `args` alone is
  * cloned so script mutation cannot alter initialization data. See `./realm.ts` for the trust model.

packages/workflow/workflow/src/types.ts

@@ -1,6 +1,6 @@
 /**
  * Workflow seam vocabulary: the request/run/result types a workflow engine
- * consumes and produces, plus the payload shapes of the `workflow/*` events.
+ * consumes and produces, plus the fields in the `workflow/*` event payloads.
  * Types only (plus the id-brand factory), per the package convention.
  *
  * @module @deepseek-ai/dsh-workflow/types
@@ -57,8 +57,8 @@ export interface WorkflowMeta {
 
 /**
  * What a caller asks for when starting a workflow run. `meta` and `args` are
- * plain JSON DATA by the seam contract (the tool builds both from the model's
- * schema-validated call; the engine validates `meta`'s shape and rejects loud
+ * plain JSON DATA by the seam contract (the tool builds both from the model's schema-validated call;
+ * the engine validates `meta` against its schema and rejects loud
  * before anything runs) — an engine never evaluates script text to obtain
  * them. `parent` is REQUIRED — every `agent()` the script spawns is
  * attributed to it (cwd, lineage, depth flow through the subagent seam).
@@ -66,7 +66,7 @@ export interface WorkflowMeta {
 export interface WorkflowStartRequest {
   /** The plain-JS script body (top-level await allowed; ends with `return <json-value>`). */
   script: string
-  /** The workflow's identity block, as plain JSON data (shape-validated by the engine). */
+  /** The workflow's identity fields as plain JSON data, validated by the engine. */
   meta: WorkflowMeta
   /** Optional input exposed verbatim to the script as the `args` global. */
   args?: unknown