ldtc.attest

Device-signed indicator generation, encoding, and persistence. This is the only sanctioned way for run results to leave the machine; every byte that escapes lives in a CBOR payload signed with Ed25519.

Module	Headline symbols	Use it for
indicators	IndicatorConfig, quantize_M, build_and_sign	Turn LREG.derive(...) plus the latest SC1 decision into a signed CBOR payload.
exporter	IndicatorExporter	Rate-limited writer for ind_*.cbor and the JSONL companion.
keys	KeyPaths, ensure_keys	Load or generate an Ed25519 key pair under artifacts/keys/.

See Indicators for the wire format and verifier walkthrough.

Attestation and indicator export.

attest is the boundary that everything inside the LDTC harness has to cross before leaving the machine. It manages the device's Ed25519 key pair, encodes the derived NC1/SC1 indicators into a compact payload, signs that payload, and emits the signed bundle to disk under a strict rate limit:

• keys loads or generates Ed25519 keys stored as PEM.
• indicators defines the indicator payload schema, M (dB) quantization, and CBOR signing.
• exporter is the rate-limited writer for JSONL + CBOR artifacts; it enforces the no-raw-LREG export policy.

The exporter is intentionally paranoid about the no-raw-LREG rule: it walks the payload before signing and the bundle after signing, refusing to emit anything that contains L_loop, L_ex, ci_loop, or ci_ex. That keeps the device-signed artifact safe to publish and verify independently.

indicators

indicators

Indicator encoding and signing.

Defines the indicator payload schema, M (dB) quantization, and the Ed25519 signing step that produces a CBOR-encoded, device-signed packet.

The payload is intentionally small: NC1 / SC1 booleans, a 6-bit Mq code, the run counter, the active profile id, the audit chain head, and an invalidated flag. That gives auditors enough to verify a result without exposing any raw 𝓛 value.

See Also

paper/main.tex: Methods: Measurement and Attestation; Exported indicators.

Classes:

Name	Description
IndicatorConfig	Configuration for indicator encoding.

Functions:

Name	Description
quantize_M	Quantize loop-dominance M (dB) to a 6-bit code.
build_and_sign	Build CBOR indicator payload and Ed25519 signature bundle.

IndicatorConfig dataclass

IndicatorConfig(Mmin_db: float = 3.0, profile_id: int = 0)

Configuration for indicator encoding.

Attributes:

Name	Type	Description
Mmin_db	float	Threshold for NC1 pass, in dB.
profile_id	int	Profile selector (0 = R0, 1 = R*).

quantize_M

quantize_M(M_db: float) -> int

Quantize loop-dominance M (dB) to a 6-bit code.

Maps M_db linearly onto the integer range [0, 63] with a 0.25 dB step, so the encoded Mq covers 0 through 15.75 dB. Values outside the range are clamped.

Parameters:

Name	Type	Description	Default
M_db	float	Decibel loop-dominance value.	required

Returns:

Type	Description
int	Integer in the range [0, 63] using 0.25 dB steps.

build_and_sign

build_and_sign(priv: Ed25519PrivateKey, audit: AuditLog, derived: Dict[str, float | int | bool], cfg: IndicatorConfig, last_sc1_pass: bool) -> Tuple[bytes, Dict]

Build CBOR indicator payload and Ed25519 signature bundle.

The returned cbor_bytes is what gets signed and persisted; the bundle_dict is the JSON-friendly view ({"payload": ..., "sig": "<hex>"}) used by the JSONL artifact.

Parameters:

Name	Type	Description	Default
priv	Ed25519PrivateKey	Ed25519 private key (typically from ensure_keys).	required
audit	AuditLog	Audit log providing the last hash head, anchoring this indicator to the run's audit chain.	required
derived	Dict[str, float | int | bool]	Derived indicators from LREG.derive (must not contain raw 𝓛 fields).	required
cfg	IndicatorConfig	Indicator configuration with profile id and thresholds.	required
last_sc1_pass	bool	Whether SC1 passed in the most recent evaluation.	required

Returns:

