effects: put the Result envelope in every operation's return type - #1607

Stage 3 of the IoEffect migration
(fjs/effects/todo/io-effect-migration.md). Stages 1 and 2 — the types and the
composition API — shipped in #1599 and #1604.

Every operation in fjs/effects/node and fjs/effects/memory now declares a
Result return, every runner answers with one, and host failures are
normalized into a structured IoError instead of the bare unknown that used
to erase the NotImplemented distinction.

Where the envelope lives

In the operation's declared return type, not in a wrapper a constructor
applies — that is the only channel through which stage 6 can deliver
error(notImplemented) to a Do node's continuation. Two aliases carry it:

• OpResult<T> = Result<T, NotImplemented> — an operation with no failures
  of its own (now, randomInt, all, write, read, sandbox, test,
  the memory ops, …).
• IoResult<T> = Result<T, NotImplemented | IoError> — refined in place from
  Result<T, unknown> for host IO.

Runners stay total: NotImplemented is in the type model and nothing produces
it yet.

IoError

readonly['ioError', { code?: string, message: string }] — a tagged tuple
beside NotImplemented so the shared channel stays discriminable, in
fjs/effects/node/types.ts beside the operations that report it. The bare
unknown had to go for a specific reason: NotImplemented | unknown collapses
to unknown, so a program could not tell "this runner cannot do it" from "the
host tried and failed".

toIoError normalizes a thrown value at the single boundary where an impure
runner catches, keeping the OS code when the host attached one — which is
what isNotFound still reads. The virtual runner reports the same shape, so a
proof against the virtual filesystem is still evidence about the real one.

SandboxResult.result stays a Result inside the envelope: it is the
sandboxed function's outcome — returned data, not effect status.

Write and Read stayed OpResult. They are host IO and could fail
(EPIPE), but this stage's rule for a currently-infallible handler is to wrap
its output in ok(...), not to invent a failure the runner never reported.
Promoting them is a behavior change and belongs in its own issue.

The value-discarding sweep

This is the part tsc cannot do, and the hazard the whole migration is about:
a continuation that reads the operation's value broke loudly, while
() => next kept compiling and silently ignored the new error channel. Every
such site now states a policy, and two of them are named so the stragglers stay
findable:

• unwrapStep (fjs/effects/io/module.f.mjs) — leave the layer by
  panicking on the error branch. One greppable name rather than an unwrap
  buried in a continuation, so the set of sites that have not yet chosen
  anything better is exactly the set this name marks. That is the worklist
  stage 4 starts from.
• exitStep / errorMessage (fjs/effects/node/module.f.mjs) — a
  NodeProgram's exit-code policy: report the failure on stderr, exit 1.
  This replaces step(log(x), () => pure(0)) at program tails, which used to
  exit 0 whether or not the write landed.

errorExit keeps discarding its own write's outcome, deliberately and with the
reasoning in its JSDoc: the program is already failing, and the exit code is
1 whether or not stderr accepted the bytes.

Consumers

Per the plan, consumers are not migrated to Io composition here — that is
stage 4. Each one keeps its existing failure policy and changes only what the
envelope forces: modules that already panicked on IO failure (fjs/dev,
fjs/ci, fjs/nanvm/update, the test reporter) now say so with unwrapStep,
and the two places where the envelope simplified something took it —
readUtf8File is now mapStep over the Io layer, and the MCP stdio transport
returns write's own result instead of rebuilding an ok.

Checks

npx tsc clean; fjs t 2919 pass / 0 fail; npm run cov reports 100%
line/branch/function with the #1605 gate enabled; npm run ci-update
regenerates nothing.

Changelog:

• BREAKING CHANGES: effects: every operation's return type carries a
  Result. Infallible operations answer OpResult<T>
  (Result<T, NotImplemented>); host IO answers IoResult<T>, whose error is
  now the structured NotImplemented | IoError rather than unknown. Runner
  handlers wrap their output in ok(...); isNotFound takes a channel error
• effects/node: new IoError / IoErrorInfo / OpResult types with
  ioError, toIoError, errorMessage and exitStep, the NodeProgram
  exit-code policy
• effects/io: new unwrapStep, which leaves the layer by panicking on the
  error branch

🤖 Generated with Claude Code

https://claude.ai/code/session_018gTX18dhKRpQDAGoQWKiFb

Generated by Claude Code