@prestack/thread 0.0.1 → 0.0.2

package/dist/operations/dispatch.ts

@@ -0,0 +1,348 @@
+import { ANONYMOUS, ENVIRONMENT } from '../core/actor.ts'
+import { errorDefForResult } from './error-results.ts'
+import { DbConflict } from './errors/errors.ts'
+import { quoted, runtime } from './generators/seed.ts'
+import type { ResultCode } from './result.ts'
+import { SUPPLY, type AuditOutcome } from './seams.ts'
+
+export const DISPATCH_AT = 'operations/_dispatch.ts'
+
+const identity = (code: ResultCode): { readonly code: string; readonly class: string } => {
+  const def = errorDefForResult(code)
+  return { code: def.code, class: def.class }
+}
+
+const CODES: readonly ResultCode[] = ['denied', 'invalid', 'rate_limited', 'feature_denied', 'quota_exceeded', 'error']
+
+const REFUSAL: Readonly<Record<ResultCode, { readonly said: string; readonly outcome: AuditOutcome }>> = {
+  denied: { said: 'not allowed', outcome: 'denied' },
+  invalid: { said: 'invalid input', outcome: 'failed' },
+  rate_limited: { said: 'rate limited', outcome: 'rate_limited' },
+  feature_denied: { said: 'not in plan', outcome: 'feature_denied' },
+  quota_exceeded: { said: 'quota exceeded', outcome: 'quota_exceeded' },
+  error: { said: 'failed', outcome: 'failed' },
+}
+
+const printed = (value: unknown): string => JSON.stringify(value, null, 2)
+
+const DEFS = Object.fromEntries(CODES.map((code) => [code, identity(code)]))
+
+export const dispatched = (
+  reached: Readonly<
+    Record<
+      string,
+      {
+        readonly reach: string
+        readonly address: string | null
+        readonly sends: readonly { readonly secret: string; readonly header: string; readonly prefix: string }[]
+        readonly calls: Readonly<Record<string, { readonly method: string; readonly path: string }>>
+      }
+    >
+  >,
+): string => [
+  `import type { Actor } from ${quoted(runtime(DISPATCH_AT, '../../core/actor.ts'))}`,
+  `import type { Operation } from ${quoted(runtime(DISPATCH_AT, '../operations.ts'))}`,
+  `import type { FailureIdentity, Result, ResultCode } from ${quoted(runtime(DISPATCH_AT, '../result.ts'))}`,
+  `import type { AuditOutcome, Handed, LogLevel, QuotaHold, Seams } from ${quoted(runtime(DISPATCH_AT, '../seams.ts'))}`,
+  '',
+  `const ANONYMOUS: Actor = ${printed(ANONYMOUS)}`,
+  '',
+  `const ENVIRONMENT: readonly string[] = ${printed(ENVIRONMENT.map(([fact]) => fact))}`,
+  '',
+  `const REFUSAL: Readonly<Record<ResultCode, { readonly said: string; readonly outcome: AuditOutcome }>> = ${printed(REFUSAL)}`,
+  '',
+  `const DEFS = ${printed(DEFS)} as Readonly<Record<ResultCode, FailureIdentity>>`,
+  '',
+  `const CONFLICT = ${printed({ code: DbConflict.def.code, class: DbConflict.def.class })} as FailureIdentity`,
+  '',
+  `const SUPPLY: Readonly<Record<string, string>> = ${printed(SUPPLY)}`,
+  '',
+  'type Reached = Readonly<Record<string, {',
+  '  readonly reach: string',
+  '  readonly address: string | null',
+  '  readonly sends: readonly { readonly secret: string; readonly header: string; readonly prefix: string }[]',
+  '  readonly calls: Readonly<Record<string, { readonly method: string; readonly path: string }>>',
+  '}>>',
+  '',
+  `const REACHED: Reached = ${printed(reached)}`,
+  '',
+  "const STOPPED = Symbol.for('thread.operation.stopped')",
+  '',
+  'const ok = <O>(value: O): Result<O> => ({ ok: true, value })',
+  '',
+  'const fail = (code: ResultCode, error: string, because?: string, identity?: FailureIdentity): Result<never> => ({',
+  '  ok: false,',
+  '  code,',
+  '  error,',
+  '  because,',
+  '  ...(identity === undefined ? {} : { errorCode: identity.code, errorClass: identity.class }),',
+  '}) as Result<never>',
+  '',
+  "const strings = (value: unknown): value is string[] => Array.isArray(value) && value.every((one) => typeof one === 'string')",
+  '',
+  'const person = (value: unknown): Actor | undefined => {',
+  "  if (typeof value !== 'object' || value === null) return undefined",
+  '  const one = value as Record<string, unknown>',
+  "  const id = one['id']",
+  "  if (!(id === null || typeof id === 'string')) return undefined",
+  "  const roles = one['roles']",
+  "  const entitlements = one['entitlements']",
+  '  if (!strings(roles) || !strings(entitlements)) return undefined',
+  '  const carried: Record<string, string> = {}',
+  '  for (const fact of ENVIRONMENT) {',
+  '    const held = one[fact]',
+  '    if (held === undefined) continue',
+  "    if (typeof held !== 'string') return undefined",
+  '    carried[fact] = held',
+  '  }',
+  '  return { ...carried, id, roles, entitlements }',
+  '}',
+  '',
+  'const named = (thrown: unknown, what: string): boolean => {',
+  "  if (typeof thrown !== 'object' || thrown === null) return false",
+  '  const one = thrown as { readonly name?: unknown; readonly constructor?: { readonly name?: unknown } }',
+  '  return one.name === what || one.constructor?.name === what',
+  '}',
+  '',
+  'const stopped = (thrown: unknown): { readonly value: unknown } | undefined => {',
+  "  if (typeof thrown !== 'object' || thrown === null) return undefined",
+  '  const one = thrown as Record<PropertyKey, unknown>',
+  "  return one[STOPPED] === true ? { value: one['value'] } : undefined",
+  '}',
+  '',
+  'const marked = (thrown: unknown): string | undefined => {',
+  "  if (typeof thrown !== 'object' || thrown === null) return undefined",
+  '  const said = (thrown as { readonly node?: unknown }).node',
+  "  return typeof said === 'string' ? said : undefined",
+  '}',
+  '',
+  'const platform = (thrown: unknown): string | undefined => {',
+  "  if (typeof thrown !== 'object' || thrown === null) return undefined",
+  '  const said = (thrown as { readonly because?: unknown }).because',
+  "  return typeof said === 'string' ? said : undefined",
+  '}',
+  '',
+  'const filled = (path: string, fills: Readonly<Record<string, string | number>> | undefined): string => {',
+  '  let held = path',
+  '  for (const [name, value] of Object.entries(fills ?? {})) held = held.split(`{${name}}`).join(encodeURIComponent(String(value)))',
+  '  const left = /\\{([a-z][a-z0-9_]*)\\}/.exec(held)',
+  '  if (left !== null) throw new Error(`the path ${path} leaves ${left[0]} to be filled and nothing filled it`)',
+  '  return held',
+  '}',
+  '',
+  'const bound = (word: string, wired: Reached[string], seams: Seams): Record<string, unknown> | string => {',
+  '  const names = Object.keys(wired.calls)',
+  '  if (names.length === 0) {',
+  '    return `\\`${word}\\` is required and takes no call, so there is nothing to hand a node. Declare one with \\`thread create target call\\``',
+  '  }',
+  '  if (seams.http === undefined) {',
+  '    return `\\`${word}\\` is reached over ${wired.reach} and the seams this dispatch was handed hold no \\`http\\` — wire one, or take \\`${word}\\` off that operation\'s row`',
+  '  }',
+  '  const wanted = [...(wired.address === null ? [] : [wired.address]), ...wired.sends.map((one) => one.secret)]',
+  '  if (wanted.length > 0 && seams.vault === undefined) {',
+  '    return `\\`${word}\\` needs ${wanted.join(\', \')} and the seams this dispatch was handed hold no \\`vault\\` to open them. A target is reached with what opens it or not at all`',
+  '  }',
+  '  const out: Record<string, unknown> = {}',
+  '  for (const name of names) {',
+  '    const call = wired.calls[name]',
+  '    if (call === undefined) continue',
+  '    out[name] = async (given?: { fills?: Readonly<Record<string, string | number>>; json?: unknown; body?: Uint8Array; contentType?: string }) => {',
+  '      const values = wanted.length === 0 ? {} : await seams.vault!.resolve(wanted)',
+  '      const headers: Record<string, string> = {}',
+  '      for (const one of wired.sends) headers[one.header] = `${one.prefix}${values[one.secret] ?? \'\'}`',
+  '      const body = given?.json === undefined ? given?.body : new TextEncoder().encode(JSON.stringify(given.json))',
+  '      return await seams.http!.call({',
+  '        target: word,',
+  '        address: wired.address === null ? \'\' : (values[wired.address] ?? \'\'),',
+  "        method: call.method as 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',",
+  '        path: filled(call.path, given?.fills),',
+  '        headers,',
+  '        ...(body === undefined ? {} : { body, contentType: given?.contentType ?? \'application/json\' }),',
+  '      })',
+  '    }',
+  '  }',
+  '  return out',
+  '}',
+  '',
+
+  'const given = (operation: Operation<unknown, string>, actor: Actor, seams: Seams): Record<string, unknown> | string => {',
+  '  const held: Record<string, unknown> = { actor }',
+  '  for (const word of operation.requires) {',
+  '    const key = SUPPLY[word]',
+  '    if (key === undefined) {',
+  '      const wired = REACHED[word]',
+  '      if (wired === undefined) {',
+  '        return `\\`${operation.id}\\` requires \\`${word}\\`, and nothing here supplies it — what may be required is ${[...Object.keys(SUPPLY), ...Object.keys(REACHED)].join(\', \')}`',
+  '      }',
+  '      const reached = bound(word, wired, seams)',
+  "      if (typeof reached === 'string') return reached",
+  '      held[word] = reached',
+  '      continue',
+  '    }',
+  '    const seam = (seams as unknown as Record<string, unknown>)[key]',
+  '    if (seam === undefined) {',
+  '      return `\\`${operation.id}\\` requires \\`${word}\\`, and the seams this dispatch was handed hold no \\`${key}\\` — wire one, or take \\`${word}\\` off that operation\'s row. An operation does not run short of what it declared`',
+  '    }',
+  '    held[key] = seam',
+  '  }',
+  '  return held',
+  '}',
+  '',
+  'export async function dispatch<I, R extends string = string>(',
+  '  operation: Operation<I, R>,',
+  '  rawInput: unknown,',
+  '  asking: Actor,',
+  '  handed: Seams,',
+  '): Promise<Result<unknown>> {',
+  '  const seams = running(handed)',
+  '  const id = operation.id',
+  '  const who = person(asking)',
+  '  const run = who?.run ?? seams.random.uuid()',
+  '  const actor: Actor = { ...(who ?? ANONYMOUS), run }',
+  '  const span = seams.telemetry?.start(id, run, { ...actor })',
+  '',
+  '  const gates = { rate: seams.rateLimiter !== undefined, replay: seams.idempotency !== undefined, quota: seams.quotas !== undefined, telemetry: seams.telemetry !== undefined }',
+  '',
+  '  let hold: QuotaHold | null = null',
+  '  let granted: string | undefined',
+  '',
+  '  const sank = (what: string) => (thrown: unknown): void => {',
+  "    seams.log?.write('error', id, actor, {",
+  '      [`${what}_failed`]: thrown instanceof Error ? thrown.message : String(thrown),',
+  '    })',
+  '  }',
+  '',
+  '  const settled = async (held: Result<unknown>, because?: string): Promise<Result<unknown>> => {',
+  "    const outcome: AuditOutcome = held.ok ? 'ok' : REFUSAL[held.code].outcome",
+  '    const detail = because === undefined ? {} : { because }',
+  '',
+  '    const reserved = hold === null ? null : operation.estimate',
+  '    let consumed: number | null = null',
+  '',
+  '    if (hold !== null) {',
+  '      const settling = held.ok ? hold.commit(operation.estimate) : hold.release()',
+  '      consumed = held.ok ? operation.estimate : 0',
+  '      hold = null',
+  "      await settling.catch(sank('quota'))",
+  '    }',
+  '',
+  "    seams.log.write(held.ok ? 'info' : 'warn', id, actor, {",
+  '      outcome,',
+  '      ...detail,',
+  "      access: { roles: actor.roles, entitlements: actor.entitlements, granted: granted ?? 'not reached' },",
+  '      quota: { meter: id, reserved, consumed },',
+  '      gates,',
+  '    })',
+  '    if (held.ok) span?.ok()',
+  '    else span?.error(outcome)',
+  '',
+  '    await seams.audit',
+  "      .append(actor, { action: id, outcome, subject: { type: 'operation', id }, ...detail })",
+  "      .catch(sank('audit'))",
+  '',
+  '    if (!held.ok) {',
+  '      const identity: FailureIdentity =',
+  '        held.errorCode === undefined || held.errorClass === undefined',
+  '          ? DEFS[held.code]',
+  '          : { code: held.errorCode, class: held.errorClass }',
+  '',
+  '      await seams.errors',
+  '        .record(actor, { code: identity.code, class: identity.class, action: id, ...detail })',
+  "        .catch(sank('errors'))",
+  '    }',
+  '',
+  '    return held',
+  '  }',
+  '',
+  '  const refused = (code: ResultCode, because?: string): Promise<Result<unknown>> =>',
+  '    settled(fail(code, REFUSAL[code].said, because), because)',
+  '',
+  '  const recorded = (began: number, ok: boolean, at: string | undefined, because?: string): void => {',
+  '    const took = seams.clock.now() - began',
+  '    const sections = {',
+  '      node: { at: at ?? null },',
+  '      audit: { actor, when: began },',
+  '      observability: { ms: took, ok, ...(because === undefined ? {} : { because }) },',
+  '    }',
+  '',
+  "    seams.log.write(ok ? 'info' : 'warn', id, actor, sections)",
+  '    seams.telemetry?.record?.({',
+  '      key: id,',
+  '      traceId: run,',
+  '      spanId: run,',
+  '      durationMs: took,',
+  '      ok,',
+  '      attrs: sections,',
+  '      actor,',
+  '      ...(at === undefined ? {} : { nodeId: at }),',
+  '      workflowId: id,',
+  '      ...(because === undefined ? {} : { error: because }),',
+  '    })',
+  '  }',
+  '',
+  '  try {',
+  "    if (who === undefined) return await refused('denied', 'identity_invalid')",
+  '',
+  "    if (seams.rateLimiter !== undefined && !(await seams.rateLimiter.check(actor, id))) return await refused('rate_limited')",
+  '',
+  '    const replayed = seams.idempotency === undefined ? null : await seams.idempotency.check(actor.replay, id)',
+  "    if (replayed !== null && replayed !== undefined) return await settled(ok(replayed), 'replayed')",
+  '',
+  '    const parsed = operation.input.safeParse(rawInput)',
+  '    if (!parsed.success) {',
+  "      return await refused('invalid', parsed.error.issues.map((one) => one.message).join('; '))",
+  '    }',
+  '',
+  '    if (seams.quotas) {',
+  '      const reserved = await seams.quotas.reserve(actor, id, operation.estimate)',
+  "      if (!reserved.ok) return await refused('quota_exceeded', reserved.behavior ?? 'block')",
+  '      hold = reserved',
+  '    }',
+  '',
+  '    if (seams.permits === undefined) {',
+  "      return await refused('denied', 'no permits check is wired, so nothing can permit this operation')",
+  '    }',
+  '',
+  '    const ruled = await seams.permits.check(actor, id, operation.resource(parsed.data))',
+  "    if (!ruled.allow) return await refused('denied', ruled.because)",
+  '    granted = ruled.because',
+  '',
+  '    const hands = given(operation as Operation<unknown, string>, actor, seams)',
+  "    if (typeof hands === 'string') return await refused('error', hands)",
+  '',
+  '    const held: { readonly input: I } & Record<string, unknown> = { input: parsed.data }',
+  '    const began = seams.clock.now()',
+  '    let value: unknown',
+  '    try {',
+  '      value = await operation.run(hands as Handed<R>, held)',
+  '    } catch (thrown) {',
+  '      recorded(began, stopped(thrown) !== undefined, marked(thrown), thrown instanceof Error ? thrown.message : String(thrown))',
+  '      throw thrown',
+  '    }',
+  '    recorded(began, true, undefined)',
+  '',
+  "    if (seams.idempotency !== undefined) await seams.idempotency.store(actor.replay, id, value).catch(sank('idempotency'))",
+  '',
+  '    return await settled(ok(value))',
+  '  } catch (thrown) {',
+  '    const early = stopped(thrown)',
+  '    if (early !== undefined) {',
+  "      if (seams.idempotency !== undefined) await seams.idempotency.store(actor.replay, id, early.value).catch(sank('idempotency'))",
+  "      return await settled(ok(early.value), 'stopped')",
+  '    }',
+  '',
+  '    const message = thrown instanceof Error ? thrown.message : String(thrown)',
+  '',
+  "    if (named(thrown, 'VersionConflictError')) {",
+  "      return await settled(fail('invalid', message, 'version_conflict', CONFLICT), 'version_conflict')",
+  '    }',
+  '',
+  "    const code: ResultCode = named(thrown, 'ValidationError') ? 'invalid' : 'error'",
+  '    const because = platform(thrown) ?? message',
+  '    return await settled(fail(code, message, because), because)',
+  '  } finally {',
+  '    span?.end()',
+  '  }',
+  '}',
+  '',
+].join('\n')

