# @smithers-orchestrator/errors — src

The shared error vocabulary for smithers: `SmithersError` (a coded `Error` with
`summary`/`docsUrl`/`details`), Effect `Data.TaggedError` classes for engine
faults (`TaskAborted`, `TaskTimeout`, `TaskHeartbeatTimeout`, `RunNotFound`,
`InvalidInput`, `DbWriteFailed`, `AgentCliError`, `WorkflowFailed`,
`EngineError`), the `smithersErrorDefinitions` code catalog, and converters
between representations. Everything here is re-exported to consumers through
the `packages/smithers` umbrella.

Three representations, and how they convert:

- Live tagged errors inside Effect code (the `Data.TaggedError` classes).
- `SmithersError` at CLI/API boundaries: `toSmithersError` normalizes any
  unknown value; `fromTaggedError` maps a tagged error to a `SmithersError`.
- JSON-safe forms for durable DB writes: `errorToJson` guarantees
  `JSON.stringify` can never throw on its output; `toTaggedErrorPayload` /
  `fromTaggedErrorPayload` round-trip tagged errors with finite-number coercion.

Key entry points: `index.js` (public barrel), `SmithersError.js`,
`toSmithersError.js`, `errorToJson.js`, `smithersErrorDefinitions.js`.
`assertZodV4.js` is the Zod v4-only fail-fast guard used at workflow
construction.

Gotchas:

- `index.d.ts` is generated by `tsup --dts-only` into src/ — never hand-edit.
- The `@smithers-type-exports` block in `index.js` is tool-managed; preserve it
  byte-for-byte.
- `*.ts` files are type-only sidecars, imported with `.ts` specifiers even from
  `.js` value modules — that is the package-wide convention.
- `tests/error-declarations.test.js` locks the catalog keys in
  `smithersErrorDefinitions.js` to the declare-namespace entries in `index.d.ts`.
