@softize/opus 8.6.6

package/src/core/errors.ts

@@ -0,0 +1,181 @@
+/**
+ * tbdlib — Error factory
+ *
+ * `error()` é a maneira canônica de emitir `ActionError` de dentro de um handler.
+ * Aplica defaults sensatos baseados na categoria (severity, retriable) e
+ * preserva stack trace via `Error`. Ver §3 do protocolo.
+ *
+ * Uso:
+ *   throw error({
+ *     code: 'deal.archive.notFound',
+ *     category: 'not_found',
+ *     message: `Deal ${id} not found`,
+ *   })
+ *
+ * Erros não criados via `error()` (ex: `throw new Error(...)`, exceções de driver)
+ * são normalizados pelo runtime em `{ category: 'internal', code: 'internal.unhandled' }`.
+ */
+
+import type {
+  ActionError,
+  ErrorCategory,
+  Severity,
+  ValidationIssue,
+} from './types.ts'
+
+/** Brand interno pra distinguir ActionError construído via `error()` de Error genérico. */
+const ACTION_ERROR_BRAND = Symbol('tbdlib.ActionError')
+
+/**
+ * Defaults de severity por categoria.
+ * Ver tabela em §3 do protocolo.
+ */
+const DEFAULT_SEVERITY_BY_CATEGORY: Record<ErrorCategory, Severity> = {
+  validation: 'warning',
+  authentication: 'warning',
+  authorization: 'warning',
+  not_found: 'warning',
+  conflict: 'warning',
+  rate_limit: 'warning',
+  dependency: 'error',
+  internal: 'error',
+}
+
+/**
+ * Defaults de retriable por categoria.
+ */
+const DEFAULT_RETRIABLE_BY_CATEGORY: Record<ErrorCategory, boolean> = {
+  validation: false,
+  authentication: false,
+  authorization: false,
+  not_found: false,
+  conflict: false,
+  rate_limit: true,
+  dependency: true,
+  internal: false,
+}
+
+/**
+ * Input do factory `error()`. Tudo opcional exceto `code` e `category`;
+ * defaults são aplicados em runtime baseado na categoria.
+ */
+export interface ErrorInput {
+  code: string
+  category: ErrorCategory
+  message?: string
+  severity?: Severity
+  retriable?: boolean
+
+  i18nKey?: string
+  i18nParams?: Record<string, unknown>
+
+  field?: string
+  issues?: ValidationIssue[]
+
+  cause?: unknown
+  meta?: Record<string, unknown>
+}
+
+/**
+ * Implementação concreta. Não exportada — consumers usam `error()` e checam via `isActionError()`.
+ * Estende `Error` para preservar stack trace e funcionar com try/catch idiomático.
+ */
+class ActionErrorImpl extends Error implements ActionError {
+  readonly [ACTION_ERROR_BRAND] = true as const
+
+  readonly code: string
+  readonly category: ErrorCategory
+  readonly severity: Severity
+  readonly retriable: boolean
+
+  readonly i18nKey?: string
+  readonly i18nParams?: Record<string, unknown>
+  readonly field?: string
+  readonly issues?: ValidationIssue[]
+  override readonly cause?: unknown
+  readonly meta?: Record<string, unknown>
+
+  constructor(input: ErrorInput) {
+    const message = input.message ?? defaultMessage(input.code, input.category)
+    super(message)
+
+    this.name = 'ActionError'
+    this.code = input.code
+    this.category = input.category
+    this.severity = input.severity ?? DEFAULT_SEVERITY_BY_CATEGORY[input.category]
+    this.retriable = input.retriable ?? DEFAULT_RETRIABLE_BY_CATEGORY[input.category]
+
+    if (input.i18nKey !== undefined) this.i18nKey = input.i18nKey
+    if (input.i18nParams !== undefined) this.i18nParams = input.i18nParams
+    if (input.field !== undefined) this.field = input.field
+    if (input.issues !== undefined) this.issues = input.issues
+    if (input.cause !== undefined) this.cause = input.cause
+    if (input.meta !== undefined) this.meta = input.meta
+
+    // Preserva stack trace de quem chamou error(), não desta constructor.
+    // captureStackTrace é V8-only (Node/Chrome); ignora em outros runtimes.
+    const ctor = Error as ErrorConstructor & {
+      captureStackTrace?: (target: object, ctor?: Function) => void
+    }
+    if (typeof ctor.captureStackTrace === 'function') {
+      ctor.captureStackTrace(this, error)
+    }
+  }
+}
+
+/**
+ * Constrói um `ActionError` a partir de input parcial.
+ * Severity e retriable são derivados da categoria se não passados.
+ *
+ * O resultado é uma instância de `Error` (preserva stack, funciona com try/catch)
+ * que também satisfaz a interface `ActionError`.
+ */
+export function error(input: ErrorInput): ActionError {
+  return new ActionErrorImpl(input)
+}
+
+/**
+ * Type guard pra checar se um valor foi construído via `error()`.
+ * Runtime usa pra distinguir entre ActionError emitido pelo handler vs
+ * exceção genérica que precisa ser normalizada.
+ */
+export function isActionError(value: unknown): value is ActionError {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    ACTION_ERROR_BRAND in value &&
+    (value as { [ACTION_ERROR_BRAND]: unknown })[ACTION_ERROR_BRAND] === true
+  )
+}
+
+/**
+ * Normaliza uma exceção qualquer em ActionError. Usado pelo runtime quando
+ * handler lança algo que não foi criado via `error()`.
+ */
+export function normalizeError(thrown: unknown): ActionError {
+  if (isActionError(thrown)) return thrown
+
+  if (thrown instanceof Error) {
+    return error({
+      code: 'internal.unhandled',
+      category: 'internal',
+      message: thrown.message,
+      cause: thrown.message, // só mensagem; stack não vaza pra wire
+    })
+  }
+
+  return error({
+    code: 'internal.unhandled',
+    category: 'internal',
+    message: typeof thrown === 'string' ? thrown : 'Unhandled error',
+    cause: thrown,
+  })
+}
+
+// =============================================================================
+// Internos
+// =============================================================================
+
+function defaultMessage(code: string, category: ErrorCategory): string {
+  return `[${category}] ${code}`
+}

