# @smithers-orchestrator/driver — src

The workflow execution driver: the loop that turns a rendered workflow into
scheduled work and acts on the engine's decisions.

- `WorkflowDriver.js` — the run loop. Renders the workflow via a
  `WorkflowGraphRenderer`, submits graphs to a scheduler `WorkflowSession`, and
  acts on `EngineDecision`s (Execute / ReRender / Wait / ContinueAsNew /
  Finished / Failed). Keeps tasks in-flight without blocking scheduling (#267).
- `SmithersCtx.js` — the render-time ctx handed to a workflow's `build()`:
  `input`, `iterations`, `output()`, `outputMaybe()`, `latest()`,
  `worktreePath()`, plus `_deferredDeps` that the engine reads after each render.
- Loop-scope machinery: node ids inside loops carry `@@ancestor=iter` scope
  suffixes. `buildCurrentScopes.js`, `filterRowsByNodeId.js`, and
  `withLogicalIterationShortcuts.js` resolve scoped output rows and iteration
  shortcuts for the current render; `normalizeInputRow.js` unwraps the
  persisted `{ runId, payload }` input row.
- Entry points (package.json exports): `index.js` (WorkflowDriver +
  SmithersCtx), `task-runtime.js` (AsyncLocalStorage-scoped SmithersTaskRuntime
  for builder steps), `child-process.js` (`spawnCaptureEffect` — Effect-wrapped
  spawn with total/idle timeouts, tree kill, byte-capped capture), `interop.js`
  (re-exports `ignoreSyncError`). The `./*` wildcard export makes every module
  here public surface.

Gotchas: implementation is `.js` + JSDoc with type-only `.ts` sidecars
(`RunOptions.ts`, `WorkflowSession.ts`, ...). `index.d.ts` is generated by
`tsup --dts-only` — never hand-edit. The `@smithers-type-exports` block in
`index.js` is tool-managed. Helpers here are imported directly by tests and by
engine/agents/sandbox/components, so do not inline or rename them.
