Enabling analysis features¶

Up to now, you’ve learned how Jane processes data: scanning, normalizing, parsing, validating, and deciding. That’s the core pipeline. But Jane also gives you something most validation libraries never attempt: full transparency.

Jane’s analysis layer is optional, lazy, and designed for real-world debugging, auditing, and observability. These features never affect the pipeline’s decision. They never mutate values. They never change severity. They simply observe and report.

This chapter introduces the four analysis tools:

Diff: What changed.
Explain: Why it changed.
Replay: How it changed
Telemetry: What happened, structured for systems.

Each one gives you a different lens into the pipeline.

Why Analysis Exists¶

Most validation libraries give you:

A boolean
Maybe a list of errors

That’s not enough when you need to answer questions like:

Why did this fail?
What changed during normalization?
What did the value look like after each step?
What happened inside this boundary?
How do I log this for audits or debugging?

Jane’s analysis layer exists to make the pipeline transparent, not magical.

You opt into each feature explicitly:

.withDiff()
.withExplain()
.withReplay()
.withTelemetry(sink)

Nothing runs unless you ask for it.

Diff: Seeing What Changed¶

Diff compares:

The safe value (after containment)
The normalized value (after normalization rules)

And records structural changes:

Added
Removed
Changed

Example:

const result = await jane.value("  hello  ")
  .withDiff()
  .run();

console.log(result.diff);

Diff is perfect for:

Debugging normalization.
Understanding lossy transformations.
Audits and compliance.
Teaching contributors how normalization works.

Diff is structural, not semantic. It tells you what changed, not why.

Explain: A Human‑Readable Narrative¶

Explain turns the entire pipeline into a chronological story:

Scan hazards
Normalization changes
Diff entries
Parse events
Validation events

Example:

const result = await jane.value(" 42 ")
  .parse("numeric")
  .positive()
  .withExplain()
  .run();

console.log(result.explain);

Explain is perfect for:

Debugging.
UI error messages.
Onboarding new developers.
Understanding complex pipelines.

Explain is narrative. It tells you why things happened.

Replay: Step‑By‑Step Reconstruction¶

Replay uses diff entries to reconstruct the normalized value one step at a time.

Example:

const result = await jane.value("  hello  ")
  .withReplay()
  .run();

console.log(result.replay);

Replay shows:

The initial safe value.
Each diff entry.
The intermediate state after each change.

Replay is perfect for:

Audits.
Debugging tricky normalization rules.
Teaching how normalization works internally.

Replay is procedural. It shows you how things changed.

Telemetry: Structured Observability for Real Systems¶

Telemetry emits structured records for each stage of the pipeline:

Scan
Normalize
Parse
Validate
Diff (optional)
Explain (optional)
Replay (optional)
Decision metadata

You provide the sink:

const result = await jane.value(input)
    .withTelemetry(records => {
            console.log(records);
    }).run();

Telemetry is perfect for:

Logs
Dashboards
Monitoring
Analytics
Compliance systems

Telemetry is systemic. It shows you everything that happened, in a machine‑friendly format.

How Analysis Fits Into the Pipeline¶

Analysis features run after the pipeline finishes.

They never influence:

Parsing
Validation
Normalization
Decision making

They are observers, not participants. This keeps the pipeline deterministic and safe.

Using Analysis Features Together¶

You can enable any combination:

const result = await jane.value(" 42 ")
  .parse("numeric")
  .positive()
  .withDiff()
  .withExplain()
  .withReplay()
  .withTelemetry(console.log)
  .run();

Each feature adds a different dimension of visibility.

What You’ve Learned¶

You now understand:

What the analysis layer is.
Why it exists.
How to enable diff, explain, replay, and telemetry.
How each feature provides a different lens.
How analysis integrates with real systems.

Next, we'll take a look policies.

Customizing policy