package/src/core/index.ts

@@ -0,0 +1,174 @@
+/**
+ * @softize/opus/core — public entry
+ *
+ * Re-exports da superfície pública. Source of truth: `/docs/protocol.md`.
+ */
+
+// — Tipos —————————————————————————————————————————————————————————————————————
+export type {
+  // primitivos / shared
+  I18nRef,
+  Unsubscribe,
+  Logger,
+  ContextBase,
+  Schema,
+  InferInput,
+  InferOutput,
+  // erro
+  ActionError,
+  ErrorCategory,
+  Severity,
+  ValidationIssue,
+  ErrorSpec,
+  // result
+  ResultMeta,
+  ActionResult,
+  BackgroundResult,
+  Paginated,
+  // contexto
+  User,
+  CanFn,
+  EmitFn,
+  ActionContext,
+  ReactionContext,
+  Provenance,
+  // audit
+  AuditRecord,
+  AuditConfig,
+  // eventos
+  DomainEvent,
+  // jobs / background
+  JobStatus,
+  JobHandle,
+  JobSpec,
+  BackoffSpec,
+  BackgroundConfig,
+  ProgressReporter,
+  // tipos lógicos
+  LogicalTypeMeta,
+  // specs (action)
+  ConfirmSpec,
+  RateLimitSpec,
+  AIConfig,
+  Example,
+  ActionMessages,
+  OptionsSpec,
+  FieldSpec,
+  FilterOp,
+  FilterSpec,
+  ListColumnSpec,
+  SortSpec,
+  PeriodSpec,
+  ExpandSpec,
+  // action union + variants
+  ActionKind,
+  ActionBase,
+  SimpleAction,
+  FormAction,
+  ListAction,
+  ViewAction,
+  ActionDef,
+  AuthorizeFn,
+  AuthorizeSpec,
+  HandlerFn,
+  LoaderFn,
+  LoaderResolver,
+  LoadSpec,
+  LoadsSpec,
+  LoadersSpec,
+  // reaction
+  ReactionDef,
+  ReactionHandlerFn,
+  // schedule
+  ScheduleDef,
+  // adapters
+  AdapterKind,
+  Adapter,
+  RuntimeRef,
+  HealthStatus,
+  ServerAdapter,
+  DataAdapter,
+  AuthAdapter,
+  AuditSink,
+  LoggerAdapter,
+  QueueAdapter,
+  EventBusAdapter,
+  SchedulerAdapter,
+  ClientAdapter,
+  StorageAdapter,
+  StoragePutOptions,
+  StorageObject,
+  AiAdapter,
+  AiCompleteOptions,
+  AiTool,
+  AiMessage,
+  AiRunOptions,
+  AiRunResult,
+  BoundAi,
+  BoundAiRunOptions,
+  ChatEvent,
+  AskOption,
+  AskQuestion,
+  AskAnswer,
+  EndpointSpec,
+  LogsEndpointSpec,
+  AuditEndpointSpec,
+  LogQuery,
+  LogEntry,
+  AuditQuery,
+  // runtime config
+  RuntimeConfig,
+} from './types.ts'
+
+// — Erro ——————————————————————————————————————————————————————————————————————
+export { error, isActionError, normalizeError } from './errors.ts'
+export type { ErrorInput } from './errors.ts'
+
+// — Logical types ——————————————————————————————————————————————————————————————
+// As factories `t.*` moram em `@softize/opus/schema`; o attach/get da meta é
+// isomórfico e mora AQUI (a UI lê a meta do contrato — fronteira ui→core).
+// `@softize/opus/schema` re-exporta os dois pra manter a API de sempre.
+export { attachLogicalType, getLogicalType } from './logical-type.ts'
+
+// — Action ————————————————————————————————————————————————————————————————————
+export {
+  defineAction,
+  isSimpleAction,
+  isFormAction,
+  isListAction,
+  isViewAction,
+  isBackgroundAction,
+} from './actions.ts'
+
+// — Contract / bind (split contrato↔handler) ——————————————————————————————————
+export { defineContract, bindAction } from './contracts.ts'
+export type {
+  ActionContract,
+  ActionBinding,
+  SimpleContract,
+  FormContract,
+  ListContract,
+  ViewContract,
+} from './contracts.ts'
+
+// — Reaction ——————————————————————————————————————————————————————————————————
+export { defineReaction, defineReactionContract, bindReaction, isReaction } from './reactions.ts'
+export type { ReactionContract, ReactionBinding } from './reactions.ts'
+
+// — Schedule ——————————————————————————————————————————————————————————————————
+export { defineSchedule, isSchedule } from './schedules.ts'
+
+// — Domain ————————————————————————————————————————————————————————————————————
+export { defineDomain, flattenDomain, isDomainConfig } from './domain.ts'
+export type { DomainConfig, FlattenedDomain } from './domain.ts'
+
+// — Audit —————————————————————————————————————————————————————————————————————
+export { AuditEmitter } from './audit.ts'
+
+// — Runtime ———————————————————————————————————————————————————————————————————
+export { Runtime, createRuntime } from './runtime.ts'
+export type {
+  RuntimeSetup,
+  RuntimeSetupConfig,
+  ResolvedRuntimeConfig,
+} from './runtime.ts'

