audit.query y getScope(name).query — findMany, findById, count, filtros y lifecycle.

En el mismo objeto app

La read API viene como audit.query en la app de startTracevault, y como audit.getScope("name").query por scope. Es deliberadamente acotada: filtros de igualdad en columnas escalares (incluyendo outcome, error_code, severity generados), ventana en occurred_at y paginación determinística. Agregaciones, probes JSONB y joins van en SQL directo.

read.ts

const recent = await audit.query.findMany({
  event: "product.price.updated",
  from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
  limit: 100,
})

const scoped = await audit.getScope("users").query.findMany({
  event: "user.profile.updated",
  limit: 50,
})

const one = await audit.query.findById("uuid-here")
const total = await audit.query.count({ actorType: "user", environment: "prod" })

Lecturas con scope

Usá getScope("users").query en lugar de una factory de lectura separada. Todos los scopes comparten los pools de lectura y escritura de la app.

scoped-read.ts

const rows = await audit.getScope("users").query.findMany({
  event: "user.profile.updated",
  errorsOnly: true,
  limit: 50,
})

Vistas orientadas a errores

errorsOnly: true matchea filas donde outcome = 'failure' o severity está en SEVERITIES_FOR_ERRORS_ONLY_FILTER (exportado desde tracevault). Los filtros se combinan con AND.

errors.ts

// failures by outcome OR high-severity rows (see SEVERITIES_FOR_ERRORS_ONLY_FILTER)
await audit.query.findMany({
  errorsOnly: true,
  limit: 50,
})

Filtros findMany / count

Claves desconocidas lanzan ValidationError. Filtros string son igualdad exacta — sin LIKE. from / to no pueden estar invertidos.

Campo	Aplica a	Notas
event	findMany, count	Match exacto
actorId, actorType	findMany, count	Match exacto
targetId, targetType	findMany, count	Match exacto
correlationId, requestId	findMany, count	Match exacto
environment	findMany, count	Match exacto
outcome, errorCode, severity	findMany, count	Columnas generadas (migraciones 002–003)
severities	findMany, count	IN list, máx 16, sin duplicados
errorsOnly	findMany, count	outcome failure o severities altas
mode	findMany, count	sync \| async
from, to	findMany, count	Límites inclusivos en occurredAt
limit, offset, order	solo findMany	limit 1–500 (default 50), order asc\|desc en (occurred_at, id)

Lifecycle

Llamá await audit.close() una vez: drena la cola de escritura de cada scope y cierra pools propios de Tracevault. pool / readPool inyectados no se cierran. Después de close, emit y query lanzan TracevaultError.

Tipos

AuditRecord, AuditQueryFilters, DOCUMENTED_SEVERITY_LEVELS y exports relacionados viven en el entry principal tracevault — sin paquete query separado en 1.x.

Referencia de columnas en Modelo de datos. setup en Install.