Eve library

Error

Evidence

Revision 1

On this page

The stable code registry and the safe public envelope, which is constructed rather than filtered.

Generated from libs/oshun/workbench-kit/src/errors.ts by node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger: S1.9 / S1.10. Do not edit by hand.

Summary#

  • src/errors.ts
Entry point Runtime class Authorized by
@oshun/workbench-kit/errors contract S1.9 / S1.10

Exports#

Symbol Kind Summary
CAUSE_KINDS enumeration —
CauseKind type —
CauseMapping interface —
CauseStore interface —
CodeDeprecation interface —
CodeResolution type —
DEFAULT_CAUSE_MAPPINGS constant The default cause mappings, keyed on identifiers each source PUBLISHES.
envelopeMatchesCause function The join, checked in the direction that matters.
ERROR_NAMESPACES enumeration The twelve namespaces, closed.
ERROR_REGISTRY constant The codes seven workbenches share.
ERROR_REGISTRY_VERSION constant —
ERROR_VIOLATION_KINDS enumeration —
ErrorCodeEntry interface —
ErrorNamespace type —
ErrorRegistry interface —
ErrorViolation interface —
ErrorViolationKind type —
EVENT_SEVERITIES enumeration —
EventSeverity type —
InternalCause interface The privileged half. NOTHING here is public — not the message, not the context, and obviously not the stack.
JOB_DISPOSITIONS enumeration What a worker does with an attempt that failed with this code.
JobDisposition type —
Leak interface —
LEAK_CLASSES enumeration —
LeakClass type —
LeakScanOptions interface —
lookupCause function Resolve an envelope's correlation id to its cause, under authorization.
mapCause function —
parseSupportReference function Parse a correlation id the way a support tool receives one: as text.
PUBLIC_ERROR_SCHEMA_VERSION constant —
publicError function Build a public envelope, or refuse.
PublicErrorDetail interface —
PublicErrorEnvelope interface —
PublicErrorInput interface —
resolveCode function —
RetiredCode interface —
RETRYABILITIES enumeration What a caller should do next — which is not the same question as whether the failure was the caller's fault.
Retryability type —
RPC_STATUSES enumeration The subset of gRPC statuses this kit maps onto.
RpcStatus type —
SafeParam type A value that may cross the boundary.
scanEnvelope function Every leak in an envelope, in a stable order.
scanText function The value scan, on its own.
SUPPORT_SCOPE constant —
SupportAudit interface The record a lookup PRODUCES.
SupportLookupOutcome type —
SupportLookupRequest interface —
TransportRow interface —
transportTable function The per-code transport mapping, sorted, derived from the registry alone.
UNMAPPED_CAUSE_CODE constant The code an unmapped cause becomes.
validateErrorRegistry function —
validateMappings function —

Shapes#

CAUSE_KINDS#

Values: domain, internal, provider, database, queue, bridge

CauseKind#

ts
(typeof CAUSE_KINDS)[number];

CauseMapping#

Field Type Required Notes
kind CauseKind required —
source string | null required Null matches any source of this kind — a deliberate, coarser rule.
classifier string required —
code string required —

CauseStore#

Field Type Required Notes
read (correlationId: CorrelationId) => InternalCause | null — CorrelationId, InternalCause required —

CodeDeprecation#

Field Type Required Notes
deprecatedIn number required —
removedIn number | null required The registry version it stops being emitted in, or null when undecided.
replacedBy string required —
reason string required —

CodeResolution#

ts
| { readonly status: 'known'; readonly entry: ErrorCodeEntry }
| { readonly status: 'deprecated'; readonly entry: ErrorCodeEntry; readonly replacedBy: string }
| { readonly status: 'retired'; readonly retiredIn: number; readonly reason: string }
| { readonly status: 'unknown'; readonly namespace: ErrorNamespace; readonly retryability: Retryability; }
| { readonly status: 'unparseable' }

DEFAULT_CAUSE_MAPPINGS#

The default cause mappings, keyed on identifiers each source PUBLISHES.

envelopeMatchesCause#

The join, checked in the direction that matters.

ts
envelopeMatchesCause(envelope: PublicErrorEnvelope, cause: InternalCause): ParseResult<null>

ERROR_NAMESPACES#

The twelve namespaces, closed.

