@clementine-solutions/jane-io 1.0.0 → 1.0.2

package/dist/core/scanners/string/string-is-long.js

@@ -0,0 +1,32 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Scanners | String Is Long
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Warns when text exceeds a conservative length threshold,
+ *                  highlighting oversized or potentially adversarial input.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import { scanEvent } from '../../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Warns when a string exceeds a conservative maximum length.
+ *
+ * Extremely long text can signal malformed payloads, denial‑of‑service
+ * attempts, or unbounded user input. This rule surfaces oversized strings
+ * early so containment and validation layers can respond safely.
+ */
+export const stringIsLong = (raw, path) => {
+    if (typeof raw !== 'string')
+        return [];
+    const max = 10_000;
+    if (raw.length > max) {
+        return [
+            scanEvent('warn', 'string.is.long', path, `String length ${raw.length} exceeds safe threshold ${max}.`, 'This text is very long.', { length: raw.length, max }),
+        ];
+    }
+    return [];
+};

package/dist/core/scanners/unknown/unknown-not-scannable.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Scanners | Unknown Not Scannable
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Flags values whose structural type cannot be determined,
+ *                  surfacing opaque or unpredictable inputs that cannot be
+ *                  scanned safely.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { ScanRule } from '../../shapes';
+/**
+ * Flags values whose structural type cannot be determined.
+ *
+ * Unknown values have no predictable shape, traversal semantics, or guarantees
+ * about behavior. They may be callable, throw on access, or vary across realms.
+ * This rule surfaces opaque inputs early so containment, validation, and policy
+ * layers can decide how to handle them safely.
+ */
+export declare const unknownNotScannable: ScanRule;

package/dist/core/scanners/unknown/unknown-not-scannable.js

@@ -0,0 +1,34 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Scanners | Unknown Not Scannable
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Flags values whose structural type cannot be determined,
+ *                  surfacing opaque or unpredictable inputs that cannot be
+ *                  scanned safely.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Internal Modules                                                          *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+import { detectStructuralType } from '../../../core/pipeline';
+import { scanEvent } from '../../pipeline';
+/* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— *\
+|* Implementation                                                            *|
+\* ——— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ————— * ——— */
+/**
+ * Flags values whose structural type cannot be determined.
+ *
+ * Unknown values have no predictable shape, traversal semantics, or guarantees
+ * about behavior. They may be callable, throw on access, or vary across realms.
+ * This rule surfaces opaque inputs early so containment, validation, and policy
+ * layers can decide how to handle them safely.
+ */
+export const unknownNotScannable = (raw, path) => {
+    if (detectStructuralType(raw) !== 'unknown')
+        return [];
+    return [
+        scanEvent('warn', 'unknown.not.scannable', path, 'Value has an unknown structural type and cannot be scanned safely.', 'This value cannot be scanned safely.', { value: raw }),
+    ];
+};

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

