API Overview

The published package is organized around one practical flow: translate raw records when needed, validate or compare when you want narrower primitives, order bounded or streaming inputs, then inspect the result with operator-facing summaries instead of building that layer yourself first.

Where to start

If your data is not already in the event-envelope shape, start with translateBatch(). Use validateEvent() when you need a narrow validation step before ordering, and compareByCausality() when you only need pairwise causal comparison. Move to orderEvents() for bounded replay or audit slices, then to orderEventStream() when you need watermark, late-arrival, and correction-capable behavior. Use inspectOrderResult() or inspectOrderBatch() when you want compact operational summaries without writing your own result-shaping layer first.

Focused entrypoints

If you prefer smaller import surfaces, the package also exposes focused subpath entrypoints alongside the root causal-order import. The root import may still keep compatibility aliases for older code, but the focused subpaths are the cleaner primary surface for new code.

• causal-order - Full top-level surface for users who prefer one import path.
• causal-order/types - Type-only entrypoint for the published public type surface.
• causal-order/clock - Clock helpers for creating, parsing, and serializing HLC values.
• causal-order/compare - Pairwise comparison helpers for HLC and causal reasoning, centered on the current primary names rather than deprecated compatibility aliases.
• causal-order/validate - Validation helpers for clocks and event envelopes.
• causal-order/anomalies - Structured anomaly detection and anomaly-facing runtime types.
• causal-order/inspect - Operational inspection helpers for summaries, explanations, and compact result snapshots.
• causal-order/order - Combined ordering barrel for users who want batch, stream, tie-breakers, and watermarks together.
• causal-order/batch - Bounded batch ordering plus current tie-breaker helpers, without the deprecated compatibility alias kept at the root import.
• causal-order/stream - Streaming ordering surface through orderEventStream().
• causal-order/watermarks - Watermark helpers only.
• causal-order/translate - Raw-record translation surface, including translateBatch() and TranslateBatchPolicyError.

Primary entry points

• compareByCausality() - Performs pairwise causal comparison without inventing evidence.
• inspectOrderBatch() - Builds a payload-agnostic inspection snapshot for one emitted orderEventStream() batch.
• inspectOrderResult() - Builds a payload-agnostic inspection snapshot for a bounded orderEvents() result.
• orderEvents() - Orders a bounded event set and returns ordered output, anomalies, and stats.
• orderEventStream() - Consumes an async event source and emits watermark-aware ordered batches.
• translateBatch() - Translates raw user-space records into event envelopes and structured translation anomalies.
• validateEvent() - Validates an event envelope and returns a branded validated value on success.

All exports

Clocks

• createHlcClock() - Creates a monotonic hybrid logical clock for a single node.
• parseHlc() - Parses a serialized HLC string into its structured parts.
• serializeHlc() - Serializes an HLC value into the canonical string form.

Comparison

• compareByHlc() - Compares two events by their HLC values only.
• compareByCausality() - Performs pairwise causal comparison without inventing evidence.
• compareValidatedByCausality() - Performs pairwise causal comparison on already validated events.
• applyTieBreaker() - Applies the active deterministic tie-breaker when stronger ordering is absent.
• compareDeterministically() - Deterministically compares two events when causal proof is insufficient.
• compareValidatedDeterministically() - Deterministically compares two already validated events using the current tie-breaker.

Translation

• TranslateBatchPolicyError - Error raised when translateBatch() policy configuration chooses fail-fast handling for a structured translation anomaly.
• translateBatch() - Translates raw user-space records into event envelopes and structured translation anomalies.

Validation

• validateClock() - Validates an HLC clock value and reports structured failures or warnings.
• validateEvent() - Validates an event envelope and returns a branded validated value on success.

Anomalies

• detectAnomalies() - Detects structured anomalies across a bounded event set.
• detectSingleEventAnomalies() - Detects anomalies that can be inferred from one event in isolation.

Inspection

• explainOrderedEvent() - Builds a compact human-readable explanation of why one ordered event landed where it did.
• inspectOrderBatch() - Builds a payload-agnostic inspection snapshot for one emitted orderEventStream() batch.
• inspectOrderResult() - Builds a payload-agnostic inspection snapshot for a bounded orderEvents() result.
• summarizeEventAnomalies() - Summarizes emitted event anomalies by type and severity for operator-facing inspection.
• summarizeTranslationAnomalies() - Summarizes translation anomalies by code, field, mapper, stage, and policy action.

