Replay

Reconstructing the normalized value step‑by‑step — transparent, deterministic, and perfect for audits.

Replay is the third part of Jane’s analysis layer, sitting alongside Diff and Explain. If Diff tells you what changed and Explain tells you why it changed, Replay shows you how it changed, one step at a time. It’s a deterministic reconstruction of the normalization process, built entirely from the diff entries.

Replay doesn’t validate, parse, normalize, or interpret anything. It simply applies each diff entry in order and records the intermediate states. This gives you a complete, inspection-enabled timeline of how the value evolved.

Replay is the closest thing Jane has to a time machine.

Why Replay Exists

Normalization can involve multiple structural changes:

• Trimming strings.
• Removing empty keys.
• Compacting arrays.
• Converting invalid dates.
• Flattening nested structures.
• Removing undefined values.

Diff shows you the final set of changes.

Explain tells you why they happened. Replay shows you the sequence. Replay exists for the moments when you need to answer questions like:

• What did the value look like after the first normalization rule?
• Which change caused this downstream issue?
• How did we get from the raw value to the final one?
• Can we reproduce the exact normalization process for auditing?
• What was the intermediate state before this change?

Replay is especially valuable in regulated environments, debugging sessions, and contributor onboarding.

What Replay Does

Replay takes:

• The before value (the contained raw value).
• The diff entries (structural changes).

...and applies each diff entry in order.

For each step, Replay records:

• The index of the diff entry.
• The diff entry itself.
• The full intermediate state after applying it.

This produces a clean, chronological list of states. Replay never mutates the original value. It always works on deep clones.

When Replay Runs

Replay is optional and lazy.

It only runs if:

• The policy enables replay analysis.
• You explicitly request it using withReplay().

Example:

const replay = await jane.value(input).nonEmpty().withReplay();

If you don’t ask for replay, Jane doesn’t compute it. This keeps the pipeline fast by default.

What Replay Never Does

Replay is intentionally limited. It does not:

• Validate.
• Parse.
• Normalize.
• Mutate the original value.
• Affect the pipeline decision.
• Interpret semantics.
• Change event severity.
• Rewrite event codes.

Replay is purely observational. It reconstructs — it never influences.

How Replay Works (Conceptually)

Replay starts with:

current = deepClone(before)

Then for each diff entry:

• Apply the change (added, removed, changed).
• Deep clone the new state.
• Record the step.

This produces a sequence like:

• Step 0: Initial state.
• Step 1: After trimming whitespace.
• Step 2: After removing empty keys.
• Step 3: After compacting array.
• ...

Replay is deterministic — the same diff always produces the same sequence.

Example Replay Output

Imagine this input:

{
  name: "  Alice  ",
  tags: ["a", "", "b"]
}

Normalization trims the name and removes empty tags.

Replay might produce:

[
  {
    index: 0,
    entry: { kind: "changed", path: "$.name", before: "  Alice  ", after: "Alice" },
    state: { name: "Alice", tags: ["a", "", "b"] }
  },
  {
    index: 1,
    entry: { kind: "removed", path: "$.tags[1]", before: "" },
    state: { name: "Alice", tags: ["a", "b"] }
  }
]

You can see the value evolve step‑by‑step.

Why Replay Matters

Replay is the layer that makes normalization:

• Transparent
• Reproducible
• Auditable
• Teachable
• Debuggable

It’s perfect for:

• Compliance and audit logs.
• Debugging complex normalization rules.
• Understanding lossy transformations.
• Teaching contributors how normalization works.
• Building developer tools around Jane.

Replay turns normalization from a single before and after snapshot into a full timeline.