@@ -0,0 +1,239 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Analysis
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define the structures used for diff, explain,
+ *                  replay, and telemetry analysis.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { FieldPath, JaneEvent, PipelineResult } from '.';
+/**
+ * Represents a single structural difference between two values.
+ *
+ * Captures the field path, the nature of the change, and the before/after
+ * snapshots used for diff, explain, and replay analysis.
+ */
+export interface DiffEntry {
+    readonly path: FieldPath;
+    readonly kind: 'added' | 'removed' | 'changed';
+    readonly before?: unknown;
+    readonly after?: unknown;
+}
+/**
+ * Computes the structural differences between two values.
+ *
+ * Produces a diff result describing all added, removed, and changed
+ * paths for downstream analysis.
+ */
+export type DiffFunction = (before: unknown, after: unknown) => DiffResult;
+/**
+ * The complete set of structural differences between two values.
+ *
+ * Contains the ordered list of diff entries used by explain and replay
+ * to interpret or reconstruct changes.
+ */
+export interface DiffResult {
+    readonly entries: readonly DiffEntry[];
+}
+/**
+ * Produces a narrative explanation of pipeline behavior.
+ *
+ * Consumes events from each stage and an optional diff to generate a
+ * step‑wise account of hazards, changes, and errors.
+ */
+export type ExplainFunction = (input: {
+    scanEvents: readonly JaneEvent[];
+    normalizationEvents: readonly JaneEvent[];
+    parseEvents: readonly JaneEvent[];
+    validationEvents: readonly JaneEvent[];
+    diff?: DiffResult;
+}) => ExplainResult;
+/**
+ * A structured narrative describing how the pipeline processed a value.
+ *
+ * Contains the ordered explanation steps that summarize hazards,
+ * changes, and errors across all stages.
+ */
+export interface ExplainResult {
+    readonly steps: readonly ExplainStep[];
+}
+/**
+ * A single explanatory step in the pipeline narrative.
+ *
+ * Identifies the stage, kind, and code involved, with optional path and
+ * message to clarify the meaning of the event.
+ */
+export interface ExplainStep {
+    readonly path?: FieldPath;
+    readonly stage: 'scan' | 'normalize' | 'parse' | 'validate' | 'decide';
+    readonly kind: 'hazard' | 'change' | 'error';
+    readonly code: string;
+    readonly message?: string;
+}
+/**
+ * Reconstructs intermediate states by replaying diff entries.
+ *
+ * Applies each diff step in order to show how the value evolved from
+ * its original form to the final normalized or parsed state.
+ */
+export type ReplayFunction = (input: {
+    before: unknown;
+    diff: readonly DiffEntry[];
+}) => ReplayResult;
+/**
+ * The full sequence of replayed states derived from a diff.
+ *
+ * Contains each intermediate step, allowing contributors to inspect how
+ * structural changes accumulated over time.
+ */
+export interface ReplayResult {
+    readonly steps: readonly ReplayStep[];
+}
+/**
+ * A single step in the replay sequence.
+ *
+ * Records the diff entry applied and the resulting state after that
+ * change, enabling step‑wise reconstruction of value evolution.
+ */
+export interface ReplayStep {
+    readonly index: number;
+    readonly entry: DiffEntry;
+    readonly state: unknown;
+}
+/**
+ * Receives the emitted telemetry records for a pipeline run.
+ *
+ * Allows callers to collect, store, or forward stage‑level telemetry
+ * without coupling the pipeline to any specific transport or backend.
+ */
+export type TelemetrySink = (records: readonly TelemetryRecord[]) => void;
+/**
+ * Enumerates all pipeline stages that can emit telemetry.
+ *
+ * Used to tag records with their originating phase for analysis,
+ * auditing, and observability.
+ */
+export type TelemetryStage = 'scan' | 'normalize' | 'validate' | 'parse' | 'diff' | 'explain' | 'replay' | 'decide';
+/**
+ * Common metadata shared by all telemetry records.
+ *
+ * Identifies the boundary, pipeline, timestamp, and originating stage,
+ * forming the structural foundation for all telemetry entries.
+ */
+export interface TelemetryRecordBase {
+    readonly boundary: string;
+    readonly pipeline: string;
+    readonly timestamp: string;
+    readonly stage: TelemetryStage;
+}
+/**
+ * Telemetry emitted from the scan stage.
+ *
+ * Captures all scan events, including hazards, errors, and structural
+ * findings discovered before normalization or parsing.
+ */
+export interface TelemetryScanRecord extends TelemetryRecordBase {
+    readonly stage: 'scan';
+    readonly events: readonly JaneEvent[];
+}
+/**
+ * Telemetry emitted from the normalization stage.
+ *
+ * Records all normalization events that shaped the safe or adjusted
+ * value prior to parsing or validation.
+ */
+export interface TelemetryNormalizeRecord extends TelemetryRecordBase {
+    readonly stage: 'normalize';
+    readonly events: readonly JaneEvent[];
+}
+/**
+ * Telemetry emitted from the parse stage.
+ *
+ * Captures parser‑driven transformations and any associated events
+ * produced while interpreting the normalized value.
+ */
+export interface TelemetryParseRecord extends TelemetryRecordBase {
+    readonly stage: 'parse';
+    readonly events: readonly JaneEvent[];
+}
+/**
+ * Telemetry emitted from the validation stage.
+ *
+ * Records all validation events, including rule outcomes and any
+ * issues that contribute to the final decision.
+ */
+export interface TelemetryValidateRecord extends TelemetryRecordBase {
+    readonly stage: 'validate';
+    readonly events: readonly JaneEvent[];
+}
+/**
+ * Telemetry emitted from the diff stage.
+ *
+ * Contains the structural differences between the safe and normalized
+ * values, supporting explain and replay analysis.
+ */
+export interface TelemetryDiffRecord extends TelemetryRecordBase {
+    readonly stage: 'diff';
+    readonly diff: DiffResult;
+}
+/**
+ * Telemetry emitted from the explain stage.
+ *
+ * Provides the narrative explanation of how the pipeline processed the
+ * value across all stages.
+ */
+export interface TelemetryExplainRecord extends TelemetryRecordBase {
+    readonly stage: 'explain';
+    readonly explain: ExplainResult;
+}
+/**
+ * Telemetry emitted from the replay stage.
+ *
+ * Contains the reconstructed intermediate states derived from applying
+ * diff entries step‑by‑step.
+ */
+export interface TelemetryReplayRecord extends TelemetryRecordBase {
+    readonly stage: 'replay';
+    readonly replay: ReplayResult;
+}
+/**
+ * Telemetry emitted from the decision stage.
+ *
+ * Records the final decision code, policy mode, and total event count,
+ * providing a compact summary of the pipeline outcome.
+ */
+export interface TelemetryDecideRecord extends TelemetryRecordBase {
+    readonly stage: 'decide';
+    readonly decision: string;
+    readonly mode: string;
+    readonly eventCount: number;
+}
+/**
+ * Union of all telemetry record types.
+ *
+ * Represents any stage‑specific telemetry entry emitted during a
+ * pipeline run.
+ */
+export type TelemetryRecord = TelemetryScanRecord | TelemetryNormalizeRecord | TelemetryParseRecord | TelemetryValidateRecord | TelemetryDiffRecord | TelemetryExplainRecord | TelemetryReplayRecord | TelemetryDecideRecord;
+/**
+ * Container for all telemetry emitted during a pipeline run.
+ *
+ * Provides the complete ordered sequence of stage‑level records for
+ * analysis, debugging, or external reporting.
+ */
+export interface TelemetryResult {
+    readonly records: readonly TelemetryRecord[];
+}
+/**
+ * Context passed to the telemetry generator.
+ *
+ * Supplies the boundary and pipeline names along with the full pipeline
+ * result, enabling stage‑aware telemetry construction.
+ */
+export interface TelemetryContext<T> {
+    readonly boundaryName: string;
+    readonly pipelineName: string;
+    readonly result: PipelineResult<T>;
+}

