Skip to content

Explain

A clear, human‑readable narrative of everything that happened in the pipeline.

Explain is Jane’s narrative layer — the part of the system that takes all the structural, semantic, and validation events and turns them into a clean, chronological story. It’s not for machines. It’s for humans. It’s the “tell me what happened” feature that makes Jane feel transparent instead of magical.

Explain doesn’t validate, parse, normalize, or decide anything. It simply observes the pipeline and produces a readable sequence of steps that describe what happened and why.

If Diff shows you what changed, Explain shows you why it changed.

Why Explain Exists

Most validation libraries give you a boolean and maybe a list of errors. That’s fine until you need to answer questions like:

  • Why did this value get rejected?
  • What changed during normalization?
  • Why did parsing fail?
  • What rules ran?
  • What happened first?
  • What happened last?
  • What exactly did Jane do to this value?

Explain exists to make the pipeline understandable — not just correct.

It’s the difference between debugging in the dark and having a flashlight.

What Explain Does

Explain takes the events from each pipeline stage and turns them into a linear sequence of explain steps. Each step includes:

  • The path where it happened.
  • The stage (scan, normalize, parse, validate).
  • The kind of step (hazard, change, error).
  • The event code.
  • A human‑readable message.

Explain also incorporates diff entries (if diff is enabled), turning structural changes into readable descriptions like:

  • "Added value: 42”
  • "Removed value: null"
  • "Changed from " hello " to "hello""

This gives you a complete, chronological narrative of the entire pipeline.

When Explain Runs

Explain is optional and lazy.

It only runs if:

  • The policy enables explain analysis.
  • You explicitly request it using withExplain().

Example:

const explanation = await jane.value(input).nonEmpty().withExplain();

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

What Explain Never Does

Explain is intentionally limited. It does not:

  • Validate.
  • Parse.
  • Normalize.
  • Mutate values.
  • Affect the decision.
  • Change event severity.
  • Rewrite event codes.
  • Coerce types.

Explain is purely observational. It tells you what happened — not what it means.

How Explain Works

Explain walks through the pipeline stages in order:

  1. Scan hazards: Structural issues detected before anything else.
  2. Normalization events: Structural changes, warnings, and hazards.
  3. Diff entries (optional): A readable description of added, removed, and changed values.
  4. Parse events: Semantic changes (for example, string → number).
  5. Validation events: Business rule failures.

Each event becomes a step in the narrative. The result is a clean, chronological story.

Example Explain Output

Imagine this input:

" 42 "

With numeric parsing and validation:

[
  { stage: "normalize", kind: "change", message: "Changed from \" 42 \" to \"42\"" },
  { stage: "parse", kind: "change", message: "Parsed numeric string to number" },
  { stage: "validate", kind: "error", message: "Value must be positive" }
]

Readable. Chronological. Human‑friendly.

Why Explain Matters

Explain is the layer that makes Jane feel:

  • Debuggable.
  • Transparent.
  • Trustworthy.
  • Teachable.
  • Auditable.

It’s perfect for:

  • Developer debugging.
  • UI error messages.
  • Logs.
  • Onboarding.
  • Compliance.
  • Support tooling.

Explain turns the pipeline from a black box into a story you can follow.