package/src/core/logical-type.ts

@@ -0,0 +1,31 @@
+/**
+ * Metadata machinery de logical types — attach/get driver-agnostic.
+ *
+ * Mora no CORE (não em `schema/`) porque o protocolo é isomórfico: a UI resolve
+ * labels de dict lendo a meta que viaja no schema do contrato, e a fronteira SPA
+ * (gate de arquitetura) só deixa a UI tocar ui/lib/core. O `@softize/opus/schema`
+ * re-exporta — a API pública não muda; as factories `t.*` seguem no driver.
+ */
+
+import type { LogicalTypeMeta } from './types.ts'
+
+const META = new WeakMap<object, LogicalTypeMeta>()
+
+/**
+ * Anexa metadata logical type a qualquer schema (objeto). Drivers usam
+ * internamente; consumers usam pra registrar tipos lógicos customizados.
+ */
+export function attachLogicalType<S extends object>(
+  schema: S,
+  meta: LogicalTypeMeta,
+): S {
+  META.set(schema, meta)
+  return schema
+}
+
+/**
+ * Lê a metadata logical type anexada. Retorna `undefined` se ausente.
+ */
+export function getLogicalType(schema: object): LogicalTypeMeta | undefined {
+  return META.get(schema)
+}

package/src/core/reactions.ts