package/dist/core/shapes/analysis.js

@@ -0,0 +1,11 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Analysis
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define the structures used for diff, explain,
+ *                  replay, and telemetry analysis.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};

package/dist/core/shapes/boundary.d.ts

@@ -0,0 +1,126 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Boundary
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define the structure, policy surface, and
+ *                  results of boundary evaluation.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { EventCode, FieldMetadata, JaneEvent, PipelineResult, Policy } from '.';
+/**
+ * Context passed to boundary rules and reducers.
+ * Provides the evaluated fields, aggregated events and issues, resolved
+ * values, and the active policy for making boundary‑level decisions.
+ */
+export interface BoundaryContext {
+    readonly policy: Policy;
+    readonly fields: Record<string, PipelineResult<unknown>>;
+    readonly issues: readonly JaneEvent[];
+    readonly events: readonly JaneEvent[];
+    readonly values: Record<string, unknown>;
+}
+/**
+ * Configuration surface for boundary‑level decision logic.
+ * Defines reject and review patterns, severity transforms, visibility
+ * filters, acceptance modes, value and metadata shaping, and optional
+ * rule and reducer hooks.
+ */
+export interface BoundaryDecideConfig {
+    readonly reject?: readonly string[];
+    readonly review?: readonly string[];
+    readonly override?: Readonly<Partial<Record<EventCode, number>>>;
+    readonly escalate?: Readonly<Partial<Record<EventCode, number>>>;
+    readonly ignore?: readonly string[];
+    readonly hideEvents?: readonly string[];
+    readonly hideIssues?: readonly string[];
+    readonly accept?: 'all' | 'any' | 'strict' | 'partial';
+    readonly values?: {
+        readonly includeRejected?: boolean;
+        readonly includeUndefined?: boolean;
+        readonly transform?: (values: Record<string, unknown>) => Record<string, unknown>;
+    };
+    readonly metadata?: {
+        readonly includeFields?: boolean;
+        readonly includeTimestamps?: boolean;
+        readonly includeRunId?: boolean;
+    };
+    rules?: BoundaryRule[];
+    readonly reducer?: BoundaryReducer;
+}
+/**
+ * A reducer hook that can refine or override the boundary decision.
+ * Receives the full boundary context and may return a complete or
+ * partial decision, or perform side effects without returning a value.
+ */
+export type BoundaryReducer = (ctx: BoundaryContext) => BoundaryDecision | Partial<BoundaryDecision> | void;
+/**
+ * The final decision produced by boundary evaluation.
+ * Indicates acceptance and may override values, metadata, issues, or
+ * events before the result is returned to the caller.
+ */
+export interface BoundaryDecision {
+    readonly ok: boolean;
+    readonly values?: Record<string, unknown>;
+    readonly metadata?: BoundaryMetadata;
+    readonly issues?: readonly JaneEvent[];
+    readonly events?: readonly JaneEvent[];
+}
+/**
+ * Input to a boundary evaluation.
+ * Supplies the evaluated field results and an optional policy to guide
+ * decision logic and shaping.
+ */
+export interface BoundaryInput {
+    readonly policy?: Policy;
+    readonly fields: Record<string, PipelineResult<unknown>>;
+}
+/**
+ * Execution‑level metadata for a boundary evaluation.
+ * Records timing, identifiers, field metadata, naming, and enabled
+ * analysis features for auditing and reporting.
+ */
+export interface BoundaryMetadata {
+    readonly runId?: string;
+    readonly startedAt?: string;
+    readonly finishedAt?: string;
+    readonly durationMs?: number;
+    readonly fields: Record<string, FieldMetadata>;
+    readonly boundaryName?: string;
+    readonly pipelineName?: string;
+    readonly analysis?: {
+        readonly diff?: boolean;
+        readonly explain?: boolean;
+        readonly replay?: boolean;
+        readonly telemetry?: boolean;
+    };
+}
+/**
+ * A boundary‑level rule that can emit additional events or issues.
+ * Operates on the full boundary context and may refine the decision
+ * indirectly through its outputs.
+ */
+export type BoundaryRule = (ctx: BoundaryContext) => BoundaryRuleResult | Promise<BoundaryRuleResult>;
+/**
+ * Output produced by a boundary rule.
+ * Allows rules to contribute events or issues that participate in the
+ * final boundary decision.
+ */
+export interface BoundaryRuleResult {
+    events?: JaneEvent[];
+    issues?: JaneEvent[];
+}
+/**
+ * The complete result of boundary evaluation.
+ * Contains the final acceptance state, shaped values, aggregated field
+ * results, emitted events and issues, and execution metadata.
+ */
+export interface BoundaryResult {
+    ok: boolean;
+    issues?: readonly JaneEvent[];
+    events?: readonly JaneEvent[];
+    values?: Record<string, unknown>;
+    fields: Record<string, PipelineResult<unknown>>;
+    metadata: BoundaryMetadata;
+}

