Skip to content

Ordered AER Event Integrity

The ordered event surface preserves the information that the legacy rate decoder intentionally discards: raw wire address, dense mapped channel, polarity, source identity, source timestamp, and source sequence. It is the loss-intolerant path from the MIF-007 B-dot producer through the MIF-006 ingress boundary to CONTROL's public exact-current LIF runtime.

This is a simulation and diagnostic path. It has no actuation authority and does not replace the established lif_fire permit or the independent safety veto.

Versioned contracts

The machine-readable contracts are:

  • schemas/aer_address_map_v1.schema.json, which binds each raw unsigned 16-bit address to one dense unsigned 16-bit channel and an explicit -1 or +1 polarity;
  • schemas/aer_event_stream_v1.schema.json, which binds a shot, clock domain, source frequency, map identity and digest, explicit sequence_start, and ordered events;
  • schemas/aer_exact_current_projection_v1.schema.json, which binds the normalized-current projection calibration and its provenance;
  • schemas/aer_exact_current_trace_v1.schema.json, which describes the complete projected interval trace;
  • schemas/aer_exact_current_execution_v1.schema.json, which binds that trace to the complete CONTROL execution packet and both digests.

Canonical map and stream JSON uses sorted compact keys, UTF-8, and one trailing newline. Their SHA-256 digests therefore identify exact bytes, not merely equivalent parsed objects. Python, Rust, and Julia independently reproduce the same mapping, validation, canonical bytes, and digests.

Ordering and loss policy

An event stream is accepted only when all of the following hold:

  • the selected address map is non-ambiguous, ordered, and dense;
  • every event's declared polarity agrees with the raw-address binding;
  • sequences are contiguous from the explicit sequence_start;
  • timestamps never regress within the batch;
  • the map identifier and SHA-256 digest match the selected map; and
  • all integer fields fit their declared unsigned 16-bit or unsigned 64-bit wire domains.

AerIntegrityBuffer uses a reject-newest policy. A rejected event does not advance its expected sequence or timestamp, so a producer can drain and retry the same event. Lifetime telemetry exposes generated, accepted, dropped, queued, high-water, and sticky-overflow state and enforces generated == accepted + dropped. Exact-current execution refuses any stream whose loss accounting is inconsistent, whose queued count differs from the supplied batch, or whose drop/overflow state is non-zero.

Exact-current projection

AerExactCurrentProjectionSpec maps each dense channel to a canonical decimal current for each named CONTROL transition. The only admitted fidelity scope in this profile is normalized_simulation_only; physical calibration requires a separate governed profile.

project_aer_events(...) expands every event into a half-open rectangular pulse, retains the active source sequences on every interval, preserves zero- current gaps, and binds the source stream, source-event list, projection spec, and output trace by SHA-256. AerExactCurrentLIFBridge then executes the trace through CONTROL's public stateful exact-current runtime. Across incremental batches it enforces contiguous time, contiguous source sequence, one source identity per shot, and explicit reset before sequence-space reuse.

Python API

event_integrity

Versioned, fail-closed integrity contracts for MIF AER event streams.

AERIntegrityError

Bases: ValueError

Base class for rejected AER mapping and stream contracts.

AERAddressMapError

Bases: AERIntegrityError

Raised when an AER address map is ambiguous or malformed.

UnknownAERAddressError

Bases: AERIntegrityError

Raised when an event address is absent from the selected map.

AERPolarityMismatchError

Bases: AERIntegrityError

Raised when explicit event polarity contradicts its mapped address.

AERSequenceError

Bases: AERIntegrityError

Raised when an event sequence is duplicated, reordered, or has a gap.

AERTimestampRegressionError

Bases: AERIntegrityError

Raised when event time regresses within one ordered stream.

AERContractMismatchError

Bases: AERIntegrityError

Raised when serialized evidence disagrees with its selected contract.

AerAddressBinding(raw_address, channel, polarity) dataclass

One raw-u16 address to dense-u16 channel and polarity binding.

__post_init__()

Validate the wire address, dense channel, and explicit polarity.

to_mapping()