package/dist/operations/error-results.ts

@@ -0,0 +1,31 @@
+import { PlatformError, catalog, type ErrorDef } from './errors/catalog.ts'
+import { AuthDenied, FeatureNotInPlan, InternalInvalidArgument, InternalUnexpected, QuotaExceeded, RateLimitExceeded } from './errors/errors.ts'
+
+import type { Result, ResultCode } from './result.ts'
+
+const RESULT_ERROR_DEFS: Readonly<Record<ResultCode, ErrorDef>> = {
+  invalid: InternalInvalidArgument.def,
+  denied: AuthDenied.def,
+  rate_limited: RateLimitExceeded.def,
+  quota_exceeded: QuotaExceeded.def,
+  feature_denied: FeatureNotInPlan.def,
+  error: InternalUnexpected.def,
+}
+
+export function errorDefForResult(code: ResultCode): ErrorDef {
+  return RESULT_ERROR_DEFS[code]
+}
+
+export function platformErrorForResult(result: Result<unknown>, run: string): PlatformError {
+  if (result.ok) throw new TypeError('cannot render a successful Result as a problem')
+
+  const def = result.errorCode === undefined ? errorDefForResult(result.code) : catalog.get(result.errorCode)
+  const resolved = def ?? InternalUnexpected.def
+  const detail = result.errorCode === undefined && resolved.code === InternalUnexpected.def.code ? undefined : result.error
+
+  return new PlatformError(resolved, {
+    ...(detail === undefined ? {} : { detail }),
+    ...(result.because === undefined ? {} : { because: result.because }),
+    traceId: run,
+  })
+}

