@softize/opus 8.6.6

package/src/core/audit.ts

@@ -0,0 +1,239 @@
+/**
+ * tbdlib — AuditEmitter
+ *
+ * Classe que coordena a emissão de `AuditRecord` pros `AuditSink` registrados.
+ * Aplica config da action (redact, fields, severity, sink filter) antes de
+ * dispatchar; trata falhas conforme `auditMode` ('lenient' | 'strict').
+ *
+ * Ver §5 do protocolo.
+ */
+
+import { error } from './errors.ts'
+import type {
+  AuditConfig,
+  AuditRecord,
+  AuditSink,
+  Logger,
+} from './types.ts'
+
+interface AuditEmitterOptions {
+  mode: 'lenient' | 'strict'
+  log: Logger
+}
+
+export class AuditEmitter {
+  private readonly sinks: AuditSink[] = []
+  private readonly mode: 'lenient' | 'strict'
+  private readonly log: Logger
+
+  constructor(options: AuditEmitterOptions) {
+    this.mode = options.mode
+    this.log = options.log
+  }
+
+  /**
+   * Registra um sink. Sinks são emitidos em paralelo; ordem de registro
+   * não importa.
+   */
+  register(sink: AuditSink): void {
+    this.sinks.push(sink)
+  }
+
+  /**
+   * Emite um record pros sinks apropriados.
+   * - `config === false` → no-op (audit desabilitado pra esta action).
+   * - `config === true | undefined` → record bruto, todos os sinks.
+   * - `config: AuditConfig` → aplica redact/fields/severity/sink filter.
+   *
+   * Falhas seguem o `auditMode`:
+   * - `lenient` (default): warn no logger, processo segue.
+   * - `strict`: lança ActionError de categoria 'internal', aborta o flow.
+   */
+  async emit(
+    record: AuditRecord,
+    config?: boolean | AuditConfig,
+  ): Promise<void> {
+    if (config === false) return
+
+    const processed = this.applyConfig(record, config)
+    const targetSinks = this.filterSinks(config)
+
+    if (targetSinks.length === 0) return
+
+    const results = await Promise.allSettled(
+      targetSinks.map((sink) => Promise.resolve(sink.emit(processed))),
+    )
+
+    const failures = results.filter(
+      (r): r is PromiseRejectedResult => r.status === 'rejected',
+    )
+
+    if (failures.length === 0) return
+
+    if (this.mode === 'strict') {
+      throw error({
+        code: 'audit.sink.failed',
+        category: 'internal',
+        message: `${failures.length}/${targetSinks.length} audit sinks failed`,
+        meta: { failures: failures.map((f) => String(f.reason)) },
+      })
+    }
+
+    this.log.warn('audit sinks failed (lenient mode)', {
+      failures: failures.length,
+      total: targetSinks.length,
+      reasons: failures.map((f) => String(f.reason)),
+    })
+  }
+
+  /**
+   * Health check: ok se todos os sinks declararam ok (ou nenhum implementou
+   * healthCheck). Detalhes do estado de cada sink no `details`.
+   */
+  async healthCheck(): Promise<{ ok: boolean; details: Record<string, unknown> }> {
+    const details: Record<string, unknown> = {}
+    let ok = true
+
+    for (const sink of this.sinks) {
+      if (sink.healthCheck === undefined) {
+        details[sink.name] = { ok: true, skipped: true }
+        continue
+      }
+      try {
+        const result = await sink.healthCheck()
+        details[sink.name] = result
+        if (!result.ok) ok = false
+      } catch (err) {
+        details[sink.name] = { ok: false, error: String(err) }
+        ok = false
+      }
+    }
+
+    return { ok, details }
+  }
+
+  // ===========================================================================
+  // Internos
+  // ===========================================================================
+
+  private applyConfig(
+    record: AuditRecord,
+    config: boolean | AuditConfig | undefined,
+  ): AuditRecord {
+    if (config === undefined || config === true) return record
+    /* v8 ignore next 2 — defensivo; emit() já short-circuita config=false */
+    if (config === false) return record
+
+    let input = record.input
+    if (config.fields !== undefined) input = pickFields(input, config.fields)
+    if (config.redact !== undefined) input = redactPaths(input, config.redact)
+
+    let output: unknown = record.output
+    let suppressOutput = false
+    if (config.output === false) {
+      suppressOutput = true
+    } else if (typeof config.output === 'object' && record.output !== undefined) {
+      if (config.output.fields !== undefined)
+        output = pickFields(record.output, config.output.fields)
+      if (config.output.redact !== undefined)
+        output = redactPaths(output, config.output.redact)
+    }
+
+    const { output: _stripped, ...rest } = record
+    const next: AuditRecord = { ...rest, input }
+    if (!suppressOutput && output !== undefined) next.output = output
+    if (config.severity !== undefined) next.severity = config.severity
+
+    return next
+  }
+
+  private filterSinks(config: boolean | AuditConfig | undefined): AuditSink[] {
+    if (config === undefined || config === true || config === false) {
+      return this.sinks
+    }
+    if (config.sink === undefined) return this.sinks
+    return this.sinks.filter((sink) => sink.name === config.sink)
+  }
+}
+
+// =============================================================================
+// Path helpers
+// =============================================================================
+
+/**
+ * Retorna um novo objeto contendo apenas as chaves listadas em `fields`.
+ * Suporta dot-paths simples ("payment.amount"); arrays não são percorridos.
+ */
+function pickFields(value: unknown, fields: string[]): unknown {
+  if (!isPlainObject(value)) return value
+  const result: Record<string, unknown> = {}
+  for (const field of fields) {
+    const found = getAtPath(value, field)
+    if (found.exists) {
+      setAtPath(result, field, found.value)
+    }
+  }
+  return result
+}
+
+/**
+ * Substitui valores nos paths informados por '[REDACTED]'.
+ * Não mutaiona o original.
+ */
+function redactPaths(value: unknown, paths: string[]): unknown {
+  if (!isPlainObject(value)) return value
+  const cloned = deepClone(value)
+  for (const path of paths) {
+    const found = getAtPath(cloned, path)
+    if (found.exists) setAtPath(cloned, path, '[REDACTED]')
+  }
+  return cloned
+}
+
+function getAtPath(
+  obj: unknown,
+  path: string,
+): { exists: boolean; value: unknown } {
+  const parts = path.split('.')
+  let cursor: unknown = obj
+  for (const part of parts) {
+    if (!isPlainObject(cursor) || !(part in cursor)) {
+      return { exists: false, value: undefined }
+    }
+    cursor = (cursor as Record<string, unknown>)[part]
+  }
+  return { exists: true, value: cursor }
+}
+
+function setAtPath(obj: Record<string, unknown>, path: string, value: unknown): void {
+  const parts = path.split('.')
+  let cursor: Record<string, unknown> = obj
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    const part = parts[i] as string
+    const next = cursor[part]
+    if (!isPlainObject(next)) {
+      const fresh: Record<string, unknown> = {}
+      cursor[part] = fresh
+      cursor = fresh
+    } else {
+      cursor = next as Record<string, unknown>
+    }
+  }
+  cursor[parts[parts.length - 1] as string] = value
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  )
+}
+
+function deepClone<T>(value: T): T {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(value)
+  }
+  return JSON.parse(JSON.stringify(value)) as T
+}