Values: validation, authentication, authorization, tenancy, conflict, state, dependency, provider, job, policy, quota, internal

ERROR_REGISTRY#

The codes seven workbenches share.

ERROR_REGISTRY_VERSION#

Value: 3

ERROR_VIOLATION_KINDS#

Values: malformed-code, code-namespace-mismatch, duplicate-code, namespace-without-codes, since-above-registry-version, retired-code-reregistered, retired-code-not-removed, deprecated-without-replacement, replacement-not-registered, replacement-itself-deprecated, replacement-changes-retryability, internal-code-carrying-detail-keys, malformed-detail-key, retryability-contradicts-http-status, retryability-contradicts-job-disposition, rpc-status-contradicts-http-status, quota-code-without-backoff, missing-unmapped-fallback, duplicate-mapping, mapping-to-unknown-code, mapping-on-a-message-not-a-classifier

ErrorCodeEntry#

Field Type Required Notes
code string required —
namespace ErrorNamespace required —
since number required Registry version this code was introduced in.
summary string required One line, for a human reading the registry. Never sent to a client.
retryability Retryability required —
httpStatus number required —
rpcStatus RpcStatus required —
jobDisposition JobDisposition required —
eventSeverity EventSeverity required —
remediation RemediationAction required —
detailKeys readonly string[] required The ONLY parameter keys an envelope for this code may carry.
deprecation CodeDeprecation | null — CodeDeprecation required —

ErrorNamespace#

ts
(typeof ERROR_NAMESPACES)[number];

ErrorRegistry#

Field Type Required Notes
version number required —
entries readonly ErrorCodeEntry[] — ErrorCodeEntry required —
retired readonly RetiredCode[] — RetiredCode required Codes that were removed. They may never come back with new semantics: an old client still has the old meaning compiled in and would handle the new failure as the old one, silently and correctly-looking.

ErrorViolation#

Field Type Required Notes
kind ErrorViolationKind required —
subject string required —
detail string required —

ErrorViolationKind#

ts
(typeof ERROR_VIOLATION_KINDS)[number];

EVENT_SEVERITIES#

Values: info, warning, error, critical

EventSeverity#

ts
(typeof EVENT_SEVERITIES)[number];

InternalCause#

The privileged half. NOTHING here is public — not the message, not the context, and obviously not the stack.

Field Type Required Notes
kind CauseKind required —
source string required The subsystem that produced it: a service, a driver, a provider name.
classifier string required A STABLE identifier the source publishes: a SQLSTATE, a provider error code, a domain error name. Never a message.
message string required —
stack string | null required —
context Readonly<Record<string, unknown>> required —
occurredAt Instant required —
correlationId CorrelationId required —
traceId TraceId | null — TraceId required —
tenant TenantId | null — TenantId required —
retainedUntil Instant required When the cause may no longer be read. Retention is a decision, not a bug.

JOB_DISPOSITIONS#

What a worker does with an attempt that failed with this code.

Values: retry, dead-letter, fail-fast, park-for-operator

JobDisposition#

ts
(typeof JOB_DISPOSITIONS)[number];

Leak#

Field Type Required Notes
leakClass LeakClass required —
at string required Where in the envelope it was found, e.g. messageParams.detail.
why string required —

LEAK_CLASSES#

Values: bearer-token, api-key, private-key, signed-url, connection-string, stack-frame, sql, email-address, phone-number, prompt, cross-tenant-id

LeakClass#

ts
(typeof LEAK_CLASSES)[number];

LeakScanOptions#

Field Type Required Notes
tenant TenantId | null — TenantId optional The tenant the envelope is being sent TO. Any other tenant id appearing in it is cross-tenant detail — the leak that looks like a helpful message.
canaries readonly string[] optional Extra literal strings that must not appear. Used by canary tests.

lookupCause#

Resolve an envelope's correlation id to its cause, under authorization.

ts
lookupCause(request: SupportLookupRequest, store: CauseStore): SupportLookupOutcome

mapCause#

ts
mapCause(cause: Pick<InternalCause, 'kind' | 'source' | 'classifier'>, mappings: readonly CauseMapping[], registry: ErrorRegistry): ErrorCodeEntry

parseSupportReference#

Parse a correlation id the way a support tool receives one: as text.