@@ -0,0 +1,81 @@
+/**
+ * tbdlib — `defineReaction` factory + type guards
+ *
+ * `defineReaction` é identity function tipada que aceita uma `ReactionDef`
+ * e preserva o tipo do evento pra inferência. Runtime registra no
+ * `EventBusAdapter` durante `start()`.
+ *
+ * Também expõe o SPLIT `defineReactionContract`→`bindReaction` (declaração isomorfa,
+ * autorável no design, × handler do handoff), espelhando `defineContract`/`bindAction`.
+ *
+ * Ver §12 do protocolo.
+ */
+
+import type { BackoffSpec, DomainEvent, ReactionDef, ReactionHandlerFn } from './types.ts'
+
+/**
+ * Constrói uma `ReactionDef`. Identity function pra inferência de tipo.
+ */
+export function defineReaction<Event = unknown>(
+  spec: ReactionDef<Event>,
+): ReactionDef<Event> {
+  return spec
+}
+
+// =============================================================================
+// Split contrato/handler (defineReactionContract → bindReaction)
+// =============================================================================
+
+/** Campos server-only que o `bindReaction` fornece — o resto é a DECLARAÇÃO (isomorfa). */
+type ReactionBindingKeys = 'handler' | 'retry' | 'timeout' | 'dedup' | 'concurrency'
+
+/**
+ * A DECLARAÇÃO de uma reação, autorável na sessão de design (isomorfa, SEM efeito): qual
+ * evento (`on`), o que significa (`description`), quem pode (`authorize`). O `handler` e a
+ * config de entrega ficam de fora — são do handoff (`bindReaction`). Espelha `ActionContract`.
+ */
+export type ReactionContract<Event = unknown> = Omit<ReactionDef<Event>, ReactionBindingKeys>
+
+/** Parte server-only amarrada por `bindReaction`: o handler + a config de entrega. */
+export interface ReactionBinding<Event = unknown> {
+  handler: ReactionHandlerFn<Event>
+  retry?: { attempts: number; backoff?: BackoffSpec }
+  timeout?: number
+  dedup?: (event: DomainEvent<Event>) => string
+  concurrency?: number
+}
+
+/**
+ * Constrói a DECLARAÇÃO de uma reação (sem o efeito) — o que a sessão de design autora.
+ * Identity function, pra preservar a inferência do tipo do evento.
+ */
+export function defineReactionContract<Event = unknown>(
+  contract: ReactionContract<Event>,
+): ReactionContract<Event> {
+  return contract
+}
+
+/**
+ * Amarra o trabalho server-only (`handler` + entrega) à declaração, produzindo uma
+ * `ReactionDef` normal — o runtime nem sabe que houve split (igual `bindAction`). É o handoff.
+ */
+export function bindReaction<Event = unknown>(
+  contract: ReactionContract<Event>,
+  binding: ReactionBinding<Event>,
+): ReactionDef<Event> {
+  return { ...contract, ...binding }
+}
+
+/**
+ * Type guard utilitário pra distinguir reactions de actions quando
+ * registradas misturadas em `runtime.register([...])`.
+ */
+export function isReaction(value: unknown): value is ReactionDef {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as { on?: unknown; handler?: unknown; name?: unknown }
+  return (
+    typeof candidate.name === 'string' &&
+    typeof candidate.handler === 'function' &&
+    (typeof candidate.on === 'string' || Array.isArray(candidate.on))
+  )
+}