Ordering

• DEFAULT_TIE_BREAKER - Default deterministic tie-breaker used when stronger ordering is unavailable.
• getTieBreaker() - Resolves the tie-breaker function from the current ordering options.
• orderEvents() - Orders a bounded event set and returns ordered output, anomalies, and stats.
• orderValidatedEvents() - Orders already validated events without re-running validation.
• orderEventStream() - Consumes an async event source and emits watermark-aware ordered batches.
• createProcessingTimeWatermark() - Builds a processing-time watermark helper for more aggressive stream progress.
• eventTimeWatermark() - Advances stream readiness from event-time timestamps.
• ingestedAtWatermark() - Advances stream readiness from ingestion-time metadata.

Public types

The public type surface is grouped separately from the runtime entry points so you can scan the main event, result, and streaming types without mixing them into the function list.

Core event types

• NodeId - Branded node identifier used to separate same-node and cross-node reasoning.
• EventId - Branded event identifier used for duplicate and reference checks.
• HlcTimestamp - Serialized hybrid logical clock string.
• ValidatedHlcTimestamp - Branded HLC timestamp that has passed validation.
• EventEnvelope<T = unknown> - Public shape for an input event and its ordering metadata.
• ValidatedEventEnvelope<T = unknown> - Validated event envelope safe for downstream ordering logic.
• CausalOrdering - Pairwise ordering result such as before, after, equal, or unknown.
• CausalEvidence - Machine-readable evidence explaining why one event was ordered relative to another.

Translation types

• TranslatedEventEnvelope<T = unknown> - Readonly translated event-envelope shape returned by the raw-record ingress layer.
• TranslateMapper<TInput, TValue> - Synchronous mapper shape used by translateBatch() field extractors.
• TranslateTimestampInput - Accepted raw timestamp input for translation: bigint, safe integer number, canonical integer string, or Date for explicit rejection handling.
• TranslateBatchConfig<TInput, TPayload = TInput> - Mapper configuration for translating raw records into event envelopes.
• TranslateBatchPolicy - Policy configuration controlling how translation failures are surfaced or failed.
• TranslationAnomalyCode - Stable code describing a translation-time mapping or coercion failure.
• TranslationAnomalyDomain - Stable top-level domain for translation anomaly classification.
• TranslationAnomalyFamily - Stable family split between mapping and structural translation failures.
• TranslationAnomalyCategory - Stable category used for machine-readable translation anomaly handling.
• TranslationRecordFailureAction - Fail-fast or warning action for record-level translation failures.
• TranslationOptionalFieldAction - Handling action for optional-field translation failures, including continue behavior where omission is honest.
• TranslationPolicyKey - Stable policy selector describing the translation failure class being handled.
• TranslationPolicyDecision - Resolved policy decision attached to structured translation anomalies.
• TranslationField - Stable field label used in structured translation anomalies.
• TranslationMapperName - Stable mapper-function label used in structured translation anomalies.
• TranslationAnomalyStage - Translation pipeline stage where a structured anomaly was raised.
• TranslationActualValueType - Normalized runtime value classification attached to translation anomalies.
• TranslationDiagnosticSource - Stable source split between mapping and structural translation failures.
• TranslationDiagnosticRecord<TInput = unknown> - Record-local translation diagnostic context including index and original input.
• TranslationDiagnosticOrdering - Deterministic ordering metadata attached to emitted translation anomalies.
• TranslationFieldReferenceKind - Stable field-reference kind used by translation diagnostics.
• TranslationFieldReference - Machine-readable field reference attached to translation diagnostics.
• TranslationAnomalyClassification - Stable machine-readable classification attached to translation anomalies.
• TranslationDiagnosticLocation - Structured field and mapper location metadata for translation diagnostics.
• TranslationDiagnosticContract - Contract-facing detail attached to translation diagnostics.
• TranslationDiagnostic<TInput = unknown> - Nested machine-readable diagnostic object attached to translation anomalies.
• TranslationAnomaly<TInput = unknown> - Structured translation failure record carrying mapper, field, stage, and actual-value metadata.
• TranslateBatchResult<TPayload = unknown, TInput = unknown> - Top-level translation result containing accepted envelopes and structured anomalies.

Validation and anomaly types