Return this binding as a canonical JSON-compatible mapping.

from_mapping(value) classmethod

Parse one strict binding without accepting extra fields.

AerAddressMap(map_id, bindings, schema_version=AER_ADDRESS_MAP_SCHEMA_VERSION) dataclass

Immutable versioned map from raw AER addresses to dense channels.

n_channels property

Return the dense feature-channel count declared by the map.

digest property

Return the SHA-256 digest of the canonical map representation.

__post_init__()

Reject unordered, duplicate, sparse, or aliased bindings.

resolve(raw_address)

Resolve one raw address or fail closed when it is unknown.

to_mapping()

Return the canonical JSON-compatible address-map document.

to_canonical_bytes()

Serialize the address map deterministically for hashing and custody.

from_mapping(value) classmethod

Parse one strict versioned address-map document.

RawAerEvent(source_id, raw_address, polarity, t_ns, sequence) dataclass

One source-identified event before address-map resolution.

__post_init__()

Validate raw wire fields without deriving channel identity.

MappedAerEvent(source_id, raw_address, channel, polarity, t_ns, sequence) dataclass

One raw event with map-verified dense channel and polarity.

__post_init__()

Validate all source, mapped, and wire-level event fields.

to_mapping()

Return the canonical JSON-compatible mapped event.

AerLossTelemetry(generated, accepted, dropped, queued, high_watermark, overflow_sticky) dataclass

Conservation-checked lifetime counters for one integrity buffer epoch.

__post_init__()

Validate non-negative counters and event conservation.

AerAdmission(accepted, event, reason, telemetry) dataclass

Explicit accepted or reject-newest outcome for one valid source event.

__post_init__()

Reject contradictory admission states.

AerIntegrityBuffer(capacity, address_map, *, sequence_start=0)

Bounded map-validating FIFO with explicit reject-newest loss telemetry.

events property

Return queued mapped events in accepted sequence order.

telemetry property

Return a conservation-checked immutable counter snapshot.

__len__()

Return the number of currently queued mapped events.

push(event)

Validate and admit one event, rejecting newest explicitly when full.

pop_oldest()

Remove and return the oldest event, refusing an empty queue.

reset_epoch()

Reset sequence, time, and telemetry only after the queue is drained.

AerEventStream(shot_id, clock_domain, source_frequency_hz, map_id, map_digest, events, sequence_start, schema_version=AER_EVENT_STREAM_SCHEMA_VERSION) dataclass

Map-bound AER evidence for one shot and one declared clock basis.

digest property

Return the SHA-256 digest of the canonical stream representation.

__post_init__()

Validate the stream envelope and sequence from its declared start.

to_mapping()

Return the canonical JSON-compatible event-stream document.

to_canonical_bytes()

Serialize the event stream deterministically for hashing and custody.

from_raw_events(address_map, events, *, shot_id, clock_domain, source_frequency_hz, sequence_start) classmethod

Resolve a complete contiguous stream against address_map.

from_mapping(value, address_map) classmethod

Parse stream evidence and re-resolve every declared mapped field.

exact_current_lif_bridge

Project ordered MIF-007 AER events into CONTROL's exact-current runtime.

The projection is deliberately explicit about its fidelity boundary. It is a deterministic normalized-current simulation contract, not a facility calibration or an actuation claim. Raw event identity is retained in every projected interval and any reported loss prevents execution.

AerExactCurrentProjectionError

Bases: ValueError

Raised when an AER stream cannot be projected without semantic loss.

AerTransitionCalibration(transition_name, channel_currents) dataclass

Normalized current contributed by each mapped channel to one transition.

__post_init__()

Validate canonical normalized-current calibration fields.

to_payload()

Return the canonical calibration payload.

AerExactCurrentProjectionSpec(address_map_digest, pulse_width_ns, calibrations, calibration_id, calibration_provenance, schema=AER_EXACT_CURRENT_PROJECTION_SCHEMA, profile=AER_EXACT_CURRENT_PROJECTION_PROFILE, fidelity_scope='normalized_simulation_only') dataclass

Versioned rectangular-pulse projection into normalized CONTROL current.

