openquant.provenance

Pure Python. Signatures are as written in the source; descriptions are the docstrings. All Python modules.

Examples and interpretation: provenance.

Find an API by task

Bind exact selected numeric values to declared revisions across row reordering.

This is an association/consistency guard, NOT provider authentication. A caller can backdate metadata or swap identities and construct a new self-consistent bundle; SHA256 cannot detect that without an external trusted anchor. Selection is latest only relative to supplied history: omitted candidates cannot be discovered. A bundle does not attest that selection policy executed or history was complete; a caller may directly bundle an eligible older revision. Identical payloads with forged/swapped physical identities cannot recover discarded provenance. Python frozen objects are convenience invariants, not a security boundary.

Order: retain stable sample/source IDs and raw revisions; select at the decision BEFORE cleaning drops nulls or resolves duplicate events; retain bundles beside cleaned rows; rejoin by IDs and compare exact payloads. This strict API rejects all unknown clocks/nonfinite or null payloads globally, including future records. It never drops an invalid latest revision to resurrect an older value. A later valid publication is excluded at earlier decisions by the explicit as-of policy.

Payloads are flat named builtin integers/floats. Types and signed zero matter: integer 1 differs from float 1.0. Cleaner coercion, rounding, renamed fields and learned transformations fail exact binding. If needed, explicitly normalize values with precision-loss checks BEFORE constructing revisions; this module performs no numeric coercion. Mapping inputs cannot reveal duplicate fields already collapsed upstream; use pairs to reject duplicates before collapse. Normal package import still initializes existing native/package dependencies.

Classes

RejoinResult

class RejoinResult(NamedTuple)

Bundles in incoming row order; their original selection positions and drops.

Dropped keys are in original selected order. Missing selection groups remain missing; they cannot be reintroduced as cleaned rows.

Revision

class Revision

Candidate for a stable sample row and source stream; revision IDs scoped to both.

Multiple event times may belong to a sample/source group. The caller owns the group definition; this is not inference of identity from timestamps or OHLCV. event_ns means an observed input event, not a forecast target/validity time; availability must not precede that observation. Integers use canonical hex encoding, so no decimal conversion limit or binary64 rounding is imposed. Use make_revision to accept mappings or pairs. Direct construction also validates all fields. Payload field order is normalized, numeric values are not.

Jump to a member:

• key

Revision.key

key() -> Key

SelectedRevision

class SelectedRevision

Schema-tagged digest binds decision, IDs, clocks and exact typed payload.

Digest is consistency evidence, not a signature or external attestation. Reconstructing a bundle with fabricated but consistent inputs recomputes it.

Selection

class Selection

Bundles and missing groups, each in original decisions mapping order.

Functions

make_revision

make_revision(
    row_id: str,
    source_id: str,
    revision_id: str,
    event_ns: int,
    available_ns: int,
    payload: object,
) -> Revision

Construct an immutable, validated candidate without coercing numeric values.

rejoin_selected

rejoin_selected(
    selection: Selection,
    rows: Iterable[tuple[str, str, int, object]],
    *,
    require_all: bool = True,
) -> RejoinResult

Bind reordered/subset cleaned rows to exactly matching selected payloads.

Every row is (row_id, source_id, event_ns, numeric payload). Duplicate/unknown keys and any typed-value mismatch fail closed. No positional fallback, rounding tolerance, field dropping or revision reselection. Empty rows are permitted only with explicit require_all=False and dropped-key output.

select_revisions

select_revisions(
    revisions: Iterable[Revision],
    decisions: Mapping[Key, int],
) -> Selection

Select latest eligible (event, availability), before canonical row cleaning.

All supplied records and decisions validate. Same full revision identities with conflicting content reject globally, even if future or unrequested. Exact duplicates are idempotent. Distinct winning revision IDs at equal clocks reject even if their values agree. No lexical revision-ID tiebreak is implied. Unknown decision groups return missing, never a prior row or positional match.