Policy catalog

Policy is the interpretation layer of the Jane pipeline. It does not parse, validate, normalize, or mutate values. Instead, it interprets the events emitted by scan, normalization, parsing, and validation, and decides what those events mean for the pipeline’s final outcome.

Policy determines:

• Whether the pipeline is accepted, rejected, or marked for review
• How event severities are transformed
• Whether analysis features are enabled
• Whether scan is active
• Whether certain structural types (BigInt, Map, Set) are allowed
• Which patterns automatically reject, review, or warn

Policy is opt‑in, explicit, and immutable. Every pipeline and boundary runs under a specific policy.

How Policy Works

1. The pipeline emits events: Scan, normalization, parsing, and validation each produce structured events describing what happened.

2. Policy receives the full event list: Policy does not influence event creation — only interpretation.

3. Policy applies transforms:

   Policy may:

   • Escalate severities.
   • Downgrade severities.
   • Override specific event codes.
   • Match wildcard patterns.
   • Apply reject and review rules.

4. Policy produces the final decision

   Policy determines:

   • ok: true: Accepted
   • ok: false: Rejected
   • ok: false: Review events or review required

5. Analysis features run last

   If enabled, diff/explain/replay/telemetry are generated after the decision.

Policy never mutates values, never changes the pipeline’s structure, and never runs rules. It is purely interpretive.

Policy Fields

A Policy object contains the following fields:

• mode: Controls strictness and normalization behavior.
• strict
• moderate (default)
• lax
• decide: Controls how events are interpreted.
• reject: string[] — wildcard patterns that trigger automatic rejection
• review: string[] — wildcard patterns that require human review
• warn: string[] — patterns that always produce warnings
• override: Record<string, number> — severity downgrades
• escalate: Record<string, number> — severity upgrades
• analysis: Controls which analysis features are enabled.
• diff
• explain
• replay
• telemetry
• scan: Enables or disables scan entirely.
• exception: Controls whether certain structural types are allowed:
• bigint

Built‑In Policies

Jane ships with three built‑in policies that define the baseline behavior for most applications.

Default Policy

Moderate, safe, predictable.

The default policy is designed for typical backend and application boundaries. It is safe, predictable, and avoids surprises.

export const defaultPolicy: Policy = {
    mode: 'moderate',

    decide: {
        reject: [],
        review: [],
        warn: [],
        override: {},
        escalate: {},
    },

    analysis: {
        diff: false,
        explain: false,
        replay: false,
        telemetry: false,
    },

    scan: false,

    exception: {
        bigint: false,
        map: false,
        set: false,
    },
};

Characteristics

• No automatic rejection.
• No severity transforms.
• No analysis features.
• Scan disabled.
• Bigint disallowed unless explicitly enabled.

This is the baseline for most pipelines.

Lax Policy

Permissive, forgiving, developer‑friendly.

Lax mode is ideal for user input, prototyping, and developer tools. It prioritizes convenience over strictness.

export const laxPolicy: Policy = {
    mode: 'lax',

    scan: false,

    decide: {
        reject: [],
        review: [],
        override: {
            '*': 1, // shift severity down by 1
        },
        escalate: {},
        warn: [],
    },

    analysis: {
        diff: false,
        explain: false,
        replay: false,
        telemetry: false,
    },

    exception: {
        bigint: true,
        map: true,
        set: true,
    },
};

Characteristics

• No automatic rejection.
• All severities are downgraded.
• Scan disabled.
• Bigint allowed.
• No analysis features.

Perfect for messy real‑world input.

Strict Policy

Maximum safety, maximum scrutiny.

Strict mode is designed for compliance, regulated environments, and high‑assurance boundaries.

export const strictPolicy: Policy = {
    mode: 'strict',

    scan: true,

    decide: {
        reject: [
            'value.was.contained',
            'object.has.circular-references',
            'number.not.finite',
            'number.not.number',
            'date.is.invalid',
            'string.has.unsafe-unicode',
            'array.is.deep',
            'object.is.deep',
        ],

        review: ['array.is.large', 'object.has.many-keys', 'string.is.long', 'bigint.is.large'],

        escalate: {
            '*': 1, // every warn → error
        },

        override: {},

        warn: [],
    },

    analysis: {
        diff: true,
        explain: true,
        replay: true,
        telemetry: true,
    },

    exception: {
        bigint: false,
        map: false,
        set: false,
    },
};

Characteristics

• Automatic rejection for dangerous patterns.
• Automatic review for suspicious patterns.
• All warnings are escalated to errors.
• Scan enabled.
• Full analysis enabled.
• BigInt disallowed.

This is the policy for high‑risk boundaries.

Example: Severity Transform

A simple example of a policy that downgrades all errors to warnings:

const forgivingPolicy = jane.policy({
    decide: {
        override: { '*': 1 }
    }
});

This illustrates the policy contract:

• Pattern matching is wildcard‑based.
• Transforms shift severity up or down.
• Policy never mutates values.
• Policy never runs rules.
• Policy only interprets events.

Summary

Policy is the decision layer of the Jane pipeline. It interprets events emitted by scan, normalization, parsing, and validation, and determines the final outcome of the pipeline.

Policy is:

• Explicit — nothing happens unless configured
• Interpretive — never mutates values
• Pattern‑driven — wildcard matching for reject/review rules
• Severity‑aware — can escalate or downgrade events
• Mode‑driven — strict, moderate, lax
• Analysis‑controlling — diff, explain, replay, telemetry
• Structural‑type‑aware — BigInt/Map/Set exceptions

Policy is what makes Jane predictable, transparent, and adaptable to different environments — from permissive user‑facing forms to strict compliance boundaries.