@hecto/devtools

Trace disclosure policy

exportTrace(serviceId) creates a safe-to-share trace. Without a redact option, it replaces every application payload leaf with a redaction marker. It retains the record sequence, state values, versions, statuses, event and command type fields, and patch paths so the exported trace can still be imported and replayed in either direction.

Pass createDevtoolsClient({ redact(path, value) { ... } }) to choose which payload leaves to preserve or replace. The path starts with initialInput, state, or records, so one policy covers live traces and traces loaded with importTrace. A custom policy is responsible for every value it returns.

Logical history state always uses the canonical state.context path. The exporter sanitizes each state first, then derives its forward and inverse patches from those sanitized states. This keeps path-sensitive policy output identical whether replay starts at a checkpoint or travels across a patch.

If retention starts at a checkpoint whose predecessor has already been evicted, safe export omits that checkpoint's obsolete backward patch. Replay begins from the retained checkpoint state; no unavailable earlier state is implied or disclosed.

The following APIs intentionally expose raw application values for local inspection:

• getRawLog
• subscribeRaw
• forkRawSandbox, including SandboxHandle.getRawLog
• exportRawTrace

Do not share their output without applying an application-specific disclosure policy. getLog, subscribe, forkSandbox, and SandboxHandle.getLog remain as deprecated raw aliases for compatibility.

Imported trace limits

importTrace decodes format version 1 into an owned deep copy. It rejects unknown or malformed record kinds, invalid history patches, non-increasing sequences, non-JSON values including sparse arrays, and unsafe patch paths with a records[index] location where applicable. Mutating either the caller's object or any nested operation path in a later raw-log/raw-export copy cannot change imported replay.

DEVTOOLS_TRACE_LIMITS publishes the fixed ingestion bounds: 10,000 records, 10,000 operations per patch, 64 nested levels, and 5 MiB of UTF-8 JSON. A newer envelope requires a new formatVersion decoder rather than silently accepting changed record shapes.

Retained history

History capacity and checkpoint interval must be finite positive integers. The capacity includes events and diagnostics. When eviction reaches a patch or an event-only stretch after recorded state, the history synthesizes one checkpoint at the retained boundary, then keeps the newest records that fit. The log-truncated diagnostic is emitted once with the triggering record's timestamp.