package/dist/core/shapes/boundary.js

@@ -0,0 +1,11 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Boundary
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Shapes that define the structure, policy surface, and
+ *                  results of boundary evaluation.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};

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

@@ -0,0 +1,83 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Event
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Structured observations emitted by each pipeline phase.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+import type { FieldPath, PipelinePhase } from '../shapes';
+/**
+ * Canonical list of all event codes emitted anywhere in the pipeline.
+ *
+ * Each literal represents a stable, public identifier used by scan, parse,
+ * normalize, validate, boundary, and policy stages. Codes are intentionally
+ * explicit and human‑readable so contributors can reason about behavior,
+ * write policies, and interpret explain/diff/replay output without guessing.
+ *
+ * This union is closed: adding or removing codes is a versioned change.
+ * Downstream tools rely on these strings for matching, grouping, and
+ * telemetry, so edits should be deliberate and documented.
+ */
+export type EventCode = 'array.has.empty-strings' | 'array.has.invalid-length' | 'array.has.invalid-value' | 'array.has.null-items' | 'array.has.undefined-items' | 'array.is.deep' | 'array.is.empty' | 'array.is.heterogeneous' | 'array.is.large' | 'array.is.missing-value' | 'array.is.sparse' | 'array.not.array' | 'array.not.unique' | 'array.now.compacted' | 'array.now.flattened' | 'array.too.short' | 'array.too.long' | 'array.without.empty-strings' | 'array.without.null-items' | 'array.without.undefined-items' | 'bigint.is.large' | 'bigint.not.bigint' | 'bigint.not.equal' | 'bigint.not.in-range' | 'bigint.not.negative' | 'bigint.not.positive' | 'bigint.not.non-negative' | 'bigint.not.non-positive' | 'bigint.not.safe' | 'bigint.not.string' | 'bigint.too.large' | 'bigint.too.small' | 'boolean.not.boolean' | 'boolean.not.false' | 'boolean.not.true' | 'boundary.cannot.allow-unknown' | 'boundary.does.at-most-one' | 'boundary.does.mutual-exclusion' | 'boundary.does.require-all' | 'boundary.does.require-date-range' | 'boundary.does.require-field' | 'boundary.does.require-one' | 'boundary.fatal.error' | 'date.in.future' | 'date.in.past' | 'date.is.before-epoch' | 'date.is.far-future' | 'date.is.invalid' | 'date.not.after' | 'date.not.before' | 'date.not.date' | 'date.not.in-range' | 'date.not.same-day' | 'date.not.same-month' | 'date.not.same-year' | 'date.not.weekday' | 'date.not.weekend' | 'date.now.undefined' | 'date.too.early' | 'date.too.late' | 'error.while.normalizing' | 'error.while.parsing' | 'error.while.scanning' | 'error.while.validating' | 'map.has.circular-ref' | 'map.has.non-string-key' | 'map.is.empty' | 'map.is.large' | 'map.not.map' | 'map.too.large' | 'map.too.small' | 'number.is.too-large' | 'number.not.number' | 'number.not.zero' | 'number.not.finite' | 'number.not.integer' | 'number.not.float' | 'number.not.negative' | 'number.not.positive' | 'number.not.in-range' | 'number.not.in-port-range' | 'number.not.multiple-of' | 'number.not.non-negative' | 'number.not.non-positive' | 'number.not.safe-integer' | 'number.now.positive-zero' | 'number.now.undefined' | 'number.too.high' | 'number.too.low' | 'object.has.circular-references' | 'object.has.empty-array' | 'object.has.empty-object' | 'object.has.empty-string' | 'object.has.extra-key' | 'object.has.invalid-key' | 'object.has.invalid-key-length' | 'object.has.key' | 'object.has.many-keys' | 'object.has.missing-key' | 'object.has.missing-value' | 'object.has.null-value' | 'object.has.undefined-value' | 'object.is.deep' | 'object.is.empty' | 'object.not.deeply-equal' | 'object.not.object' | 'object.not.plain-object' | 'object.now.plain' | 'object.too.few-keys' | 'object.too.many-keys' | 'object.without.empty-arrays' | 'object.without.empty-objects' | 'object.without.empty-strings' | 'object.without.null-keys' | 'object.without.undefined-keys' | 'policy.is.moderate' | 'policy.is.strict' | 'scan.is.disabled' | 'scan.rule.checked' | 'set.has.circular-refs' | 'set.is.empty' | 'set.is.large' | 'set.not.set' | 'set.too.large' | 'set.too.small' | 'string.has.invalid-length' | 'string.has.leading-whitespace' | 'string.has.repeating-whitespace' | 'string.has.trailing-whitespace' | 'string.has.unsafe-unicode' | 'string.has.whitespace' | 'string.has.whitespace-edges' | 'string.is.disallowed' | 'string.is.empty' | 'string.is.long' | 'string.is.not-match' | 'string.too.long' | 'string.too.short' | 'string.must.end-with' | 'string.must.start-with' | 'string.not.allowed' | 'string.not.alpha' | 'string.not.alphanumeric' | 'string.not.ascii' | 'string.not.country-code' | 'string.not.currency-code' | 'string.not.email' | 'string.not.ip' | 'string.not.in-range' | 'string.not.numeric' | 'string.not.phone' | 'string.not.postal-code' | 'string.not.printable' | 'string.not.strict-email' | 'string.not.strict-phone' | 'string.not.string' | 'string.not.trimmed' | 'string.not.url' | 'string.not.uuid' | 'string.now.array' | 'string.now.bigint' | 'string.now.binary' | 'string.now.boolean' | 'string.now.collapsed' | 'string.now.date' | 'string.now.duration' | 'string.now.enum' | 'string.now.hex' | 'string.now.integer' | 'string.now.json' | 'string.now.number' | 'string.now.object' | 'string.now.octal' | 'string.now.parsed' | 'string.now.scientific' | 'string.now.trimmed' | 'string.now.undefined' | 'string.now.url' | 'type.not.valid' | 'unknown.not.scannable' | 'value.not.found' | 'value.not.null' | 'value.not.null-or-undefined' | 'value.not.undefined' | 'value.was.contained';
+/**
+ * Severity level attached to an event as it moves through the pipeline.
+ *
+ * Kinds describe how the event should be interpreted, not whether the
+ * pipeline accepts or rejects a value. Policy makes those decisions.
+ *
+ * These literals are stable and intentionally minimal so contributors can
+ * classify events consistently across scan, parse, normalize, validate,
+ * boundary, and policy stages.
+ */
+export type EventKind = 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * User‑supplied pattern used to match event codes in policy configuration.
+ *
+ * Patterns are plain strings. They may include wildcards or other matching
+ * syntax defined by the policy layer, but the type remains open so policy
+ * authors are not constrained by the EventCode union.
+ *
+ * This alias exists to distinguish user patterns from canonical event codes
+ * and to make intent clear at call sites.
+ */
+export type EventPattern = string;
+/**
+ * Structural filter used by policies to match specific events.
+ *
+ * A rule narrows the set of events a policy entry applies to. Each field is
+ * optional, and matching is exact: a rule only matches events whose path,
+ * code, kind, and phase equal the values provided here.
+ *
+ * Rules are intentionally minimal. They do not support patterns, wildcards,
+ * or partial matching. More complex behavior is composed by listing multiple
+ * rules rather than expanding this shape.
+ */
+export interface EventRule {
+    readonly path?: FieldPath;
+    readonly code?: EventCode;
+    readonly kind?: EventKind;
+    readonly phase?: PipelinePhase;
+}
+/**
+ * Immutable fact emitted by any stage of the pipeline.
+ *
+ * A JaneEvent records what happened at a specific path: which phase produced
+ * it, how severe it is, and the stable code describing the condition. Events
+ * never encode decisions or control flow; they are observations only.
+ *
+ * Optional fields carry developer‑facing context (`message`), end‑user
+ * context (`userMessage`), the originating input name, and any structured
+ * metadata needed by tooling. All fields are stable and contributor‑visible.
+ */
+export interface JaneEvent {
+    readonly phase: PipelinePhase;
+    readonly kind: EventKind;
+    readonly code: EventCode;
+    readonly message?: string;
+    readonly inputName?: string;
+    readonly userMessage?: string;
+    readonly path?: FieldPath;
+    readonly metadata?: Record<string, unknown>;
+}

