@clementine-solutions/jane-io 1.0.0 → 1.0.1

package/README.md

@@ -1 +1,132 @@
-# Meet Jane
+# Jane IO
+
+[![pipeline status](https://gitlab.com/clementine-solution/open-source/jane-io/badges/main/pipeline.svg)](https://gitlab.com/clementine-solution/open-source/jane-io/-/commits/main)
+[![coverage report](https://gitlab.com/clementine-solution/open-source/jane-io/badges/main/coverage.svg)](https://gitlab.com/clementine-solution/open-source/jane-io/-/commits/main)
+[![npm version](https://img.shields.io/npm/v/@clementine-solutions/jane-io.svg)](https://www.npmjs.com/package/@clementine-solutions/jane-io)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+> A clarity-first boundary system for shaping, validating, and transforming data with full introspection and policy control.
+
+Jane IO is a TypeScript-first data validation library that emphasizes **explicit design**, **runtime safety**, and **comprehensive observability**. Unlike traditional validators, Jane treats data processing as a multi-stage pipeline with policy-driven decision making.
+
+## Key Features
+
+- **Security-First**: Built-in protection against prototype pollution, circular references, and unsafe Unicode
+- **Type-Safe**: Full TypeScript coverage with immutable, composable APIs
+- **Observable**: Rich telemetry, diff tracking, and audit trails
+- **Configurable**: Policy-driven behavior with multiple validation modes
+- **Performant**: Lazy evaluation and efficient data structures
+- **Extensible**: Plugin architecture for custom validators and parsers
+
+## Installation
+
+```bash
+npm install @clementine-solutions/jane-io
+```
+
+```bash
+yarn add @clementine-solutions/jane-io
+```
+
+```bash
+pnpm add @clementine-solutions/jane-io
+```
+
+## Quick Start
+
+```typescript
+import { jane } from '@clementine-solutions/jane-io';
+
+// Simple validation
+const result = await jane.value("hello@example.com")
+  .parse("string")
+  .matches(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)
+  .run();
+
+if (result.ok) {
+  console.log("Valid email:", result.value);
+} else {
+  console.log("Issues:", result.issues);
+}
+```
+
+## Documentation
+
+- [Getting Started Guide](https://jane-io.com/docs/getting-started/introduction)
+- [Conceptual Overview](https://jane-io.clementine.solutions/concepts/introduction/)
+
+## Use Cases
+
+Jane excels at:
+
+- **API Data Validation**: Secure processing of external inputs.
+- **Configuration Management**: Structured config validation with audit trails.
+- **Data Transformation Pipelines**: ETL workflows with error tracking.
+- **Form Validation**: Complex multi-field validation scenarios.
+- **Data Import/Export**: Safe handling of structured data.
+
+## Architecture
+
+Jane's pipeline processes data through distinct stages:
+
+```mermaid
+graph LR
+    A[Raw Input] --> B[Contain]
+    B --> C[Scan]
+    C --> D[Normalize]
+    D --> E[Parse]
+    E --> F[Validate]
+    F --> G[Policy]
+    G --> H[Result]
+```
+
+- **Contain**: Structural safety and sanitization.
+- **Scan**: Analysis and hazard detection.
+- **Normalize**: Data hygiene and standardization.
+- **Parse**: Semantic interpretation.
+- **Validate**: Business rule enforcement.
+- **Policy**: Decision-making and observability.
+
+## Security Features
+
+- **Structural Hazard Detection**: Identifies circular references, excessive depth, and unsafe structures.
+- **Unicode Safety**: Detects and handles bidirectional control characters.
+- **Prototype Pollution Prevention**: Safe property access and key filtering.
+- **Containment Sentinels**: Safe representation of dangerous values.
+- **Immutable Processing**: No side effects or data mutation.
+
+## Observability
+
+Jane provides comprehensive introspection:
+
+```typescript
+const result = await jane.value(data)
+  .withDiff()      // Track changes
+  .withExplain()   // Explain decisions
+  .withReplay()    // Reconstruct transformations
+  .withTelemetry(sink) // Custom telemetry
+  .run();
+
+// Access detailed metadata
+console.log(result.metadata);
+console.log(result.diff);
+console.log(result.explain);
+```
+
+## License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+Jane IO is built with care for the developer experience and runtime safety. Special thanks to the TypeScript community and the broader JavaScript ecosystem for inspiration and tooling.
+
+## Support
+
+- **Issues**: [GitLab Issues](https://gitlab.com/clementine-solution/open-source/jane-io/issues)
+- **Discussions**: [GitLab Discussions](https://gitlab.com/clementine-solution/open-source/jane-io/discussions)
+- **Documentation**: [Jane IO Docs](https://jane-io.com/)
+
+---
+
+**Jane IO** - Data validation with clarity and confidence.

package/dist/core/analysis/diff.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Diff
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Structural diff utilities used to compare safe and
+ *                  normalized values.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { DiffEntry, DiffFunction, FieldPath, JsonValue, PipelineBuilder } from '../shapes';
+/**
+ * Computes a structural diff between two JSON‑compatible values.
+ *
+ * Delegates all traversal to `walkDiff`, collecting every change into a flat
+ * list of diff entries rooted at the top‑level path. Always returns a stable
+ * `{ entries }` object with no filtering or interpretation.
+ */
+export declare const diff: DiffFunction;
+/**
+ * Recursively walks two JSON‑compatible values and records structural changes.
+ *
+ * Compares primitives, arrays, and plain objects by shape and content, emitting
+ * diff entries at each divergent path. Keys and indices are traversed in a
+ * stable order, and non‑object mismatches are treated as direct value changes.
+ * All entries are appended to `out`; no filtering or interpretation occurs here.
+ */
+export declare function walkDiff(before: JsonValue | undefined, after: JsonValue | undefined, path: FieldPath, out: DiffEntry[]): void;
+/**
+ * Runs the pipeline and returns its computed diff.
+ *
+ * Delegates execution to the provided builder and exposes only the diff
+ * portion of the result. No additional processing or filtering occurs here.
+ */
+export declare function runDiff<T>(builder: PipelineBuilder): Promise<import("../shapes").DiffResult | undefined>;

package/dist/core/analysis/explain.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Explain
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Builds a human‑readable narrative of all pipeline events in
+ *                  order.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ExplainFunction, PipelineBuilder } from '../shapes';
+/**
+ * Builds a linear explanation of all pipeline events.
+ *
+ * Emits scan hazards, normalization events, diff entries, parse changes, and
+ * validation errors in pipeline order. Each event is mapped to a stable
+ * ExplainStep with its path, stage, kind, code, and message. No filtering or
+ * interpretation occurs; this is a direct narrative of what the pipeline saw.
+ */
+export declare const explain: ExplainFunction;
+/**
+ * Formats a value for human‑readable explain output.
+ *
+ * Produces stable string representations for primitives and falls back to
+ * compact JSON for objects. Never throws; errors during formatting degrade
+ * gracefully to `String(value)`.
+ */
+export declare function format(value: unknown): string;
+/**
+ * Runs the pipeline and returns its explain output.
+ *
+ * Delegates execution to the provided builder and exposes only the explain
+ * portion of the result. No additional processing or reshaping occurs here.
+ */
+export declare function runExplain<T>(builder: PipelineBuilder): Promise<import("../shapes").ExplainResult | undefined>;

package/dist/core/analysis/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Re‑exports the public Analysis modules (Diff, Explain,
+ *                  Replay, Telemetry).
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export { diff, walkDiff, runDiff } from './diff';
+export { explain, format, runExplain } from './explain';
+export { applyEntry, replay, runReplay } from './replay';
+export { runTelemetry, telemetry } from './telemetry';

package/dist/core/analysis/replay.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Replay
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Reconstructs intermediate states by applying diff entries
+ *                  in order.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { DiffEntry, InternalJsonValue, PipelineBuilder, ReplayFunction } from '../shapes';
+/**
+ * Applies a single diff entry to an internal JSON value.
+ *
+ * Clones the current state, then sets or clears the value at the entry’s path
+ * according to its kind. Used by Replay to advance state one change at a time.
+ * Never mutates the original state.
+ */
+export declare function applyEntry(state: InternalJsonValue, entry: DiffEntry): InternalJsonValue;
+/**
+ * Replays a diff step‑by‑step to reconstruct intermediate states.
+ *
+ * Clones the initial value, applies each diff entry in order, and records a
+ * snapshot after every application. Produces a stable sequence of ReplayStep
+ * objects with index, entry, and resulting state. Never mutates inputs.
+ */
+export declare const replay: ReplayFunction;
+/**
+ * Runs the pipeline and returns its replay output.
+ *
+ * Delegates execution to the provided builder and exposes only the replay
+ * portion of the result. No additional processing or transformation occurs.
+ */
+export declare function runReplay<T>(builder: PipelineBuilder): Promise<import("../shapes").ReplayResult | undefined>;

package/dist/core/analysis/telemetry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Analysis | Telemetry
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Emits structured records for each pipeline stage for
+ *                  auditing and observability.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { PipelineBuilder, PipelineResult, TelemetryContext, TelemetryResult, TelemetrySink } from '../shapes';
+/**
+ * Collects flat telemetry records for each pipeline stage.
+ *
+ * Emits one record per stage with boundary, pipeline, timestamp, and the
+ * stage‑specific payload (events, diff, explain, replay). Stages are reported
+ * in pipeline order, and a final `decide` record captures the policy outcome.
+ * No aggregation, filtering, or interpretation occurs here.
+ */
+export declare function telemetry<T>(ctx: TelemetryContext<T>): TelemetryResult;
+/**
+ * Runs the pipeline and emits telemetry if enabled by policy.
+ *
+ * Delegates execution to the builder, collects stage records through the
+ * telemetry helper, and forwards them to the provided sink. Returns the full
+ * pipeline result unchanged.
+ */
+export declare function runTelemetry<T>(builder: PipelineBuilder, sink: TelemetrySink): Promise<PipelineResult<T>>;

package/dist/core/boundary-rules/at-most-one.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | At Most One
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures that no more than one of the specified fields is
+ *                  accepted. If multiple fields are present, a boundary error
+ *                  is emitted.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { BoundaryRule } from '../shapes';
+/**
+ * Ensures that at most one of the specified fields is accepted. If more than
+ * one field is present, a boundary‑level error is emitted.
+ */
+export declare function atMostOne(...keys: string[]): BoundaryRule;

package/dist/core/boundary-rules/conditionally-required.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Conditionally Required
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Requires a set of fields when a controlling field matches a
+ *                  specific value. Missing or rejected fields trigger
+ *                  boundary‑level errors.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { BoundaryRule } from '../shapes';
+/**
+ * Requires a set of fields when a controlling field matches a specific value.
+ * If the condition is met and any required field is missing or rejected, an
+ * error is emitted for each missing field.
+ */
+export declare function conditionallyRequired(typeKey: string, typeValue: unknown, ...required: string[]): BoundaryRule;

package/dist/core/boundary-rules/date-range.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Date Range
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Validates that a start and end date form a proper
+ *                  chronological range. Emits an error when the start occurs
+ *                  after the end.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { BoundaryRule } from '../shapes';
+/**
+ * Validates that a start/end date pair forms a proper chronological range.
+ * Emits an error when both fields are dates and the start occurs after the end.
+ */
+export declare function dateRange(startKey: string, endKey: string): BoundaryRule;

package/dist/core/boundary-rules/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ----------------------------------------------------------------------------
+ *  Boundary Rules | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Re‑exports shared boundary rules to provide a stable,
+ *                  minimal entry point for internal consumers. This file
+ *                  exposes no logic of its own.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export { atMostOne } from './at-most-one';
+export { conditionallyRequired } from './conditionally-required';
+export { dateRange } from './date-range';
+export { mutuallyExclusive } from './mutually-exclusive';
+export { noUnknownFields } from './no-unknown-fields';
+export { requireAll } from './require-all';
+export { requireOne } from './require-one';

package/dist/core/boundary-rules/mutually-exclusive.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Mutually Exclusive
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Enforces that two fields cannot both be accepted. If both
+ *                  appear, a mutual‑exclusion boundary error is produced.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { BoundaryRule } from '../shapes';
+/**
+ * Enforces mutual exclusion between two fields. If both fields are accepted,
+ * a boundary‑level error is emitted indicating the conflict.
+ */
+export declare function mutuallyExclusive(a: string, b: string): BoundaryRule;

package/dist/core/boundary-rules/no-unknown-fields.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | No Unknown Fields
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Ensures that only explicitly allowed fields appear in the
+ *                  boundary input. Any unknown key results in a boundary error.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { BoundaryRule } from '../shapes';
+/**
+ * Ensures that only the explicitly allowed fields appear in the boundary
+ * input. Any field not listed is treated as an unknown key and produces a
+ * boundary‑level error.
+ */
+export declare function noUnknownFields(...allowed: string[]): BoundaryRule;

package/dist/core/boundary-rules/require-all.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Require All
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Requires that all specified fields be present and accepted.
+ *                  Missing or rejected fields each produce a boundary error.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { BoundaryRule } from '../shapes';
+/**
+ * Requires that all specified fields be present and accepted. Any missing or
+ * rejected field results in a boundary‑level error for that key.
+ */
+export declare function requireAll(...keys: string[]): BoundaryRule;

package/dist/core/boundary-rules/require-one.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Boundary Rules | Require One
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Requires that at least one of the specified fields be
+ *                  accepted. If none are present, a single boundary error is
+ *                  emitted.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { BoundaryRule } from '../shapes';
+/**
+ * Requires that at least one of the specified fields be present and accepted.
+ * If none are provided, a single boundary‑level error is emitted.
+ */
+export declare function requireOne(...keys: string[]): BoundaryRule;

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

@@ -0,0 +1,37 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Common | Events
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shared event types, factories, and helpers used across all
+ *                  pipeline stages. These modules define how Jane records and
+ *                  communicates observable facts during execution.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { EventCode, EventKind, FieldPath, JaneEvent, PipelinePhase } from '../shapes';
+/**
+ * Creates a frozen JaneEvent with consistent metadata.
+ *
+ * This factory centralizes event construction so all stages emit the same
+ * shape: stable identifiers, optional context, and a metadata block that
+ * tooling can rely on. Callers provide only the facts; the factory attaches
+ * timestamps and prepares the object for safe sharing across the pipeline.
+ *
+ * The returned event is immutable to prevent accidental mutation during
+ * scan, parse, normalize, validate, boundary, or policy execution.
+ */
+export declare function createEvent(phase: PipelinePhase, kind: EventKind, code: EventCode, path?: FieldPath, message?: string, userMessage?: string, meta?: Record<string, unknown>): JaneEvent;
+/**
+ * Structural type guard for JaneEvent.
+ *
+ * This check verifies that a value has the minimal shape required for an
+ * event: a valid phase, kind, code, and optional context fields. It does not
+ * validate semantics or metadata—only that the object is structurally safe to
+ * treat as a JaneEvent inside the pipeline.
+ *
+ * The guard is intentionally strict and literal. It accepts only the phases
+ * and kinds defined here, ensuring that stray or misspelled values cannot
+ * enter policy, explain, or replay logic.
+ */
+export declare function isJaneEvent(value: unknown): value is JaneEvent;

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

@@ -0,0 +1,151 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Common | Fluent
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Internal helpers that build Jane’s fluent API surface.
+ *                  These modules attach parser and validator methods and wrap
+ *                  PipelineBuilder instances into the public pipeline.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { BoundaryResult, FieldPath, JaneBoundaryResult, JaneResult, PipelineBuilder, PipelineResult, PublicPipeline } from '../shapes';
+import type { PolicyInput } from '../shapes/policy';
+/**
+ * Internal hook used to associate a PipelineBuilder with a PublicPipeline.
+ *
+ * The unique symbol prevents accidental collisions with user code and keeps
+ * the builder hidden from the public API. Only internal helpers read or
+ * write this property, and it is never surfaced to consumers.
+ *
+ * PublicPipelineInternal exists solely to give internal code a typed way to
+ * access the builder without widening the public interface.
+ */
+declare const BUILDER: unique symbol;
+export type PublicPipelineInternal = PublicPipeline & {
+    [BUILDER]?: PipelineBuilder;
+};
+/**
+ * Attaches fluent validator methods directly to a PipelineBuilder.
+ *
+ * Each validator in the registry becomes a fluent method on the builder.
+ * Calls record the validator request on the current builder and return the
+ * same builder instance, allowing internal code to compose validation steps
+ * without wrapping or producing a new public pipeline.
+ *
+ * Methods are non‑enumerable and immutable so the builder’s shape stays
+ * stable and free of accidental overrides.
+ */
+export declare function attachFluentValidators(builder: PipelineBuilder): void;
+/**
+ * Attaches fluent parser methods directly to a PipelineBuilder.
+ *
+ * Each parser in the registry becomes a fluent method on the builder. Calls
+ * record the parser request on the current builder and return the same
+ * builder instance, allowing internal code to compose parse steps without
+ * wrapping or producing a new public pipeline.
+ *
+ * Methods are non‑enumerable and immutable so the builder’s shape stays
+ * stable and free of accidental overrides.
+ */
+export declare function attachFluentParsers(builder: PipelineBuilder): void;
+/**
+ * Creates a policy‑aware Jane instance.
+ *
+ * Normalizes the base policy, wraps pipeline builders with the public API,
+ * and wires in analysis features (diff, explain, replay, telemetry) according
+ * to the active policy. Each fluent call returns a new wrapped builder, keeping
+ * the pipeline immutable and policy‑driven end‑to‑end.
+ */
+export declare function createJane(basePolicyInput: PolicyInput): {
+    value(raw: unknown, path?: FieldPath, options?: {
+        inputName?: string;
+    }): PublicPipeline;
+    boundary<TShape extends Record<string, PublicPipeline>>(shape: TShape): Promise<{
+        policy: import("../shapes").Policy;
+        ok: boolean;
+        issues?: readonly import("../shapes").JaneEvent[];
+        events?: readonly import("../shapes").JaneEvent[];
+        values?: Record<string, unknown> | undefined;
+        fields: Record<string, JaneResult<unknown>>;
+        metadata: {
+            runId?: string;
+            startedAt?: string;
+            finishedAt?: string;
+            durationMs?: number;
+            fields: Record<string, import("../shapes").FieldMetadata>;
+        };
+    }>;
+    withPolicy(input: PolicyInput): /*elided*/ any;
+    strictBoundary<TShape extends Record<string, PublicPipeline>>(shape: TShape): Promise<{
+        policy: import("../shapes").Policy;
+        ok: boolean;
+        issues?: readonly import("../shapes").JaneEvent[];
+        events?: readonly import("../shapes").JaneEvent[];
+        values?: Record<string, unknown> | undefined;
+        fields: Record<string, JaneResult<unknown>>;
+        metadata: {
+            runId?: string;
+            startedAt?: string;
+            finishedAt?: string;
+            durationMs?: number;
+            fields: Record<string, import("../shapes").FieldMetadata>;
+        };
+    }>;
+    laxBoundary<TShape extends Record<string, PublicPipeline>>(shape: TShape): Promise<{
+        policy: import("../shapes").Policy;
+        ok: boolean;
+        issues?: readonly import("../shapes").JaneEvent[];
+        events?: readonly import("../shapes").JaneEvent[];
+        values?: Record<string, unknown> | undefined;
+        fields: Record<string, JaneResult<unknown>>;
+        metadata: {
+            runId?: string;
+            startedAt?: string;
+            finishedAt?: string;
+            durationMs?: number;
+            fields: Record<string, import("../shapes").FieldMetadata>;
+        };
+    }>;
+    defaultBoundary<TShape extends Record<string, PublicPipeline>>(shape: TShape): Promise<{
+        policy: import("../shapes").Policy;
+        ok: boolean;
+        issues?: readonly import("../shapes").JaneEvent[];
+        events?: readonly import("../shapes").JaneEvent[];
+        values?: Record<string, unknown> | undefined;
+        fields: Record<string, JaneResult<unknown>>;
+        metadata: {
+            runId?: string;
+            startedAt?: string;
+            finishedAt?: string;
+            durationMs?: number;
+            fields: Record<string, import("../shapes").FieldMetadata>;
+        };
+    }>;
+};
+/**
+ * Creates a Jane instance with a normalized base policy and the full fluent API.
+ *
+ * The factory wraps a PipelineBuilder and exposes a stable, user‑facing
+ * pipeline surface. Each fluent call produces a new wrapped builder, while
+ * root‑level helpers (value, boundary, withPolicy) create new Jane instances
+ * with merged policy state.
+ *
+ * The wrapper isolates internal builder mechanics from consumers, attaches
+ * parser and validator methods from the registry, and ensures that telemetry,
+ * diff, explain, replay, and boundary behavior all flow through a consistent
+ * entry point. All policy resolution happens here so contributors can reason
+ * about effective behavior without tracing through individual pipeline steps.
+ */
+export declare function toJaneResult<T>(r: PipelineResult<T>): JaneResult<T>;
+/**
+ * Converts an internal BoundaryResult and its field-level PipelineResults
+ * into the public JaneBoundaryResult shape.
+ *
+ * Each pipeline result is first converted to a JaneResult, then assembled
+ * alongside the boundary’s own decision, issues, events, values, and metadata.
+ * No interpretation or rewriting occurs here—this function preserves the
+ * boundary runner’s output exactly while projecting it into the public API.
+ */
+export declare function toJaneBoundaryResult(boundary: BoundaryResult, pipelines: Record<string, PipelineResult<unknown>>): JaneBoundaryResult<Record<string, unknown>>;
+export {};

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

@@ -0,0 +1,16 @@
+/**
+ * ----------------------------------------------------------------------------
+ *  Common | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Re‑exports shared common modules to provide a stable,
+ *                  minimal entry point for internal consumers. This file
+ *                  exposes no logic of its own.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export { createEvent, isJaneEvent } from './events';
+export { attachFluentParsers, attachFluentValidators, createJane, toJaneBoundaryResult, toJaneResult, } from './fluent';
+export { applyEscalate, applyOverride, boundaryPolicyDefault, boundaryPolicyLax, boundaryPolicyStrict, clampSeverityIndex, compileSeverityMap, decideEvent, defaultPolicy, laxPolicy, normalizePolicy, mergeBoundaryPolicies, policyDecision, resolveLevel, resolvePolicy, severityIndex, SEVERITY_ORDER, strictPolicy, } from './policy';
+export { deepEqual, generateRunId, isObject, isPlainObject, isPrimitive, safeStringify, } from './utilities';
+export { compileWildcard, getCompiledWildcard, matchesWildcard } from './wildcard';