Type	Description
bytes	Tuple (cbor_bytes, bundle_dict) where bundle_dict["sig"] is
Dict	the hex-encoded Ed25519 signature over cbor_bytes.

exporter

exporter

Indicator exporter.

Rate-limited writer for device-signed indicator bundles. Each call to IndicatorExporter.maybe_export either:

1. Emits a paired *.jsonl and *.cbor artifact for the current window, or
2. Returns (False, "") because the configured rate limit has not elapsed yet.

A defense-in-depth scan rejects payloads or bundles containing raw 𝓛 fields (L_loop, L_ex, ci_loop, ci_ex).

See Also

paper/main.tex: Methods: Measurement and Attestation; Export policy.

Classes:

Name	Description
IndicatorExporter	Rate-limited export of device-signed indicator packets.

IndicatorExporter

IndicatorExporter(out_dir: str, rate_hz: float = 2.0)

Rate-limited export of device-signed indicator packets.

Writes JSONL and CBOR artifacts side-by-side after signing a derived indicator payload. Enforces the no-raw-LREG policy by inspecting every dict in the payload before signing and again after signing, raising ValueError if any banned LREG key is present (see the module-level guard in ldtc.attest.exporter).

Parameters:

Name	Type	Description	Default
out_dir	str	Output directory for indicator artifacts. Created on demand.	required
rate_hz	float	Maximum export rate in Hz. Floored at 0.1 Hz to avoid pathological intervals.	2.0

Initialize the exporter and ensure out_dir exists.

Parameters:

Name	Type	Description	Default
out_dir	str	Output directory for indicator artifacts.	required
rate_hz	float	Maximum export rate in Hz.	2.0

Methods:

Name	Description
maybe_export	Export a signed indicator bundle if the rate limit allows.

maybe_export

maybe_export(priv: Ed25519PrivateKey, audit: AuditLog, derived: Dict[str, float | int | bool], cfg: IndicatorConfig, last_sc1_pass: bool) -> Tuple[bool, str]

Export a signed indicator bundle if the rate limit allows.

Parameters:

Name	Type	Description	Default
priv	Ed25519PrivateKey	Ed25519 private key.	required
audit	AuditLog	Audit log instance (provides the last hash head).	required
derived	Dict[str, float | int | bool]	Derived indicators from LREG.derive (no raw 𝓛 fields).	required
cfg	IndicatorConfig	Indicator configuration including profile id.	required
last_sc1_pass	bool	Whether SC1 passed in the most recent evaluation.	required

Returns:

Type	Description
bool	Tuple (exported, base_path). When the rate limit blocks the
str	write, returns (False, ""). Otherwise base_path is the
Tuple[bool, str]	common prefix of the .jsonl and .cbor files written.

Raises:

Type	Description
ValueError	If derived or the signed bundle contains any raw LREG key.

keys

keys

Key management helpers.

Load or generate Ed25519 keys stored as PEM files for device-signed indicators. Designed to be one of the first things the CLI run touches so that a fresh checkout produces verifiable artifacts on its first run.

See Also

paper/main.tex: Methods: Measurement and Attestation.

Classes:

Name	Description
KeyPaths	Filesystem locations for key files.

Functions:

Name	Description
ensure_keys	Load or generate Ed25519 keys at the provided paths.

KeyPaths dataclass

KeyPaths(priv_path: str, pub_path: str)

Filesystem locations for key files.

Attributes:

Name	Type	Description
priv_path	str	Path to the private key PEM file.
pub_path	str	Path to the public key PEM file.

ensure_keys

ensure_keys(paths: KeyPaths) -> Tuple[Ed25519PrivateKey, Ed25519PublicKey]

Load or generate Ed25519 keys at the provided paths.

If no keys exist, generates a new keypair and writes them as PEM. If keys exist but are not Ed25519, regenerates an Ed25519 pair in place (overwriting the prior files). The parent directory is created on demand.

Parameters:

Name	Type	Description	Default
paths	KeyPaths	Private and public key filesystem paths.	required

Returns:

Type	Description
Tuple[Ed25519PrivateKey, Ed25519PublicKey]	Tuple (private_key, public_key).