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#
(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#
| { 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.
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#
(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#
(typeof ERROR_VIOLATION_KINDS)[number];
EVENT_SEVERITIES#
Values: info, warning, error, critical
EventSeverity#
(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#
(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#
(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.
lookupCause(request: SupportLookupRequest, store: CauseStore): SupportLookupOutcome
mapCause#
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.
parseSupportReference(input: unknown): ParseResult<CorrelationId>
PUBLIC_ERROR_SCHEMA_VERSION#
Value: 1
publicError#
Build a public envelope, or refuse.
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#
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#
(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#
(typeof RPC_STATUSES)[number];
SafeParam#
A value that may cross the boundary.
string | number | boolean;
scanEnvelope#
Every leak in an envelope, in a stable order.
scanEnvelope(envelope: PublicErrorEnvelope, options: LeakScanOptions = {}): readonly Leak[]
scanText#
The value scan, on its own.
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#
| { 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.
transportTable(registry: ErrorRegistry): readonly TransportRow[]
UNMAPPED_CAUSE_CODE#
The code an unmapped cause becomes.
Value: 'internal.unexpected'
validateErrorRegistry#
validateErrorRegistry(registry: ErrorRegistry): readonly ErrorViolation[]
validateMappings#
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
"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
"body.selectedVariants"
lookalike/a-plain-url-with-no-signature#
a documentation link is the thing the remediation field is for
"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
"«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
"sk-live-4f9a2b7c1d3e5f60718293a4b5c6d7e8"
canary/bearer-token#
a JWT, which is a credential a client will happily log
"«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.jsonevidence/v1-workbenches/workbench-kit-export-map.jsonlibs/oshun/workbench-kit/src/errors.ts