package/dist/core/shapes/events.js

@@ -0,0 +1,10 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Event
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Structured observations emitted by each pipeline phase.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};

package/dist/core/shapes/field-path.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Field Path
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Structural paths that locate positions inside JSON‑like data.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+/**
+ * A structured, lossless representation of a location inside a value.
+ *
+ * A FieldPath is an ordered list of segments, each describing a single step
+ * into an object or array. This avoids string parsing, keeps traversal
+ * deterministic, and provides a stable reference for validation, scanning,
+ * formatting, and boundary evaluation.
+ */
+export interface FieldPath {
+    segments: FieldPathSegment[];
+    toString(): string;
+    inputName?: string;
+}
+/**
+ * A single step in a FieldPath.
+ *
+ * Segments are either object keys or array indexes. They never infer meaning
+ * and never encode both at once, ensuring paths remain literal and unambiguous
+ * across all pipeline stages.
+ */
+export type FieldPathSegment = SegmentIndex | SegmentKey;
+/**
+ * A segment that refers to an array index.
+ *
+ * Represents a concrete numeric position inside a list. Index segments keep
+ * array traversal stable and predictable for scanning, diff, and explain.
+ */
+export interface SegmentIndex {
+    kind: 'index';
+    index: number;
+}
+/**
+ * A segment that refers to an object key.
+ *
+ * Stores the key exactly as encountered. No normalization or inference is
+ * applied, preserving the original structure for formatting, parsing, and
+ * boundary evaluation.
+ */
+export interface SegmentKey {
+    kind: 'key';
+    key: string;
+}