package/src/core/contracts.ts

@@ -0,0 +1,137 @@
+/**
+ * @softize/opus/core — `defineContract` + `bindAction` (split contrato/handler).
+ *
+ * O `defineAction` junta o **contrato** (declarativo) com o **handler**
+ * (server-only) num objeto só — o que impede o frontend de importar a action
+ * sem arrastar db/segredos. `defineContract`/`bindAction` partem isso:
+ *
+ *   - **Contrato** (roda nos dois lados → `shared`): identidade, input/output,
+ *     fields/filters/projection, docs, e a regra `authorize` action-level.
+ *   - **Binding** (server-only → `api`): `handler`, `loads`, `background`,
+ *     `emits`, `idempotency`, e um `authorize` row-level que sobrescreve.
+ *
+ * O `bindAction(contract, binding)` produz um `ActionDef` normal — o runtime
+ * nem sabe que houve split. Ver §15 do protocolo / `docs/data-layer.md`.
+ */
+
+import type {
+  ActionContext,
+  ActionDef,
+  AuthorizeSpec,
+  BackgroundConfig,
+  FormAction,
+  InferOutput,
+  LoadsSpec,
+  Paginated,
+  ProgressReporter,
+  ListAction,
+  SimpleAction,
+  ViewAction,
+} from './types.ts'
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// =============================================================================
+// Contrato = ActionDef sem os campos de execução
+// =============================================================================
+
+/** Campos server-only que o `bindAction` fornece — o resto é contrato. */
+type BindingKeys = 'handler' | 'loads' | 'background' | 'emits' | 'idempotency'
+
+/**
+ * `ParsedIn` (o lado PARSEADO do schema de input — defaults aplicados) defaulta
+ * a `any` nos contratos, de propósito: quem anota contrato à mão é o CLIENTE
+ * (`FormContract<MeuInput, MeuOutput>` em hooks/props), que só conhece o fio —
+ * e `authorize`/`mockHandler` são contravariantes em `ParsedIn`, então um
+ * default estreito rejeitaria contrato real cujo schema tem `.default()`.
+ * Quem precisa do parseado com precisão (`bindAction`) o infere do schema.
+ */
+export type SimpleContract<In = unknown, Out = unknown, ParsedIn = any> = Omit<
+  SimpleAction<In, Out, ParsedIn>,
+  BindingKeys
+>
+export type FormContract<
+  In extends Record<string, unknown> = Record<string, unknown>,
+  Out = unknown,
+  ParsedIn = any,
+> = Omit<FormAction<In, Out, ParsedIn>, BindingKeys>
+export type ListContract<In = unknown, Out = unknown, ParsedIn = any> = Omit<
+  ListAction<In, Out, ParsedIn>,
+  BindingKeys
+>
+export type ViewContract<In = unknown, Out = unknown, ParsedIn = any> = Omit<
+  ViewAction<In, Out, ParsedIn>,
+  BindingKeys
+>
+
+export type ActionContract<In = any, Out = any, ParsedIn = any> =
+  | SimpleContract<In, Out, ParsedIn>
+  | FormContract<In & Record<string, unknown>, Out, ParsedIn>
+  | ListContract<In, Out, ParsedIn>
+  | ViewContract<In, Out, ParsedIn>
+
+/**
+ * Parte server-only amarrada por `bindAction`. `authorize` aqui (row-level)
+ * sobrescreve a do contrato. O retorno do handler aceita `Paginated<Out>` pra
+ * cobrir o kind `search` (cujo `output` descreve o item, não o envelope).
+ *
+ * Tudo aqui roda PÓS-validação — o runtime valida o input antes de executar —
+ * então o binding é tipado por `ParsedIn` (o output do schema de input,
+ * defaults aplicados), não pelo lado do fio.
+ */
+export interface ActionBinding<ParsedIn, Out> {
+  handler: (
+    ctx: ActionContext,
+    input: ParsedIn,
+    loaded?: Record<string, unknown>,
+    progress?: ProgressReporter,
+  ) => Out | Paginated<Out> | Promise<Out | Paginated<Out>>
+  loads?: LoadsSpec<ParsedIn>
+  authorize?: AuthorizeSpec<ParsedIn>
+  background?: BackgroundConfig
+  emits?: string[]
+  idempotency?: (input: ParsedIn) => string
+}
+
+// =============================================================================
+// defineContract (overloads por kind, igual defineAction)
+// =============================================================================
+
+export function defineContract<In, Out, ParsedIn = In>(
+  contract: SimpleContract<In, Out, ParsedIn>,
+): SimpleContract<In, Out, ParsedIn>
+export function defineContract<In extends Record<string, unknown>, Out, ParsedIn = In>(
+  contract: FormContract<In, Out, ParsedIn>,
+): FormContract<In, Out, ParsedIn>
+export function defineContract<In, Out, ParsedIn = In>(
+  contract: ListContract<In, Out, ParsedIn>,
+): ListContract<In, Out, ParsedIn>
+export function defineContract<In, Out, ParsedIn = In>(
+  contract: ViewContract<In, Out, ParsedIn>,
+): ViewContract<In, Out, ParsedIn>
+export function defineContract(contract: any): any {
+  return contract
+}
+
+// =============================================================================
+// bindAction
+// =============================================================================
+
+/**
+ * Amarra o trabalho server-only a um contrato, produzindo um `ActionDef`.
+ * `binding.authorize` (row-level, com `loaded`) sobrescreve o `authorize`
+ * action-level do contrato.
+ */
+// O input do binding é o PARSEADO: extraído do lado de output do schema de
+// input do contrato (`InferOutput`), porque o runtime valida antes de executar.
+type ContractParsedIn<C extends ActionContract> = InferOutput<C['input']>
+type ContractOut<C> = C extends ActionContract<any, infer Out, any> ? Out : never
+
+export function bindAction<C extends ActionContract>(
+  contract: C,
+  // ParsedIn/Out são extraídos do contrato (C concreto), nunca do handler —
+  // senão o retorno `Paginated<Out>` do search contaminaria a inferência de `Out`.
+  binding: ActionBinding<ContractParsedIn<C>, ContractOut<C>>,
+): ActionDef {
+  return { ...contract, ...binding } as unknown as ActionDef
+}