ts
parseSupportReference(input: unknown): ParseResult<CorrelationId>

PUBLIC_ERROR_SCHEMA_VERSION#

Value: 1

publicError#

Build a public envelope, or refuse.

ts
publicError(entry: ErrorCodeEntry, input: PublicErrorInput): ParseResult<PublicErrorEnvelope>

PublicErrorDetail#

Field Type Required Notes
key string required —
value SafeParam required —

PublicErrorEnvelope#

Field Type Required Notes
schemaVersion number required —
code string required —
messageKey string required An i18n KEY. The text lives with the translations, not in the payload.
messageParams Readonly<Record<string, SafeParam>> — SafeParam required —
field readonly string[] | null required Path into the REQUEST the caller sent, or null when it is not a field.
reference string | null required An opaque, caller-visible reference (their own object), or null.
retryability Retryability required —
retryAfterSeconds number | null required —
remediation Remediation required —
correlationId CorrelationId required Joins to the internal cause, through and nothing else.
details readonly PublicErrorDetail[] — PublicErrorDetail required —

PublicErrorInput#

Field Type Required Notes
messageKey string required —
messageParams Readonly<Record<string, SafeParam>> — SafeParam optional —
field readonly string[] | null optional —
reference string | null optional —
retryAfterSeconds number | null optional —
docsUrl string | null optional —
requiresOperator boolean optional —
details readonly PublicErrorDetail[] — PublicErrorDetail optional —
correlationId CorrelationId required —
tenant TenantId | null — TenantId optional —

resolveCode#

ts
resolveCode(code: string, registry: ErrorRegistry): CodeResolution

RetiredCode#

Field Type Required Notes
code string required —
retiredIn number required —
reason string required —

RETRYABILITIES#

What a caller should do next — which is not the same question as whether the failure was the caller's fault.

Values: no, after-backoff, after-change, after-remediation

Retryability#

ts
(typeof RETRYABILITIES)[number];

RPC_STATUSES#

The subset of gRPC statuses this kit maps onto.

Values: invalid-argument, unauthenticated, permission-denied, not-found, already-exists, failed-precondition, aborted, resource-exhausted, unavailable, deadline-exceeded, internal

RpcStatus#

ts
(typeof RPC_STATUSES)[number];

SafeParam#

A value that may cross the boundary.

ts
string | number | boolean;

scanEnvelope#

Every leak in an envelope, in a stable order.

ts
scanEnvelope(envelope: PublicErrorEnvelope, options: LeakScanOptions = {}): readonly Leak[]

scanText#

The value scan, on its own.

ts
scanText(value: string, at: string, options: LeakScanOptions = {}): readonly Leak[]

SUPPORT_SCOPE#

Value: 'support:read-cause'

SupportAudit#

The record a lookup PRODUCES.

Field Type Required Notes
correlationId CorrelationId required —
actor ActorRef required —
at Instant required —
tenant TenantId | null — TenantId required —

SupportLookupOutcome#

ts
| { readonly outcome: 'found'; readonly cause: InternalCause; readonly audit: SupportAudit }
| { readonly outcome: 'unauthorized'; readonly missingScopes: readonly string[] }
| { readonly outcome: 'not-found' }
| { readonly outcome: 'expired'; readonly retainedUntil: Instant }

SupportLookupRequest#

Field Type Required Notes
correlationId CorrelationId required —
actor ActorRef required —
scopes readonly string[] required —
now Instant required —

TransportRow#

Field Type Required Notes
code string required —
httpStatus number required —
rpcStatus RpcStatus required —
jobDisposition JobDisposition required —
eventSeverity EventSeverity required —
retryability Retryability required —
deprecated boolean required —

transportTable#

The per-code transport mapping, sorted, derived from the registry alone.

ts
transportTable(registry: ErrorRegistry): readonly TransportRow[]

UNMAPPED_CAUSE_CODE#

The code an unmapped cause becomes.

Value: 'internal.unexpected'

validateErrorRegistry#

ts
validateErrorRegistry(registry: ErrorRegistry): readonly ErrorViolation[]

validateMappings#

ts
validateMappings(mappings: readonly CauseMapping[], registry: ErrorRegistry): readonly ErrorViolation[]

Valid examples#

lookalike/a-dated-slug-that-starts-like-a-key#

