传输契约矩阵
本矩阵把每个一方 transport 与其公开入口、源码文件和契约测试一一对应，目的是让可靠性说法可以被核查：原始线上协议 transport 必须暴露投递失败；生产级投递必须明确说明使用的包装器或队列；生命周期行为必须有对应的测试路径。
pnpm verify:transport-contracts 会把本页与各包的导出和仓库文件树进行核对。新增 transport 源文件或公开的 transport 子路径时，必须在同一次变更中更新本矩阵。
契约规则
- 原始 HTTP/厂商 transport 会把非 2xx 响应和被拒绝的
fetch调用作为失败向上传递；除非外面包了包装器，否则不会静默重试。 - 原始线上协议 sink 要用于生产投递，需要
batchTransport()、retryTransport()、fallbackTransport()，或使用一个在文档中说明了自身队列/重试行为的 transport。 - 依赖运行时的 transport 必须说明所依赖的平台能力，并测试依赖不可用或失败的情况。
- 持久化路径必须在测试中体现
flush()或持久化/重放行为。 - 仅用于测试或仅用于显示的 transport 必须明确说明这一点，不能暗示具备持久投递能力。
矩阵
| ID | 公开入口 | 导出 | 源码 | 投递契约 | 失败与生命周期契约 | 契约测试 |
|---|---|---|---|---|---|---|
core-batch | @loggerjs/core/transport-batch | batchTransport | packages/core/src/transports/batch.ts | 为任意内部 transport 提供有界队列、字节预算、定时 flush、并发、重试、熔断器和丢弃计数。 | 失败的批次按策略重试或重新入队；flush() 会排空队列；close() 停止定时器并 flush 待处理的工作。 | packages/core/test/batch-transport.test.ts packages/core/test/batch-coverage.test.ts |
core-retry | @loggerjs/core/transport-reliability | retryTransport, fallbackTransport | packages/core/src/transports/reliability.ts | 为已经自带批量、或可以接受逐次调用重试的 transport 提供即时重试/回退包装器。 | 重试使用有上限的退避；熔断和回退行为可以观测；flush()/close() 会转交给被包装的 transport。 | packages/core/test/reliability-transport.test.ts packages/core/test/reliability-coverage.test.ts |
core-console | @loggerjs/core/transport-console | consoleTransport | packages/core/src/transports/console.ts | 与运行时无关的本地 console sink。 | 通过未被 patch 的 console 函数输出，避免采集递归；默认过滤来自 console 的事件。 | packages/core/test/console-transport.test.ts |
core-memory | 根入口 | memoryTransport | packages/core/src/transports/memory.ts | 有界的内存诊断环形缓冲区；不持久化。 | 超过容量时丢弃最旧的条目；快照是同步的，仅在当前进程内有效。 | packages/core/test/logger.test.ts packages/core/test/integration-api.test.ts |
core-test | @loggerjs/core/transport-test | testTransport | packages/core/src/transports/test.ts | 仅用于断言的内存 sink，提供等待和快照辅助方法。 | 可注入的失败和等待超时属于测试契约；不是生产用 sink。 | packages/core/test/test-transport.test.ts |
browser-http | @loggerjs/browser/transport-http | browserHttpTransport | packages/browser/src/http-transport.ts | 浏览器 fetch 投递，支持批量、重试选项、可选离线队列、payload 转换和页面退出时的 Beacon 模式。 | 非 2xx 响应和被拒绝的 fetch 都视为失败；页面退出时的 Beacon 是尽力而为，受大小和运行时限制。 | packages/browser/test/http-transport.test.ts tests/e2e/browser-production.spec.ts |
browser-indexeddb-queue | @loggerjs/browser/offline-indexeddb, @loggerjs/browser/transport-indexeddb | indexedDbBrowserHttpOfflineQueue, indexedDbTransport | packages/browser/src/indexeddb-offline-queue.ts packages/browser/src/indexeddb-transport.ts | 持久化的浏览器队列/存储，用于刷新后仍能重放和本地导出。 | IndexedDB 不可用、配额、隐私模式、升级被阻塞、TTL 和清理都依赖运行时，并有对应测试。 | packages/browser/test/indexeddb-offline-queue.test.ts packages/browser/test/indexeddb-transport.test.ts tests/e2e/browser-production.spec.ts |
browser-offline-first | @loggerjs/browser/offline-first-transport | offlineFirstTransport | packages/browser/src/offline-first-transport.ts | 优先投递到远端，离线或远端失败后入队并稍后重放。 | 远端拒绝时 payload 进入队列；存储和网络可用时，flush() 会重放队列中的记录。 | packages/browser/test/offline-first-transport.test.ts |
browser-page-exit | @loggerjs/browser/transport-http, @loggerjs/browser/integration-page-lifecycle | browserHttpTransport 的页面生命周期 flush | packages/browser/src/http-transport.ts packages/browser/src/page-lifecycle.ts | 浏览器 HTTP 在 pagehide/visibilitychange 时的最后一次投递机会。 | sendBeacon 是尽力而为；不支持或发送失败时，会尽可能回退到已配置的 HTTP 行为。 | packages/browser/test/http-transport.test.ts packages/browser/test/page-lifecycle.test.ts tests/e2e/browser-production.spec.ts |
browser-service-worker | @loggerjs/browser/transport-service-worker | browserServiceWorkerTransport | packages/browser/src/service-worker-transport.ts | 在已配置的或已就绪的 service worker controller 可用前排队，之后再发送消息。 | registration/controller 是否可用取决于运行时；ready() 和 flush() 暴露了接收边界。 | packages/browser/test/service-worker-transport.test.ts tests/e2e/browser-production.spec.ts |
browser-websocket | @loggerjs/browser/transport-websocket | browserWebSocketTransport | packages/browser/src/websocket-transport.ts | 实时 WebSocket sink，连接中或已关闭时使用有界队列。 | 重连由调用方负责；队列上限和关闭/错误行为都有明确定义。 | packages/browser/test/websocket-transport.test.ts |
browser-broadcast | @loggerjs/browser/transport-broadcast-channel | browserBroadcastChannelTransport | packages/browser/src/broadcast-channel-transport.ts | 通过 BroadcastChannel 向同源的其他标签页分发日志。 | 不保证存在接收方；API 缺失和关闭语义有对应测试。 | packages/browser/test/broadcast-channel-transport.test.ts |
node-http | @loggerjs/node/transport-http | nodeHttpTransport | packages/node/src/http-transport.ts | Node fetch 投递，内部用 batchTransport 包装。 | 非 2xx 或被拒绝的 fetch 由包装器重试；flush() 会排空批量的 HTTP 工作。 | packages/node/test/http-transport.test.ts |
node-file | @loggerjs/node/transport-file, @loggerjs/node/transport-rotating-file | fileTransport, rotatingFileTransport | packages/node/src/file-transport.ts packages/node/src/rotating-file-transport.ts | 本地 NDJSON 文件持久化，可选同步写入、缓冲和按大小轮转。 | flush() 排空正常写入；支持时，flushSync() 是崩溃路径契约；轮转要求单一写入者。 | packages/node/test/file-transport.test.ts packages/node/test/rotating-file-transport.test.ts |
node-stdout | @loggerjs/node/transport-stdout | stdoutTransport, stderrTransport | packages/node/src/stdout-transport.ts | stdout/stderr 的 NDJSON 流 sink，可选缓冲。 | 感知背压并等待 drain；默认把 EPIPE 视为正常关闭；flush() 排空缓冲的写入。 | packages/node/test/stdout-transport.test.ts |
node-syslog | @loggerjs/node/transport-syslog | nodeSyslogTransport | packages/node/src/syslog-transport.ts | 通过 UDP 或 TCP 发送 RFC 风格的 syslog 格式消息。 | UDP 可能丢失；TCP 依赖 socket 生命周期；格式化、发送、关闭和错误行为都有测试。 | packages/node/test/syslog-transport.test.ts |
node-worker | @loggerjs/node/transport-worker | workerTransport | packages/node/src/worker-transport.ts | 把工作卸载到 worker 线程，支持 codec 传输和可选的 ready/ack 握手。 | 启动、ack 超时、回退、关闭和自动结束行为共同定义了接收边界。 | packages/node/test/worker-transport.test.ts |
database | @loggerjs/database/transport, @loggerjs/database/sqlite, @loggerjs/database/postgres | databaseTransport, sqliteTransport, postgresTransport | packages/database/src/transport.ts packages/database/src/sqlite.ts packages/database/src/postgres.ts | 把批量行映射交给应用提供的适配器、SQLite 驱动或 Postgres 客户端。 | 适配器/驱动的失败通过 batch/retry 和内部错误上报暴露；事务语义由驱动负责。 | packages/database/test/database-transport.test.ts |
datadog | @loggerjs/datadog/transport | datadogLogsTransport | packages/datadog/src/index.ts | 原始的 Datadog Logs HTTP payload sink。 | 缺少 fetch、非 2xx 或被拒绝的 fetch 都会让原始 transport 失败；生产持久性需要 batchTransport() 或 retryTransport()。 | packages/datadog/test/datadog-transport.test.ts |
elastic | @loggerjs/elastic/transport | elasticTransport | packages/elastic/src/index.ts | 原始的 Elastic bulk HTTP payload sink。 | 缺少 fetch、非 2xx 或被拒绝的 fetch 都会让原始 transport 失败；生产持久性需要 batchTransport() 或 retryTransport()。 | packages/elastic/test/elastic-transport.test.ts |
loki | @loggerjs/loki/transport | lokiTransport | packages/loki/src/index.ts | 原始的 Loki push HTTP payload sink。 | 缺少 fetch、非 2xx 或被拒绝的 fetch 都会让原始 transport 失败；生产持久性需要 batchTransport() 或 retryTransport()。 | packages/loki/test/loki-transport.test.ts |
cloudwatch | @loggerjs/cloudwatch/transport | cloudWatchLogsTransport | packages/cloudwatch/src/index.ts | 原始的 CloudWatch Logs API payload sink。 | 缺少 fetch、非 2xx 或被拒绝的 fetch 都会让原始 transport 失败；sequence token 的推进仍取决于调用方和服务端。 | packages/cloudwatch/test/cloudwatch-transport.test.ts |
sentry | @loggerjs/sentry/transport | sentryTransport | packages/sentry/src/index.ts | 适配应用提供的 Sentry SDK 对象。 | SDK 抛出的异常会让原始 transport 失败，并可被包装器观察到；capture 级别映射和被禁用的 SDK 方法有测试。 | packages/sentry/test/sentry-transport.test.ts |
otel-otlp | @loggerjs/otel/transport-http, @loggerjs/otel/codec-otlp-json | otlpHttpTransport, otlpJsonCodec | packages/otel/src/transport.ts packages/otel/src/otlp-json.ts | OTLP/HTTP JSON 投递，内部用 batchTransport 包装；codec 把 LoggerJS 事件映射为 OTLP 日志。 | 非 2xx 或被拒绝的 fetch 由包装器重试；codec 的结构和元数据映射有测试固定。 | packages/otel/test/otlp-json.test.ts |
pretty-console | @loggerjs/pretty/transport-console | prettyConsoleTransport | packages/pretty/src/console-transport.ts | 面向人阅读的浏览器/console 显示 sink。 | 仅用于显示；避免 console 采集回环，并为 DevTools 保留原始参数。 | packages/pretty/test/console-transport.test.ts |
pretty-stream | @loggerjs/pretty/transport-stream | prettyStreamTransport, prettyStdoutTransport, prettyStderrTransport | packages/pretty/src/stream-transport.ts | 面向人阅读的流 sink，用于 Node 终端或类流目标。 | 背压和流错误可见；支持时，flush() 会等待 drain。 | packages/pretty/test/stream-transport.test.ts |