@clementine-solutions/jane-io 1.0.0 → 1.0.2

package/dist/core/common/policy.js

@@ -0,0 +1,550 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Common | Policy
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Core types and helpers for defining, normalizing, and
+ *                  resolving policies that guide how Jane interprets events
+ *                  across all pipeline stages.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { createEvent, getCompiledWildcard, matchesWildcard } from '.';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Apply Escalate                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Raises an event’s severity by the given number of levels.
+ *
+ * Escalation moves the severity index upward and clamps it to the valid
+ * range. This helper is used by policy transforms to harden events without
+ * altering their underlying meaning or code.
+ */
+export function applyEscalate(kind, levels) {
+    const idx = severityIndex(kind);
+    const next = clampSeverityIndex(idx + levels);
+    return SEVERITY_ORDER[next];
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Apply Override                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Lowers an event’s severity by the given number of levels.
+ *
+ * Override moves the severity index downward and clamps it to the valid
+ * range. This helper is used by policy transforms to soften events without
+ * changing their underlying meaning or code.
+ */
+export function applyOverride(kind, levels) {
+    const idx = severityIndex(kind);
+    const next = clampSeverityIndex(idx - levels);
+    return SEVERITY_ORDER[next];
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Clamp Severity Index                                                      *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Clamps a severity index to the valid range.
+ *
+ * Severity levels are stored as an ordered list. This helper ensures that
+ * arithmetic on the index—such as escalation or override—never produces an
+ * out‑of‑bounds value. No interpretation occurs here; it simply enforces the
+ * valid numeric range.
+ */
+export function clampSeverityIndex(i) {
+    if (i < 0)
+        return 0;
+    if (i >= SEVERITY_ORDER.length)
+        return SEVERITY_ORDER.length - 1;
+    return i;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Compile Severity                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Compiles a user‑supplied severity map into override/escalation deltas.
+ *
+ * Each entry expresses a desired target severity for an event code. This
+ * helper compares the target against the baseline severity (“error”) and
+ * converts the difference into numeric levels suitable for the override and
+ * escalate policy transforms.
+ *
+ * Negative deltas become override levels; positive deltas become escalation
+ * levels. No interpretation occurs here—this function only computes the
+ * distance between severities.
+ */
+export function compileSeverityMap(severity) {
+    const override = {};
+    const escalate = {};
+    for (const [code, targetKind] of Object.entries(severity)) {
+        const targetIndex = severityIndex(targetKind);
+        const currentIndex = severityIndex('error'); // baseline assumption
+        const delta = targetIndex - currentIndex;
+        if (delta < 0)
+            override[code] = Math.abs(delta);
+        if (delta > 0)
+            escalate[code] = delta;
+    }
+    return { override, escalate };
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Decide Event                                                              *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Creates a `decide`‑phase event.
+ *
+ * Decision events are emitted after validation when policy logic evaluates
+ * severity, overrides, escalation, and boundary rules. This helper ensures
+ * all decision events share a consistent shape and metadata.
+ */
+export const decideEvent = (kind, code, path, message, userMessage, meta) => createEvent('decide', kind, code, path, message, userMessage, meta);
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Default Policy                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * The baseline policy used when no user configuration is provided.
+ *
+ * Moderate mode applies no automatic rejects, reviews, or severity transforms.
+ * Scan and analysis features are disabled, and no structural exceptions are
+ * granted. This preset defines Jane’s neutral, predictable behavior and serves
+ * as the foundation for all policy merging.
+ */
+export const defaultPolicy = {
+    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,
+    },
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Lax Policy                                                                *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * A permissive policy preset optimized for developer‑friendly behavior.
+ *
+ * Lax mode applies no rejects or reviews, downgrades all severities by one
+ * level via a wildcard override, disables scan and analysis features, and
+ * allows structural exceptions for bigint, map, and set. This preset favors
+ * flexibility and forgiveness during development and experimentation.
+ */
+export const laxPolicy = {
+    mode: 'lax',
+    scan: false,
+    decide: {
+        reject: [],
+        review: [],
+        override: {
+            '*': 1,
+        },
+        escalate: {},
+        warn: [],
+    },
+    analysis: {
+        diff: false,
+        explain: false,
+        replay: false,
+        telemetry: false,
+    },
+    exception: {
+        bigint: true,
+        map: true,
+        set: true,
+    },
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Boundary Strict Policy                                                    *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * A strict boundary preset that rejects on any issue.
+ *
+ * This configuration forces boundary acceptance to “strict”, applies a
+ * wildcard reject to treat every issue as fatal, and hides nothing from the
+ * event or issue streams. It provides the most conservative, compliance‑grade
+ * boundary behavior.
+ */
+export const boundaryPolicyStrict = {
+    accept: 'strict',
+    reject: ['*'], // any issue is a reject
+    review: [],
+    hideEvents: [], // show everything
+    hideIssues: [],
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Boundary Policy Default                                                   *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * The neutral boundary preset used when no boundary configuration is supplied.
+ *
+ * Default mode requires all fields to be accepted, applies no reject or review
+ * patterns, and hides nothing from the event or issue streams. It provides a
+ * transparent, assumption‑free baseline for boundary evaluation.
+ */
+export const boundaryPolicyDefault = {
+    accept: 'all',
+    ignore: [],
+    hideEvents: [],
+    hideIssues: [],
+    reject: [],
+    review: [],
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Boundary Policy Lax                                                       *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * A permissive boundary preset that accepts if any field succeeds.
+ *
+ * Lax mode ignores all boundary‑level events, hides both events and issues
+ * from the result, and applies no reject or review patterns. It provides a
+ * forgiving, low‑visibility boundary configuration suited for exploratory or
+ * developer‑focused workflows.
+ */
+export const boundaryPolicyLax = {
+    accept: 'any',
+    ignore: ['*'], // ignore all events
+    hideEvents: ['*'], // hide everything
+    hideIssues: ['*'],
+    reject: [],
+    review: [],
+};
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Strict Policy                                                             *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * A maximum‑scrutiny policy preset for safety‑critical pipelines.
+ *
+ * Strict mode enables scan, rejects high‑risk conditions outright, escalates
+ * all severities by one level, and requires review for large or complex
+ * structures. All analysis features are enabled, and no structural exceptions
+ * are granted. This preset enforces the most conservative, defensive behavior.
+ */
+export const strictPolicy = {
+    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,
+        },
+        override: {},
+        warn: [],
+    },
+    analysis: {
+        diff: true,
+        explain: true,
+        replay: true,
+        telemetry: true,
+    },
+    exception: {
+        bigint: false,
+        map: false,
+        set: false,
+    },
+};
+export function mergeBoundaryPolicies(base, ...overrides) {
+    let result = { ...(base ?? {}) };
+    for (const o of overrides) {
+        if (!o)
+            continue;
+        result = {
+            ...result,
+            // primitives (last one wins)
+            ...(o.accept !== undefined ? { accept: o.accept } : {}),
+            // arrays (concatenate)
+            ...(o.ignore !== undefined ? { ignore: [...(result.ignore ?? []), ...o.ignore] } : {}),
+            ...(o.hideEvents !== undefined
+                ? { hideEvents: [...(result.hideEvents ?? []), ...o.hideEvents] }
+                : {}),
+            ...(o.hideIssues !== undefined
+                ? { hideIssues: [...(result.hideIssues ?? []), ...o.hideIssues] }
+                : {}),
+            // ⭐ rules (concatenate)
+            ...(o.rules !== undefined ? { rules: [...(result.rules ?? []), ...o.rules] } : {}),
+            // nested objects (shallow merge)
+            ...(o.values !== undefined
+                ? { values: { ...(result.values ?? {}), ...o.values } }
+                : {}),
+            ...(o.metadata !== undefined
+                ? { metadata: { ...(result.metadata ?? {}), ...o.metadata } }
+                : {}),
+            // functions (last one wins)
+            ...(o.values?.transform !== undefined ? { transform: o.values?.transform } : {}),
+            ...(o.reducer !== undefined ? { reducer: o.reducer } : {}),
+        };
+    }
+    return result;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Normalize Policy                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Merges a base policy with user‑supplied input into a final, normalized policy.
+ *
+ * This function applies field‑by‑field overrides, compiles public severity
+ * settings into internal override/escalation maps, and merges reject/review/warn
+ * patterns in a predictable order. It preserves all unspecified fields from the
+ * base policy and never introduces defaults beyond those already present.
+ */
+export function normalizePolicy(base, input = {}) {
+    const next = {
+        ...base,
+    };
+    if (input.mode !== undefined) {
+        next.mode = input.mode;
+    }
+    if (input.analysis !== undefined) {
+        next.analysis = {
+            ...next.analysis,
+            ...input.analysis,
+        };
+    }
+    if (input.scan !== undefined) {
+        next.scan = input.scan;
+    }
+    if (input.exception !== undefined) {
+        next.exception = {
+            ...next.exception,
+            ...input.exception,
+        };
+    }
+    if (input.boundaryName !== undefined) {
+        next.boundaryName = input.boundaryName;
+    }
+    if (input.pipelineName !== undefined) {
+        next.pipelineName = input.pipelineName;
+    }
+    if (input.severity !== undefined) {
+        const compiled = compileSeverityMap(input.severity);
+        next.decide = {
+            ...(next.decide ?? {}),
+            override: {
+                ...(next.decide?.override ?? {}),
+                ...compiled.override,
+            },
+            escalate: {
+                ...(next.decide?.escalate ?? {}),
+                ...compiled.escalate,
+            },
+        };
+    }
+    if (input.reject !== undefined || input.review !== undefined || input.warn !== undefined) {
+        next.decide = {
+            ...(next.decide ?? {}),
+            reject: [...(next.decide?.reject ?? []), ...(input.reject ?? [])],
+            review: [...(next.decide?.review ?? []), ...(input.review ?? [])],
+            warn: [...(next.decide?.warn ?? []), ...(input.warn ?? [])],
+        };
+    }
+    if (input.decide !== undefined) {
+        next.decide = {
+            ...(next.decide ?? {}),
+            ...input.decide,
+        };
+    }
+    if (input.boundary !== undefined) {
+        next.boundary = {
+            ...(next.boundary ?? {}),
+            ...input.boundary,
+        };
+    }
+    return next;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Resolve Level                                                             *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Resolves a numeric level for an event code from a sparse lookup table.
+ *
+ * Exact matches take priority. If none exist, wildcard patterns in the table
+ * are tested in insertion order using their compiled regular expressions.
+ * Returns the matched level or `undefined` when no pattern applies.
+ */
+export function resolveLevel(code, table) {
+    if (code in table)
+        return table[code];
+    for (const pattern of Object.keys(table)) {
+        if (pattern.includes('*')) {
+            const re = getCompiledWildcard(pattern);
+            if (re.test(code)) {
+                return table[pattern];
+            }
+        }
+    }
+    return undefined;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Policy Decision                                                           *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Applies policy transforms to events and produces the final pipeline decision.
+ *
+ * This function reshapes events using override, escalation, and warn rules,
+ * derives issues from the resulting severities, and evaluates reject/review
+ * patterns according to the active policy mode. It returns the full pipeline
+ * result with shaped events, extracted issues, and a final accept/review/reject
+ * decision. No data is modified—only event interpretation changes.
+ */
+export function policyDecision(ctx, metadata) {
+    const { events, policy } = ctx;
+    let shapedEvents = [...events];
+    if (policy.decide?.override) {
+        shapedEvents = shapedEvents.map((ev) => {
+            const level = resolveLevel(ev.code, policy.decide.override);
+            return level === undefined ? ev : { ...ev, kind: applyOverride(ev.kind, level) };
+        });
+    }
+    if (policy.decide?.escalate) {
+        shapedEvents = shapedEvents.map((ev) => {
+            const level = resolveLevel(ev.code, policy.decide.escalate);
+            return level === undefined ? ev : { ...ev, kind: applyEscalate(ev.kind, level) };
+        });
+    }
+    if (policy.decide?.warn) {
+        shapedEvents = shapedEvents.map((ev) => {
+            if (matchesWildcard(ev.code, policy.decide.warn)) {
+                return { ...ev, kind: 'warn' };
+            }
+            return ev;
+        });
+    }
+    const shapedIssues = shapedEvents.filter((ev) => (ev.kind === 'error' || ev.kind === 'fatal') &&
+        typeof ev.code === 'string' &&
+        ev.code.trim().length > 0);
+    const rejectPatterns = policy.decide?.reject ?? [];
+    const reviewPatterns = policy.decide?.review ?? [];
+    let hasRejectEvents = false;
+    let hasReviewEvents = false;
+    for (const ev of shapedEvents) {
+        if (ev.kind === 'fatal') {
+            hasRejectEvents = true;
+            continue;
+        }
+        if (matchesWildcard(ev.code, rejectPatterns)) {
+            hasRejectEvents = true;
+            continue;
+        }
+        if (matchesWildcard(ev.code, reviewPatterns)) {
+            hasReviewEvents = true;
+        }
+    }
+    let decision;
+    switch (policy.mode) {
+        case 'strict':
+            decision =
+                hasRejectEvents || hasReviewEvents || shapedIssues.length > 0
+                    ? { code: 'reject', hasRejectEvents, hasReviewEvents }
+                    : { code: 'accept', hasRejectEvents, hasReviewEvents };
+            break;
+        case 'moderate':
+            decision = hasRejectEvents
+                ? { code: 'reject', hasRejectEvents, hasReviewEvents }
+                : hasReviewEvents
+                    ? { code: 'review', hasRejectEvents, hasReviewEvents }
+                    : { code: 'accept', hasRejectEvents, hasReviewEvents };
+            break;
+        case 'lax':
+        default:
+            decision = hasRejectEvents
+                ? { code: 'reject', hasRejectEvents, hasReviewEvents }
+                : { code: 'accept', hasRejectEvents, hasReviewEvents };
+            break;
+    }
+    return {
+        ...ctx,
+        events: shapedEvents,
+        issues: shapedIssues,
+        decision,
+        metadata,
+    };
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Resolve Policy                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Resolves the effective policy by merging defaults, explicit policy, and
+ * fluent‑API overrides.
+ *
+ * The default and explicit policies are combined first, then builder overrides
+ * are applied field‑by‑field with strict precedence. Only fields exposed to the
+ * fluent API are overrideable; all other structure is taken directly from the
+ * merged base. No inference or normalization occurs here—this function performs
+ * a final, literal merge for pipeline execution.
+ */
+export function resolvePolicy(defaultPolicy, janePolicy, overrides) {
+    const base = {
+        ...defaultPolicy,
+        ...(janePolicy ?? {}),
+    };
+    const o = overrides ?? {};
+    return {
+        boundaryName: base.boundaryName,
+        pipelineName: base.pipelineName,
+        mode: o.mode ?? base.mode,
+        boundary: base.boundary,
+        decide: base.decide,
+        analysis: {
+            diff: o.analysis?.diff ?? base.analysis?.diff,
+            explain: o.analysis?.explain ?? base.analysis?.explain,
+            replay: o.analysis?.replay ?? base.analysis?.replay,
+            telemetry: o.analysis?.telemetry ?? base.analysis?.telemetry,
+        },
+        scan: o.scan ?? base.scan,
+        exception: {
+            bigint: o.exception?.bigint ?? base.exception?.bigint,
+            map: o.exception?.map ?? base.exception?.map,
+            set: o.exception?.set ?? base.exception?.set,
+        },
+    };
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Severity Index                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Returns the numeric index for a severity kind.
+ *
+ * Event kinds are stored in a fixed ordered list. Unknown kinds fall back to
+ * index 0 to guarantee a safe, deterministic baseline for all severity math.
+ * No interpretation occurs here—this is a simple lookup with a fallback.
+ */
+export function severityIndex(kind) {
+    let idx = SEVERITY_ORDER.indexOf(kind);
+    if (idx === -1) {
+        idx = 0;
+    }
+    return idx;
+}
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Severity Order                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Fixed severity ladder from least to most severe.
+ *
+ * Policies, escalation math, and explain output rely on this exact ordering.
+ * Changing it is a breaking change because severity indices are used
+ * throughout the pipeline.
+ */
+export const SEVERITY_ORDER = ['info', 'warn', 'error', 'fatal'];

package/dist/core/common/utilities.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Common | Utilities
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shared low‑level helpers used across Jane’s core subsystems.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/**
+ * Performs structural deep equality on contained values.
+ *
+ * Primitives are compared by value, arrays and plain objects by shape and
+ * recursively by content, and Date objects by timestamp. Non‑plain objects
+ * are rejected. Cycle detection ensures safe comparison of recursive
+ * structures. This function defines the structural equality model used
+ * throughout Jane’s containment and diff logic.
+ */
+export declare function deepEqual(a: unknown, b: unknown, seen?: WeakMap<object, object>): boolean;
+/**
+ * Generates a unique run identifier.
+ *
+ * Uses `crypto.randomUUID` when available for strong, collision‑resistant IDs.
+ * Falls back to a timestamp + entropy string in environments without UUID
+ * support. Always returns a stable string suitable for pipeline metadata.
+ */
+export declare function generateRunId(): string;
+/**
+ * Checks for non‑null object values.
+ *
+ * Used as a minimal guard before structural checks. Functions, arrays, and
+ * plain objects all satisfy this test; it only excludes `null` and primitives.
+ */
+export declare function isObject(v: unknown): v is object;
+/**
+ * Checks whether a value is a strict plain object.
+ *
+ * Excludes arrays, null, and objects with custom or null prototypes. Only
+ * `{}`‑shaped values created by `Object` with `Object.prototype` qualify.
+ * Used wherever structural rules require predictable, JSON‑compatible objects.
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Checks whether a value is a JavaScript primitive.
+ *
+ * Includes all scalar literals plus `null` and `undefined`. Anything that is
+ * not an object and not a function qualifies. Used as a fast‑path guard before
+ * structural or container‑level checks.
+ */
+export declare function isPrimitive(value: unknown): value is string | number | boolean | bigint | symbol | null | undefined;
+/**
+ * Safely stringifies arbitrary values for use in messages and telemetry.
+ *
+ * Primitives are returned directly, strings are truncated with JSON quoting,
+ * functions and symbols are rendered as descriptive sentinels, and objects are
+ * JSON‑encoded with circular‑reference protection. Output is always bounded by
+ * `maxLength` to prevent runaway logs or unreadable diagnostics.
+ */
+export declare function safeStringify(value: unknown, maxLength?: number): string;