Jane result

The complete, structured output of every pipeline and boundary run

Every pipeline and boundary in Jane returns a single, predictable, fully‑structured object: the JaneResult. This is the contract of the entire framework — the thing you interact with after running .run(). It contains everything you need to understand what happened, why it happened, and what the final value is.

The JaneResult is intentionally rich, but never overwhelming. It’s designed so you can use as much or as little of it as you need. If all you care about is ok and value, that’s all you ever have to look at. If you want deep introspection: diff, explain, replay, telemetry — it’s all there. Cleanly separated and easy to consume.

Why the JaneResult Exists

Most validation libraries return one of two things:

• A boolean.
• A boolean and a list of errors.

That works until you need to know:

• What changed during normalization.
• What was parsed.
• What rules ran.
• What events were emitted.
• What the raw versus safe versus normalized versus final values were.
• How long the pipeline took.
• What the structural diff looks like.
• How to replay the diff.
• How to generate a human‑readable explanation.
• How to emit telemetry.

JaneResult exists because real systems need more than "true" or "false". They need transparency.

Jane gives you a complete, structured record of the entire pipeline.

The Shape of a JaneResult

Here’s the conceptual shape (not the TypeScript):

{
    ok: boolean,
    value?: T,

    issues?: JaneEvent[],
    events?: JaneEvent[],

    diff?: DiffResult,
    explain?: ExplainResult,
    replay?: ReplayResult,

    metadata: {
        raw,
        rawType,
        safe,
        safeType,
        normalized,
        normalizedType,
        final,
        finalType,
        startedAt,
        finishedAt,
        durationMs,
        inputName?
    }
}

Let’s walk through each part.

ok — The final decision

This is the simplest part of the result:

• true: The value is acceptable.
• false: The value is not acceptable.

This decision comes from policy, not from validators directly. Validators emit events. Policy interprets them. ok is the final verdict.

value — The final interpreted value

If ok is true, value contains the final value after:

• Containment
• Normalization
• Parsing

If ok is false, value is omitted unless you explicitly include rejected values at the boundary level. This keeps the API safe by default.

issues — Only the errors

Issues are the subset of events that represent:

• error
• fatal

This is the "what went wrong" list. If you only care about failures, this is the field you use.

events — Everything that happened

Events include:

• Scan events
• Normalization events
• Parse events
• Validation events

This is the full story of the pipeline. If you want to understand the entire run, this is where you look.

diff — Structural changes during normalization

If diff analysis is enabled, you get a structural diff between:

• safe (contained raw value).
• normalized (after normalization rules).

This is incredibly useful for:

• Debugging.
• Audits.
• Compliance.
• Understanding lossy transformations.

Diff is optional and lazy. It only runs if you ask for it.

explain — A human‑readable narrative

Explain turns the pipeline into a linear story:

• Hazards found during scan.
• Structural changes during normalization.
• Semantic changes during parsing.
• Validation errors.

This is perfect for:

• Debugging.
• UI error messages.
• Logs.
• Onboarding new developers.

Explain is also optional and lazy.

replay — Reconstructing the normalized value step‑by‑step

Replay applies each diff entry in order and records the intermediate states.

This is useful for:

• Audits.
• Reproducibility.
• Debugging complex normalization rules.
• Teaching contributors how normalization works.

Replay is optional and lazy.

metadata — Everything you need for observability

Metadata includes:

• raw value and type.
• safe value and type.
• normalized value and type.
• final value and type.
• Timestamps.
• Duration.
• inputName.

This is the backbone of:

• Telemetry.
• Logging.
• Debugging.
• Performance analysis.
• Compliance.

Metadata is always included, even if analysis features are disabled.

Why the JaneResult Matters

The JaneResult is the reason Jane feels transparent and trustworthy.

It gives you the:

• Final value
• Decision
• Issues
• Full event history
• Structural diff
• Narrative explanation
• Replay steps
• Metadata

All in one place. Cleanly separated, predictable, and easy to consume. It’s the difference between a black‑box validator and a real data boundary framework.