package/dist/operations/errors/catalog.ts

@@ -0,0 +1,168 @@
+
+
+import { classDef, type ErrorClass } from './classes.ts'
+
+export const NAMESPACES = [
+  'auth',
+  'quota',
+  'rate_limit',
+  'feature',
+  'db',
+  'workflow',
+  'queue',
+  'ai',
+  'search',
+  'comms',
+  'config',
+  'net',
+  'internal',
+] as const
+
+export type Namespace = (typeof NAMESPACES)[number]
+
+export type ErrorCode = `${Namespace}.${string}`
+
+export interface ErrorDef<C extends ErrorCode = ErrorCode> {
+  readonly code: C
+  readonly class: ErrorClass
+  readonly status: number
+
+  readonly titleKey: string
+  readonly retryable: boolean
+}
+
+export interface DefineErrorInput<C extends ErrorCode = ErrorCode> {
+  readonly code: C
+  readonly class: ErrorClass
+
+  readonly status?: number
+
+  readonly retryable?: boolean
+
+  readonly titleKey?: string
+}
+
+export interface PlatformErrorInit {
+
+  readonly detail?: string
+
+  readonly instance?: string
+
+  readonly because?: string
+  readonly traceId?: string
+
+  readonly retryAfter?: number
+  readonly cause?: unknown
+
+  readonly extensions?: Readonly<Record<string, unknown>>
+}
+
+export class PlatformError<C extends ErrorCode = ErrorCode> extends Error {
+  readonly def: ErrorDef<C>
+  readonly detail?: string
+  readonly instance?: string
+  readonly because?: string
+  readonly traceId?: string
+  readonly retryAfter?: number
+  readonly extensions: Readonly<Record<string, unknown>>
+
+  constructor(def: ErrorDef<C>, init: PlatformErrorInit = {}) {
+
+    super(def.code, init.cause === undefined ? undefined : { cause: init.cause })
+    this.name = 'PlatformError'
+    this.def = def
+    this.detail = init.detail
+    this.instance = init.instance
+    this.because = init.because
+    this.traceId = init.traceId
+    this.retryAfter = init.retryAfter
+    this.extensions = init.extensions ?? {}
+  }
+
+  get code(): C {
+    return this.def.code
+  }
+
+  get status(): number {
+    return this.def.status
+  }
+
+  get retryable(): boolean {
+    return this.def.retryable
+  }
+}
+
+export function isPlatformError(value: unknown): value is PlatformError {
+  return value instanceof PlatformError
+}
+
+export type ErrorFactory<C extends ErrorCode = ErrorCode> = ((
+  init?: PlatformErrorInit,
+) => PlatformError<C>) & {
+  readonly def: ErrorDef<C>
+
+  readonly is: (value: unknown) => value is PlatformError<C>
+}
+
+export class DuplicateErrorCodeError extends Error {
+  constructor(code: string) {
+    super(`duplicate error code: ${code}`)
+    this.name = 'DuplicateErrorCodeError'
+  }
+}
+
+export class ErrorCatalog {
+  readonly #byCode = new Map<ErrorCode, ErrorDef>()
+
+  define<const C extends ErrorCode>(input: DefineErrorInput<C>): ErrorFactory<C> {
+    if (this.#byCode.has(input.code)) {
+
+      throw new DuplicateErrorCodeError(input.code)
+    }
+
+    const cls = classDef(input.class)
+    const def: ErrorDef<C> = {
+      code: input.code,
+      class: input.class,
+      status: input.status ?? cls.status,
+      retryable: input.retryable ?? cls.retryable,
+      titleKey: input.titleKey ?? `errors.${input.code}.title`,
+    }
+    this.#byCode.set(def.code, def)
+
+    const factory = ((init?: PlatformErrorInit) => new PlatformError(def, init)) as {
+      (init?: PlatformErrorInit): PlatformError<C>
+      def: ErrorDef<C>
+      is: (value: unknown) => value is PlatformError<C>
+    }
+    factory.def = def
+    factory.is = (value: unknown): value is PlatformError<C> =>
+      isPlatformError(value) && value.def.code === def.code
+
+    return factory as ErrorFactory<C>
+  }
+
+  get(code: string): ErrorDef | undefined {
+    return this.#byCode.get(code as ErrorCode)
+  }
+
+  has(code: string): boolean {
+    return this.#byCode.has(code as ErrorCode)
+  }
+
+  all(): readonly ErrorDef[] {
+    return [...this.#byCode.values()].sort((a, b) => a.code.localeCompare(b.code))
+  }
+
+  get size(): number {
+    return this.#byCode.size
+  }
+}
+
+export const catalog = new ErrorCatalog()
+
+export function defineError<const C extends ErrorCode>(
+  input: DefineErrorInput<C>,
+): ErrorFactory<C> {
+  return catalog.define(input)
+}

package/dist/operations/errors/classes.ts

@@ -0,0 +1,51 @@
+
+
+export interface ErrorClassDef {
+
+  readonly status: number
+
+  readonly retryable: boolean
+}
+
+export const ERROR_CLASSES = {
+
+  OK: { status: 200, retryable: false },
+
+  CANCELLED: { status: 499, retryable: false },
+
+  UNKNOWN: { status: 500, retryable: false },
+
+  INVALID_ARGUMENT: { status: 400, retryable: false },
+
+  DEADLINE_EXCEEDED: { status: 504, retryable: true },
+
+  NOT_FOUND: { status: 404, retryable: false },
+
+  ALREADY_EXISTS: { status: 409, retryable: false },
+
+  PERMISSION_DENIED: { status: 403, retryable: false },
+
+  RESOURCE_EXHAUSTED: { status: 429, retryable: true },
+
+  FAILED_PRECONDITION: { status: 400, retryable: false },
+
+  ABORTED: { status: 409, retryable: true },
+
+  OUT_OF_RANGE: { status: 400, retryable: false },
+
+  UNIMPLEMENTED: { status: 501, retryable: false },
+
+  INTERNAL: { status: 500, retryable: false },
+
+  UNAVAILABLE: { status: 503, retryable: true },
+
+  UNAUTHENTICATED: { status: 401, retryable: false },
+} as const satisfies Record<string, ErrorClassDef>
+
+export type ErrorClass = keyof typeof ERROR_CLASSES
+
+export const ERROR_CLASS_NAMES = Object.keys(ERROR_CLASSES) as readonly ErrorClass[]
+
+export function classDef(cls: ErrorClass): ErrorClassDef {
+  return ERROR_CLASSES[cls]
+}