package/dist/core/shapes/field-path.js

@@ -0,0 +1,10 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Field Path
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Structural paths that locate positions inside JSON‑like data.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export {};

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

@@ -0,0 +1,21 @@
+/**
+ * ----------------------------------------------------------------------------
+ * Shapes | Barrel File
+ * ----------------------------------------------------------------------------
+ * @package         @clementine-solutions/jane
+ * @description     Central export surface for all shape families in this
+ *                  module.
+ * @see             https://jane-io.com
+ * ----------------------------------------------------------------------------
+ */
+export type { DiffEntry, DiffFunction, DiffResult, ExplainFunction, ExplainResult, ExplainStep, ReplayFunction, ReplayResult, ReplayStep, TelemetryContext, TelemetryDiffRecord, TelemetryNormalizeRecord, TelemetryDecideRecord, TelemetryExplainRecord, TelemetryParseRecord, TelemetryReplayRecord, TelemetryRecord, TelemetryRecordBase, TelemetryResult, TelemetryScanRecord, TelemetrySink, TelemetryStage, TelemetryValidateRecord, } from './analysis';
+export type { BoundaryContext, BoundaryDecideConfig, BoundaryDecision, BoundaryInput, BoundaryMetadata, BoundaryResult, BoundaryRule, BoundaryRuleResult, } from './boundary';
+export type { EventCode, EventKind, EventRule, JaneEvent } from './events';
+export type { FieldPath, FieldPathSegment, SegmentIndex, SegmentKey } from './field-path';
+export type { NormalizationMode, NormalizationResult, NormalizationRule, NormalizationStageContext, NormalizationStageOutput, } from './normalize';
+export type { ParserFactory, ParserFactoryRule, ParseResult, ParseRule, ParseStageContext, ParseStageOutput, ParserFluentRule, ParserName, } from './parse';
+export type { FieldMetadata, PipelineBuilder, PipelineBuilderBase, PipelineInput, PipelineMetadata, PipelinePhase, PipelineResult, } from './pipeline';
+export type { Policy, PolicyAnalysisConfig, PolicyContext, PolicyDecideConfig, PolicyDecision, PolicyDecisionCode, PolicyExceptionConfig, PolicyInput, PolicyOverrides, PolicyResult, } from './policy';
+export type { JaneBoundaryResult, JaneResult, PublicPipeline } from './public';
+export type { ContainmentContext, ContainmentOptions, InternalJsonArray, InternalJsonObject, InternalJsonValue, JsonValue, ScanRule, ScanRuleSet, ScanRunner, ScanStageContext, ScanStageOutput, StructuralType, } from './scan';
+export type { ValidatorFactory, ValidatorFactoryRule, ValidatorFluentRule, ValidatorName, ValidationRule, ValidationStageContext, ValidationStageOutput, } from './validate';