• ValidationErrorCode - Stable code describing a validation failure category.
• ValidationWarningCode - Stable code describing a non-fatal validation warning.
• ValidationError - Structured validation failure entry.
• ValidationWarning - Structured non-fatal validation warning entry.
• ValidationSuccess<TValue> - Successful validation wrapper carrying the validated value.
• ValidationFailure - Failed validation wrapper carrying errors and warnings.
• ValidationResult<TValue = never> - Discriminated union returned by validation helpers.
• AnomalyType - Stable anomaly category emitted by ordering and analysis helpers.
• EventAnomaly<T = unknown> - Structured anomaly record tied to one or more events.

Ordering result types

• OrderedEvent<T = unknown> - Ordered event entry with confidence, basis, and optional causal evidence.
• OrderStats - Summary counts describing the outcome of a bounded ordering run.
• OrderResult<T = unknown> - Top-level bounded ordering result containing ordered events, anomalies, and stats.
• TieBreaker<T> - Deterministic comparison function used when stronger ordering is absent.
• OrderOptions<T> - Options controlling bounded ordering behavior and anomaly handling.

Inspection types

• OrderedEventExplanation<T = unknown> - Compact explanation payload describing why an ordered event landed where it did.
• OrderedEventInspection<T = unknown> - Compact event-level inspection snapshot derived from an ordered result entry.
• InspectedEventAnomaly<T = unknown> - Compact anomaly view used by inspection helpers for operator-facing output.
• OrderedEventCounts<T = unknown> - Grouped inspection counts by order basis and confidence level.
• OrderResultInspection<T = unknown> - Payload-agnostic inspection snapshot returned by inspectOrderResult().
• OrderBatchInspection<T = unknown> - Payload-agnostic inspection snapshot returned by inspectOrderBatch().
• EventAnomalySummary - Grouped event-anomaly totals by type and severity.
• TranslationAnomalySummary - Grouped translation-anomaly totals by code, field, mapper, stage, and policy action.

Extension-policy boundary types

• PolicyVisibilityKind - Audit-output category used at the core-to-policy boundary for higher-layer decisions.
• PolicyVisibilityRecord - Operator-visible audit record describing what a higher-layer policy did without mutating payloads silently.
• ExtensionPolicyAction - Payload-agnostic contradiction-policy action shared across boundary-level policy hooks.
• CausalContradictionCandidate<T = unknown> - Payload-agnostic contradiction candidate surfaced at the core-to-policy boundary.
• CausalContradictionPolicyResult - Result shape for contradiction-policy evaluation with explicit operator visibility.
• CausalContradictionPolicy<T = unknown, TContext = unknown> - Policy interface for contradiction handling outside the core payload contract.
• EntityForkCandidate<T = unknown, TIdentity = unknown> - Payload-agnostic entity-fork candidate supplied by higher-layer identity logic.
• ForkResolutionAction - Fork-policy action set that avoids implicit payload merging inside the core.
• ForkResolutionPolicyResult - Result shape for fork-resolution decisions with explicit visibility output.
• ForkResolutionPolicy<T = unknown, TIdentity = unknown, TContext = unknown> - Policy interface for entity-fork handling outside the core payload contract.
• SemanticDedupeCandidate<T = unknown> - Payload-agnostic semantic-dedupe candidate surfaced at the core-to-policy boundary across different identifiers.
• SemanticDedupeAction - Dedupe-policy action set that preserves explicit operator-facing visibility.
• SemanticDedupePolicyResult - Result shape for semantic-dedupe decisions including retained and suppressed IDs.
• SemanticDedupePolicy<T = unknown, TContext = unknown> - Policy interface for semantic dedupe without forcing payload-aware merge logic into the core.

Streaming types

• CorrectionScope - Indicates whether a stream correction is local to a batch or broader in scope.
• CorrectionNotice - Structured notice attached to correction-capable stream batches.
• StreamAnomalyHorizon - Anomaly carry model for stream windows and emitted history.
• LateArrivalPolicy - Policy controlling how late stream events are surfaced or rejected.
• WatermarkSignal - Structured watermark progress signal returned by watermark helpers.
• WatermarkFunction<T> - Function shape used to derive stream watermark progress.
• StreamOrderOptions<T> - Options controlling streaming ordering, watermarking, and correction behavior.
• StreamOrderBatch<T = unknown> - Structured batch emitted by streaming ordering.

import {
  compareByCausality,
  inspectOrderBatch,
  inspectOrderResult,
  orderEvents,
  orderEventStream,
  translateBatch,
  validateEvent,
} from "causal-order"