workflow: pin thenable-return semantics as documented async-JS behavior

Codex code-review round 4 flagged the return channel: an async IIFE
Promise-assimilates a returned thenable, so its then() runs past the sync
slice and the RESOLUTION replaces the raw object. Verified against the real
engine and judged behavior, not defect:

- Assimilation is standard JavaScript (an async function's returned thenable
  resolves before the caller sees it) and is load-bearing ergonomics: an
  un-awaited 'return agent(...)' / 'return parallel(...)' resolves to the
  intended value precisely because of it. Rejecting callable-then returns
  would break that; intercepting pre-assimilation is spec-impossible (the
  Get(v,'then') and job enqueue are internal to promise resolution).
- The realm-boundary guard applies to the RESOLUTION (a thenable resolving to
  non-JSON is still RESULT_UNSERIALIZABLE), so nothing crosses unmaterialized.
- A spin inside a returned thenable's then() is the same accepted class as any
  post-slice spin (it runs on the microtask queue, past the vm timeout's
  reach); the docs previously said 'after the first await', which was too
  narrow — reworded to 'past the initial synchronous slice (an await
  continuation, or a thenable's then invoked by promise resolution)'.

Pinned with an engine test (un-awaited return agent(); custom thenable
resolution as the return value; thenable resolving to non-JSON rejects), and
the limitation wording updated in the module doc, README, and RFC.
This commit is contained in:
Tianyi Cui
2026-07-05 20:57:51 +08:00
parent fff2e1f33d
commit 95c8c878e1
4 changed files with 26 additions and 9 deletions

View File

@@ -12,13 +12,17 @@
* level as the model's bash access — and the realm-boundary materialization
* is correctness containment, not a sandbox.
* - The vm `timeout` covers only the initial SYNCHRONOUS slice of the script;
* a pathological synchronous spin after the first await cannot be killed
* in-process. `dispose()` waits a bounded grace for the script to settle
* AND its children (stray `agent()` calls included) to finish disposing,
* then ABANDONS whatever is left: pending hook promises are already
* rejected and the script's settlement is contained (no unhandled
* rejection), but an abandoned synchronous spin would still occupy the
* event loop.
* realm code that runs past that slice — an await continuation, a
* thenable's `then` invoked by promise resolution (including one the script
* RETURNS: a returned thenable resolves per JavaScript semantics before
* materialization, which is what makes an un-awaited `return agent('x')`
* work) — is beyond the timeout, so a pathological synchronous spin there
* cannot be killed in-process. `dispose()` waits a bounded grace for the
* script to settle AND its children (stray `agent()` calls included) to
* finish disposing, then ABANDONS whatever is left: pending hook promises
* are already rejected and the script's settlement is contained (no
* unhandled rejection), but an abandoned synchronous spin would still
* occupy the event loop.
*
* Plugin export shape: a default-exported {@link WorkflowService} subclass
* (the class-based service form, like `dsh-bash-local`).