package/src/core/domain.ts

@@ -0,0 +1,310 @@
+/**
+ * tbdlib — `defineDomain` factory + flatten helper.
+ *
+ * Domain agrupa as peças que pertencem a um mesmo recorte funcional
+ * (dicts, models, repository, service, actions, reactions, schedules,
+ * subdomains). É puramente declarativo: nenhum efeito colateral acontece
+ * em `defineDomain`. O runtime consome o objeto via `flattenDomain` quando
+ * recebe um `DomainConfig` em `register(...)`.
+ *
+ * Validações em runtime (em `defineDomain`):
+ *   - `name` é string não-vazia no formato `[a-z][a-zA-Z0-9_]*`.
+ *   - Actions têm nomes únicos dentro do domínio (incluindo subdomains).
+ *   - Subdomains têm nomes únicos entre siblings.
+ *
+ * Warnings (em `Runtime.register`, via `collectDomainWarnings`):
+ *   - Actions cujo `name` não casa com `<root>(\.<sub>)*\.<verb>` emitem
+ *     `console.warn`. Heurística que depende do path completo da raiz —
+ *     por isso fica pro register, não pro `defineDomain` (que pode rodar
+ *     standalone como subdomain).
+ *
+ * Ver §17 do protocolo (TBD em v2).
+ */
+
+import type { ActionContract } from './contracts.ts'
+import { error } from './errors.ts'
+import type { ActionDef, ReactionDef, ScheduleDef } from './types.ts'
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// =============================================================================
+// Tipos
+// =============================================================================
+
+/**
+ * Um registrável de action num domínio: BOUND (`ActionDef`, com handler) ou
+ * contrato PURO (`ActionContract`, sem handler). Um domínio de design — a
+ * fatia isomorfa (ADR 0004) — registra só contratos, e em modo design o
+ * `mockHandler` responde. Fora de design, contrato sem handler falha no
+ * `execute` (comportamento INTENCIONAL); o tipo só deixa de exigir o cast.
+ */
+export type DomainAction = ActionDef | ActionContract
+
+/**
+ * Especificação declarativa de um domínio. Todos os campos exceto `name`
+ * são opcionais — domínio mínimo é só um `name`.
+ */
+export interface DomainConfig {
+  /** Nome do domínio (ex: `tickets`, `shipments`). camelCase. */
+  name: string
+
+  /** Doc de negócio do domínio — o recorte que ele cobre. Flui pro manifest/lente. */
+  description?: string
+
+  /** Dicionários do domínio (ver `@softize/opus/schema`). Map de nome → instance. */
+  dicts?: Record<string, unknown>
+
+  /** Entidades do domínio (`defineEntity`). Map de nome → EntityConfig. É a fonte
+   *  estrutural+negócio que vai pro manifest. `models` é o nome legado (alias). */
+  entities?: Record<string, unknown>
+
+  /** @deprecated Use `entities`. Mantido por compat — o runtime/gen lê os dois. */
+  models?: Record<string, unknown>
+
+  /** Repository class do domínio. */
+  repository?: unknown
+
+  /** Service class do domínio. */
+  service?: unknown
+
+  /**
+   * Actions do domínio — cada item é `ActionDef` (bound) ou `ActionContract`
+   * (contrato puro, sem handler; ver `DomainAction`). Pode ser:
+   *   - `Record<string, DomainAction>` — map nome → action
+   *   - `DomainAction[]` — array
+   *   - `Record<string, DomainAction[]>` — barrel imports (`import * as actions`)
+   */
+  actions?: Record<string, DomainAction | DomainAction[]> | DomainAction[]
+
+  /** Reactions registradas no domínio. */
+  reactions?: Array<ReactionDef<any>>
+
+  /** Schedules registrados no domínio. */
+  schedules?: ScheduleDef[]
+
+  /** Subdomínios (recursivo). */
+  subdomains?: DomainConfig[]
+}
+
+/**
+ * Resultado de `flattenDomain` — arrays achatados prontos pra `Runtime.register`.
+ */
+export interface FlattenedDomain {
+  actions: ActionDef[]
+  reactions: Array<ReactionDef<any>>
+  schedules: ScheduleDef[]
+}
+
+// =============================================================================
+// defineDomain
+// =============================================================================
+
+const DOMAIN_NAME_RE = /^[a-z][a-zA-Z0-9_]*$/
+
+/**
+ * Constrói e valida um `DomainConfig`. Validação roda em runtime; em sucesso
+ * retorna o próprio config (identity, pra preservar inferência).
+ *
+ * Erros são `ActionError` com `category: 'internal'`.
+ *
+ * Warnings de nomenclatura (action que não casa com `<domain>(.sub)*.verb`)
+ * **não** são emitidos aqui — eles dependem do path completo da raiz e
+ * portanto saem em `Runtime.register([domain])` (ver `collectDomainWarnings`).
+ */
+export function defineDomain(config: DomainConfig): DomainConfig {
+  validateDomain(config, [])
+  return config
+}
+
+/**
+ * Walk no domínio emitindo warnings (via `console.warn`) pra actions cujo
+ * `name` não casa com o path completo `<root>(.sub)*.verb`. Chamado pelo
+ * `Runtime.register` quando recebe um `DomainConfig`.
+ */
+export function collectDomainWarnings(domain: DomainConfig): void {
+  walkForWarnings(domain, [])
+}
+
+/**
+ * Heurística simples pra detectar `DomainConfig` numa lista mista em
+ * `Runtime.register([...])`. Considera domain quando tem `name` (string)
+ * **sem** `kind` (descarta `ActionDef`) e **sem** `on`/`handler` no shape
+ * de reaction. Schedules têm `name + cron/every + action`, mas `action`
+ * é string — domain pode ter `actions` (plural). Faz a checagem por
+ * exclusão.
+ */
+export function isDomainConfig(value: unknown): value is DomainConfig {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  if (typeof v.name !== 'string') return false
+  // ActionDef tem `kind` literal ('simple' | 'form' | 'list' | 'view').
+  if (typeof v.kind === 'string') return false
+  // ReactionDef tem `on` + `handler`.
+  if ('on' in v && 'handler' in v) return false
+  // ScheduleDef tem `action` (string) + `cron`/`every`.
+  if (typeof v.action === 'string') return false
+  // Domain precisa de pelo menos um dos campos abaixo pra ser útil — o
+  // teste impede falso positivo em `{ name: 'x' }` solto que sobrou de
+  // outra coisa.
+  return (
+    'actions' in v ||
+    'reactions' in v ||
+    'schedules' in v ||
+    'subdomains' in v ||
+    'dicts' in v ||
+    'models' in v ||
+    'repository' in v ||
+    'service' in v
+  )
+}
+
+/**
+ * Achata um domínio (e seus subdomains recursivamente) em arrays prontos
+ * pro `Runtime.register`.
+ */
+export function flattenDomain(domain: DomainConfig): FlattenedDomain {
+  const out: FlattenedDomain = { actions: [], reactions: [], schedules: [] }
+  collect(domain, out)
+  return out
+}
+
+// =============================================================================
+// Internos
+// =============================================================================
+
+function collect(domain: DomainConfig, out: FlattenedDomain): void {
+  for (const action of iterateActions(domain.actions)) {
+    out.actions.push(action)
+  }
+  if (domain.reactions !== undefined) {
+    for (const reaction of domain.reactions) out.reactions.push(reaction)
+  }
+  if (domain.schedules !== undefined) {
+    for (const schedule of domain.schedules) out.schedules.push(schedule)
+  }
+  if (domain.subdomains !== undefined) {
+    for (const sub of domain.subdomains) collect(sub, out)
+  }
+}
+
+/**
+ * Normaliza `actions` (record | array | record-of-array) em iterável plano
+ * de `ActionDef`.
+ */
+function* iterateActions(
+  actions: DomainConfig['actions'],
+): IterableIterator<ActionDef> {
+  if (actions === undefined) return
+  // Um contrato puro (`ActionContract`, sem handler) entra como `ActionDef` no
+  // runtime — em design o `mockHandler` responde; fora de design, a ausência de
+  // handler falha no `execute` (intencional). O cast reconcilia o tipo neste
+  // boundary de normalização; ver `DomainAction`.
+  if (Array.isArray(actions)) {
+    for (const a of actions) yield a as ActionDef
+    return
+  }
+  for (const value of Object.values(actions)) {
+    if (Array.isArray(value)) {
+      for (const a of value) yield a as ActionDef
+    } else {
+      yield value as ActionDef
+    }
+  }
+}
+
+/**
+ * Valida um domínio recursivamente. `path` é a trilha dos ancestrais
+ * (camelCase concatenado em mensagens de erro).
+ */
+function validateDomain(domain: DomainConfig, path: string[]): void {
+  // — name —
+  if (typeof domain.name !== 'string' || domain.name.length === 0) {
+    throw error({
+      code: 'domain.invalid_name',
+      category: 'internal',
+      message: `Domain "name" deve ser string não-vazia${path.length > 0 ? ` (em "${path.join('.')}")` : ''}`,
+    })
+  }
+  if (!DOMAIN_NAME_RE.test(domain.name)) {
+    throw error({
+      code: 'domain.invalid_name_format',
+      category: 'internal',
+      message: `Domain name "${domain.name}" deve casar com [a-z][a-zA-Z0-9_]*${path.length > 0 ? ` (em "${path.join('.')}")` : ''}`,
+    })
+  }
+
+  const fullPath = [...path, domain.name]
+  const fullPathStr = fullPath.join('.')
+
+  // — subdomains: nomes únicos entre siblings —
+  if (domain.subdomains !== undefined) {
+    const seen = new Set<string>()
+    for (const sub of domain.subdomains) {
+      if (typeof sub.name !== 'string' || sub.name.length === 0) {
+        // Recursão vai validar; ainda assim, evitar set com chave estranha.
+        validateDomain(sub, fullPath)
+        continue
+      }
+      if (seen.has(sub.name)) {
+        throw error({
+          code: 'domain.duplicate_subdomain',
+          category: 'internal',
+          message: `Subdomain "${sub.name}" duplicado em "${fullPathStr}"`,
+        })
+      }
+      seen.add(sub.name)
+      validateDomain(sub, fullPath)
+    }
+  }
+
+  // — actions: nomes únicos no domínio (e subdomínios) —
+  // (Roda *depois* dos subdomains: assim erros de nome em subs aparecem
+  // primeiro, antes de detectar duplicatas cruzadas.)
+  const collected: FlattenedDomain = { actions: [], reactions: [], schedules: [] }
+  collect(domain, collected)
+
+  const actionNames = new Set<string>()
+  for (const action of collected.actions) {
+    if (actionNames.has(action.name)) {
+      throw error({
+        code: 'domain.duplicate_action',
+        category: 'internal',
+        message: `Action "${action.name}" duplicada em "${fullPathStr}"`,
+      })
+    }
+    actionNames.add(action.name)
+  }
+}
+
+/**
+ * Caminha a árvore emitindo warnings de nomenclatura. `path` é a trilha de
+ * ancestrais (excluindo o próprio `domain`).
+ */
+function walkForWarnings(domain: DomainConfig, path: string[]): void {
+  const fullPath = [...path, domain.name]
+  const fullPathStr = fullPath.join('.')
+  for (const action of iterateActions(domain.actions)) {
+    if (!actionNameMatchesPath(action.name, fullPath)) {
+      console.warn(
+        `[opus] Action "${action.name}" não casa com prefixo "${fullPathStr}." — considere renomear.`,
+      )
+    }
+  }
+  if (domain.subdomains !== undefined) {
+    for (const sub of domain.subdomains) walkForWarnings(sub, fullPath)
+  }
+}
+
+/**
+ * `true` se `actionName` começa com `<domain>.` ou `<domain>.<sub>.` etc,
+ * e ainda tem um segmento de verbo no final.
+ */
+function actionNameMatchesPath(actionName: string, path: string[]): boolean {
+  const parts = actionName.split('.')
+  // Precisa de pelo menos `domain.verb`.
+  if (parts.length < path.length + 1) return false
+  for (let i = 0; i < path.length; i++) {
+    if (parts[i] !== path[i]) return false
+  }
+  return true
+}