this is the price of letting the api-key body carry separators, and it is where the boundary sits: 17 body characters, so a plausible dated identifier passes while every real key (32 and up from every issuer) is still caught

json
"sk-2026-01-15-report"
lookalike/a-field-path-that-mentions-select#

the SQL detector must require a FROM as well, or every field named select trips it

json
"body.selectedVariants"
lookalike/a-plain-url-with-no-signature#

a documentation link is the thing the remediation field is for

json
"https://docs.example/errors/validation"

3 of 6 accepted case(s) shown. The full corpus is committed at evidence/v1-workbenches/workbench-kit-error-fixtures.json and is what the gate runs.

Invalid examples#

canary/api-key#

a provider API key, which grants whatever the key was issued for and is rotated by nobody until it appears in a support ticket

json
"«redacted api-key»"
canary/api-key-segmented#

the SEGMENTED form every issuer actually uses (sk-live-, sktest, sk-proj-, sk-ant-); the first version of the detector required an unbroken alphanumeric body and therefore matched only the shape nobody issues

json
"sk-live-4f9a2b7c1d3e5f60718293a4b5c6d7e8"
canary/bearer-token#

a JWT, which is a credential a client will happily log

json
"«redacted bearer-token»"

api-key, bearer-token value(s) above are REDACTED. This corpus deliberately carries credential-shaped canaries so the leak scan can be proven to detect them, and a reference page that reproduced one would put a working-looking credential in the documentation. The unredacted corpus is the committed artifact, which is what the gate runs.

3 of 12 refused case(s) shown. The full corpus is committed at evidence/v1-workbenches/workbench-kit-error-fixtures.json and is what the gate runs.

Authorization and scope#

| Symbol | Type | Notes | | ----------------------------- | ------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | InternalCause.tenant | TenantId | null | — | | LeakScanOptions.tenant | TenantId | null | The tenant the envelope is being sent TO. Any other tenant id appearing in it is cross-tenant detail — the leak that looks like a helpful message. | | PublicErrorInput.tenant | TenantId | null | — | | SUPPORT_SCOPE | constant | — | | SupportAudit.actor | ActorRef | — | | SupportAudit.tenant | TenantId | null | — | | SupportLookupRequest.actor | ActorRef | — | | SupportLookupRequest.scopes | readonly string[] | — |

Idempotency and concurrency#

Not applicable: nothing on this page is retried or applied twice: these are declarations, not operations.

Pagination#

Not applicable: nothing on this page returns a collection a caller reads in pages.

State and failure#

Symbol Type Notes
ERROR_NAMESPACES enumeration The twelve namespaces, closed.
ERROR_REGISTRY constant The codes seven workbenches share.
ERROR_REGISTRY_VERSION constant —
ERROR_VIOLATION_KINDS enumeration —
ErrorCodeEntry.httpStatus number —
ErrorCodeEntry.rpcStatus RpcStatus —
ErrorNamespace type —
ErrorViolationKind type —
PUBLIC_ERROR_SCHEMA_VERSION constant —
publicError function Build a public envelope, or refuse.
RPC_STATUSES enumeration The subset of gRPC statuses this kit maps onto.
RpcStatus type —
SupportLookupOutcome type —
TransportRow.httpStatus number —
TransportRow.rpcStatus RpcStatus —
validateErrorRegistry function —

Compatibility#

Symbol Type Notes
ERROR_REGISTRY_VERSION constant —
ErrorRegistry.version number —
PUBLIC_ERROR_SCHEMA_VERSION constant —
PublicErrorEnvelope.schemaVersion number —

Deprecation#

| Symbol | Type | Notes | | ------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | | CodeDeprecation.deprecatedIn | number | — | | ErrorCodeEntry.deprecation | CodeDeprecation | null | — | | ErrorRegistry.retired | readonly RetiredCode[] | Codes that were removed. They may never come back with new semantics: an old client still has the old meaning compiled in and would handle the new failure as the old one, silently and correctly-looking. | | RetiredCode.retiredIn | number | — | | TransportRow.deprecated | boolean | — |

Evidence#

  • evidence/v1-workbenches/workbench-kit-error-fixtures.json
  • evidence/v1-workbenches/workbench-kit-export-map.json
  • libs/oshun/workbench-kit/src/errors.ts