Tracing & Debugging

The engine emits structured events through a Tracer at explicit pipeline boundaries. Trace events are JSON-safe and use logical timestamps, so they can be stored, compared, imported, and replayed without relying on DOM state.

Tracer

createTracer(sink: TraceSink, sessionId?: TraceSessionId): Tracer

Sinks: NoopTraceSink, MemoryTraceSink, or a custom TraceSink implementation. When ts is omitted, the tracer assigns deterministic logical timestamps (0, 1, 2, ...). Each emission also accepts optional tags and JSON-safe data. See packages/core/src/trace.ts.

Event types

Events extend TraceEventBase. The built-in event kinds are:

• intentReceived
• planCompiled
• transactionApplied
• normalized
• history
• custom

Their TypeScript interfaces are TraceIntentReceived, TracePlanCompiled, TraceTransactionApplied, TraceNormalized, TraceHistory, and TraceCustom. Sessions are identified by TraceSessionId; normalization rules by NormalizationRuleId. Payloads are TraceData (Readonly<Record<string, JsonValue>>).

Export / import

exportTrace(events: readonly TraceEvent[], sessionId?: TraceSessionId): JsonValue
importTrace(value: JsonValue): { sessionId?: TraceSessionId; events: readonly TraceEvent[] }

exportTrace preserves emitted order. importTrace returns events sorted by logical timestamp, preserving original order for events with the same timestamp.

Replay

replayIntents runs intents through a real engine instance. replayTransactions applies stored transactions directly against editor state and still runs the normalizer. Both return ReplayArtifacts: final state, transaction JSON, trace events, and exported trace JSON.

Comparison helpers include replayArtifactsEqual, replayArtifactsSemanticallyEqual, and replayArtifactsNormalizedEqual.