n_channels property

Return the dense mapped channel count.

transition_names property

Return transition order consumed by CONTROL.

sha256 property

Return the canonical projection digest.

__post_init__()

Validate the complete versioned simulation projection contract.

to_payload()

Return the complete canonical projection contract.

to_json()

Serialize the projection contract canonically.

AerProjectedTick(start_ns, stop_ns, active_sequences, transition_currents) dataclass

One lossless half-open interval presented to CONTROL.

duration_ms property

Return this exact nanosecond interval in CONTROL's millisecond unit.

__post_init__()

Validate one contiguous finite-current projection interval.

to_payload()

Return the traceable interval payload without binary floats.

AerExactCurrentProjection(shot_id, source_id, clock_domain, source_frequency_hz, address_map_digest, start_ns, stop_ns, sequence_start, event_count, source_stream_sha256, source_events_sha256, projection_spec_sha256, ticks) dataclass

Complete event-preserving projection for one contiguous shot interval.

sha256 property

Return the digest of the complete projection trace.

__post_init__()

Validate complete interval coverage and immutable provenance.

to_payload()

Return a canonical, reviewable projection trace.

to_json()

Serialize the complete projection canonically.

AerExactCurrentExecution(projection, control_execution) dataclass

Bind the lossless MIF projection to CONTROL's complete SC packets.

sha256 property

Return the complete execution digest.

to_payload()

Return both complete layers without reducing the SC packet trace.

to_json()

Serialize the complete cross-repository execution canonically.

AerExactCurrentLIFBridge(runtime, spec, *, shot_id, sequence_start=0)

Stateful bridge with locally transactional source cursors.

next_start_ns property

Return the next required shot-relative interval start.

next_sequence property

Return the first sequence required in the next stream batch.

from_installed_control(spec, *, shot_id, sequence_start=0) classmethod

Bind through CONTROL's installed, digest-verified public API.

Parameters

spec : AerExactCurrentProjectionSpec Normalized current calibration and exact event-map identity. shot_id : str Non-empty identifier shared with the CONTROL shot. sequence_start : int, optional First u64 generation sequence in this accounting epoch, default 0. Time still starts at zero; this does not restore CONTROL state.

Returns

AerExactCurrentLIFBridge Fresh bridge bound to the installed SC reference profile.

Raises

AerExactCurrentProjectionError If the identity, sequence origin, or optional runtime is invalid.

execute(stream, telemetry, *, stop_ns)

Execute one interval and commit local cursors only after CONTROL returns.

reset_shot(shot_id)

Reset both CONTROL state and shot-relative source time atomically.

project_aer_events(stream, telemetry, spec, *, start_ns, stop_ns)

Create a lossless piecewise-constant current trace for one shot interval.

Focused verification

./.venv/bin/pytest -q --no-cov \
  tests/unit/aer/test_event_integrity_contract.py \
  tests/unit/aer/test_event_integrity_properties.py \
  tests/unit/aer/test_exact_current_lif_bridge.py

The real cross-repository integration test is tests/integration/test_aer_exact_current_lif_chain.py. It must run in an environment containing the exact supported SCPN-CONTROL and SC-NeuroCore packages; it does not replace those packages with a local test double.

Fidelity boundary

This surface closes ordered software event integrity, loss telemetry, and the normalized exact-current bridge. It does not claim independent simulator conformance, fixed-point neuron RTL parity, target-device timing closure, hardware-in-the-loop equivalence, or facility calibration. Those remain separate evidence gates.

The exact-current bridge accepts an explicit sequence_start when creating a new accounting epoch, matching AerIntegrityBuffer and AerEventStream. The default is zero. Shot time and CONTROL state still start from zero; a nonzero sequence origin does not restore a previous physical state. Once the last u64 event is accepted, another execution fails until reset_shot, which starts sequence zero again.

Required full-chain CI measures exact_current_lif_bridge.py against its real, pinned CONTROL/SC distributions with a 100% statement and branch gate. The Python-only gate owns the remaining AER modules and real Verilator ingress tests. Moving the bridge between environments does not relax its threshold.