Measurement record API¶
Use DomainRecord when an extension needs raw observations with explicit units,
semantics, missingness and provenance. Native fitness/cost result columns
retain their original contract; they are not migrated implicitly into this one.
Read versioned result records for complete CI examples and compatibility rules, then evaluation for interpretation.
coleman.results.domain ¶
Immutable, transport-independent version-1 measurement contracts.
Units and meanings are opaque, case-sensitive identifiers: no conversion or statistical inference is implicit. Native scheduling rows are a separate legacy contract and cannot be interpreted as these records without explicit provenance.
DomainRecord ¶
Bases: _Contract
Bundle immutable versioned measurements for one logical decision.
Attributes:
| Name | Type | Description |
|---|---|---|
schema_version |
int
|
Exact supported integer version, currently 1; unknown versions reject. |
namespace |
str
|
Extension namespace; |
run_id |
str
|
Stable logical run identity. |
execution_id |
str
|
Logical execution identity preserved on resume, not a worker/retry ID. |
decision_id |
str
|
Decision identity distinguishing relevant policy/reward/build/variant keys. |
data_fingerprint |
str
|
Identified SHA-256 of the interpreted input data. |
available_at |
datetime
|
Aware outcome-availability timestamp, normalized to UTC. This is not automatically the application's ingestion/first-receipt time. |
provenance |
ResultProvenance
|
Producer, resolved specification and evaluation identity. |
measurements |
tuple[Measurement, ...]
|
Named observations, sorted by name after validation; duplicates reject. |
learning_reward |
(LearningReward or None, optional)
|
Separate transformed signal, without replacing raw measurements. |
Raises:
| Type | Description |
|---|---|
ValidationError
|
If fields, version, timestamps, namespace or measurement invariants fail. |
Notes
The stable logical key is namespace/run/execution/decision, excluding schema version and contents. Value changes alter the content digest, not that key. Legacy native rows require their existing reader; no migration invents missing units, availability or provenance. Construction performs no I/O.
identity_digest
property
¶
Return SHA-256 of the logical key, independent of measurement values.
logical_key
property
¶
Return a retry-stable key; content conflicts at this key are errors.
from_json
classmethod
¶
Read and validate a v1 record without migrating legacy native rows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload
|
str or bytes
|
Complete JSON document. Its acquisition layer owns byte/depth limits. |
required |
Returns:
| Type | Description |
|---|---|
DomainRecord
|
Validated frozen record with normalized timestamp and measurement order. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If JSON syntax, duplicate keys, root shape, fields or schema version are invalid. Pydantic validation errors are included in this category. |
Notes
Performs no I/O and invents no missing unit, timestamp or provenance. Unknown versions and unknown fields reject rather than receiving defaults.
measurement ¶
Look up one declared observation without inventing missing values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Exact case-sensitive declared measurement name. |
required |
Returns:
| Type | Description |
|---|---|
Measurement
|
Matching frozen measurement, including its explicit status and units. |
Raises:
| Type | Description |
|---|---|
KeyError
|
If the measurement was omitted from the record. |
require_comparable ¶
Require compatible metadata and observed values without inference.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
other
|
DomainRecord
|
Record to compare against the current record's declared evaluation. |
required |
name
|
str
|
Exact measurement name required in both records. |
required |
Raises:
| Type | Description |
|---|---|
KeyError
|
If either record omits the measurement. |
ValueError
|
If metadata differs or either value is unknown, unavailable or not applicable. |
Notes
Returns None on success and mutates neither record. Performs no unit
conversion, ranking, probability estimation or statistical test. Use
require_compatible to validate metadata while reporting incomplete evidence.
require_compatible ¶
Validate measurement and evaluation metadata without comparing values.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
other
|
DomainRecord
|
Record whose schema, namespace, data and evaluation must agree. |
required |
name
|
str
|
Exact measurement name required in both records. |
required |
Raises:
| Type | Description |
|---|---|
KeyError
|
If either record omits the named measurement. |
ValueError
|
If units, meanings, directions, lower bounds, data, schema, namespace or evaluation identities are incompatible. |
Notes
Returns None on success and mutates neither record. Missing values are
allowed. Producers/specifications may differ within the same declared
evaluation; compatibility does not establish statistical comparability.
to_json ¶
Serialize v1 deterministically; absent optional fields stay absent.
Explicit optional nulls remain null. The wire format uses an array of named measurements; tuples prevent mutable dictionaries in core APIs. Raises validation errors for non-JSON/non-finite values.
LearningReward ¶
Bases: _Contract
Keep a finite transformed learning signal separate from raw outcomes.
Attributes:
| Name | Type | Description |
|---|---|---|
value |
float
|
Finite transformed value; its sign does not change raw observations. |
unit |
str
|
Explicit output-scale identifier. |
transform_id |
str
|
Versioned identifier of the transformation that produced the signal. |
Notes
Frozen and strict; no transformation, comparison or I/O is performed.
Invalid or missing fields raise pydantic.ValidationError.
Measurement ¶
Bases: _Contract
Represent one signed observation with explicit units and meaning.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Unique measurement name within its record; native metric names are reserved. |
value |
float or None
|
Required raw value. Observations are finite and may be zero or negative. Other statuses require explicit null; omitting a measurement is distinct. |
unit |
str
|
Case-sensitive unit identifier; no conversion is implicit. |
meaning |
str
|
Versioned semantic identifier specifying what was measured. |
direction |
{'minimize', 'maximize', 'none'}
|
Declared objective direction, without performing a comparison. |
status |
{'observed', 'unknown', 'unavailable', 'not_applicable'}
|
Observation state. Only |
minimum |
(float or None, optional)
|
Optional finite lower bound in the same unit. No implicit bound is imposed on arbitrary custom units. |
Raises:
| Type | Description |
|---|---|
ValidationError
|
If required fields, finite values, reserved names or state/bound invariants are violated. |
Notes
Frozen and strict. A learning reward is a separate transformed signal; this model preserves the raw observation and performs no I/O.
ResultProvenance ¶
Bases: _Contract
Identify a producer and the configuration/evaluation it actually used.
Attributes:
| Name | Type | Description |
|---|---|---|
producer |
str
|
Explicit producer identifier. |
producer_version |
str
|
Explicit producer version, not inferred from the running environment. |
spec_fingerprint |
str
|
Identified SHA-256 of the resolved specification used for the observation. |
evaluation_fingerprint |
str
|
Identified SHA-256 of the declared metric/protocol/data interpretation. |
source_revision |
(str or None, optional)
|
Explicit source revision; absence remains absence. |
Notes
Frozen metadata with no environment collection or I/O. Fingerprints record
provenance, not proof of independent observations or scientific admission.
Invalid fields raise pydantic.ValidationError.
canonical_json ¶
Encode JSON values deterministically with finite numbers only.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload
|
object
|
JSON values: string-keyed dictionaries, lists, strings, booleans, integers, finite floats or null. Array order remains significant. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Compact JSON with sorted keys and unescaped UTF-8 text. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If an object key is not a string or a float is non-finite. |
TypeError
|
If an input contains a non-JSON Python object. |
Notes
Performs no filesystem access, rounding or default=str coercion.
This is COLEMAN JSON v1, not RFC 8785 cross-language JCS. The caller must
bound payload size/depth before using untrusted data.
decode_json ¶
Parse JSON while rejecting duplicate object keys at every depth.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload
|
str or bytes
|
Complete JSON document. Callers must impose their own byte/depth limits. |
required |
exact_decimals
|
bool
|
Preserve non-integral numeric literals as |
False
|
Returns:
| Type | Description |
|---|---|
object
|
Decoded JSON value; no domain/schema validation is performed here. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If syntax or duplicate keys make the document invalid. |
UnicodeDecodeError
|
If input bytes cannot be decoded by the standard JSON reader. |
Notes
Accesses no files. Non-standard numeric constants and contract-specific finite-number, shape and version constraints must be rejected by the consuming typed contract; this helper is not their replacement.
fingerprint ¶
Hash canonical JSON input with an identified SHA-256 digest.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
payload
|
object
|
JSON-compatible input accepted by |
required |
Returns:
| Type | Description |
|---|---|
str
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If canonical encoding rejects a key or non-finite value. |
TypeError
|
If the input contains a non-JSON object. |
Notes
Performs no filesystem access. Hashes content rather than authenticating its producer, license, temporal availability or scientific eligibility.