Experimental physical entropy

Development experiment. The random number and seed policy remains the formal approach: use explicit, recorded seeds and Aner's deterministic random APIs for reproducible science. This separate Python tool explores a future bridge from externally recorded physical measurements, such as a bubble experiment, to an explicit seed. It does not change the Aner runtime or automatically reseed any operation.

No hardware is connected or validated by this implementation. A physical-recording label records the operator's assertion. It does not establish that the bytes contain physical randomness, that a device is genuine, or that observations are independent. The tool assigns zero validated entropy bits to every capture. This means entropy has not been established, rather than that every physical source has no entropy.

The implemented boundary is:

External apparatus and recorder
    -> completed local byte file
    -> explicit capture and catastrophic-fault smoke checks
    -> retained raw.bin + provenance manifest
    -> verify / replay
    -> explicit nonnegative Int64 seed
    -> existing deterministic Aner API

The recorder, instrument protocol, digitization, and interpretation of physical measurements remain external. There is no camera/serial/USB driver, network service, device discovery, stdin input, live stream reader, or background acquisition. A future hardware integration must implement and validate those stages separately.

Run the local protocol

The tool uses Python 3.10 or newer and the standard library. Run these commands from the AnerPL repository root.

First exercise the protocol with a deliberately predictable fixture:

python3 -c 'from pathlib import Path; Path("entropy-fixture.bin").write_bytes(bytes(range(256)) * 4)'
python3 tools/experimental_entropy.py capture \
  --input entropy-fixture.bin \
  --output entropy-fixture-capture \
  --source-kind fixture \
  --source-id "deterministic byte counter; not physical randomness" \
  --notes "Protocol exercise only; 00..ff repeated four times"
python3 tools/experimental_entropy.py verify entropy-fixture-capture
python3 tools/experimental_entropy.py replay entropy-fixture-capture --seed-only

capture requires a new output directory and refuses to replace an existing capture. Its parent directory must exist. The source file must be a completed regular file containing 1,024 through 1,048,576 bytes inclusive. Symbolic links, directories, FIFOs, and device files are rejected. Allocation and byte count are bounded; this is not a wall clock timeout for an unresponsive filesystem. The tool never waits for a stream to fill a requested length.

For a real experiment, record measurements using the apparatus's own bounded acquisition process, then explicitly import the completed file:

python3 tools/experimental_entropy.py capture \
  --input completed-bubble-recording.bin \
  --output bubble-capture-001 \
  --source-kind physical-recording \
  --source-id "lab bubble sensor, instrument B17, run 001" \
  --notes "Describe sensor, sample rate, byte encoding, extraction, and recorder version"
python3 tools/experimental_entropy.py verify bubble-capture-001
python3 tools/experimental_entropy.py replay bubble-capture-001 --seed-only

This example requires a recording supplied by the operator; the repository does not contain one. Source identity is limited to 256 characters and acquisition notes to 2,048. Metadata rejects control characters. Keep more detailed instrument records alongside the capture.

All successful commands print JSON, except replay --seed-only, which prints the verified seed as a decimal integer. Errors return a nonzero exit code, report the cause on stderr, and print no seed on stdout. A capture that fails smoke checks produces no output directory. A failed write removes the partial files when filesystem permissions permit; a missing manifest always means the capture is incomplete. There is no fallback to a clock, operating system generator, built in fixture, or PRNG.

Retention, verification, and use in Aner

Each successful capture retains:

verify and replay read the retained bytes, enforce the same limits, repeat smoke checks, and recompute the raw hash, derivation digest, and seed. Missing files, malformed/oversized manifests, duplicate JSON keys, unknown formats, and inconsistent computed fields fail. The raw filename is fixed; a manifest cannot redirect verification to another path. Corrupt bytes, altered seeds, altered smoke results, and inflated entropy claims fail verification.

SHA-256 checks consistency with the manifest, not authenticity. Someone who can replace both files can construct a different internally consistent capture or relabel its source. Identity, notes, and import time are descriptive metadata without a signature or external trust anchor. Archive the capture and the repository/recorder revisions under the same access and audit controls as the experiment's other inputs.

To use a verified seed, copy the decimal printed by replay --seed-only into an explicit seed argument, for example tensor.random(rows: 2, cols: 3, seed: VERIFIED_DECIMAL, scale: 1.0). Replace VERIFIED_DECIMAL with that integer before running Aner. Import aner.tensor for this example. Keep the seed and capture hash in the experiment record. APIs that add stage/epoch offsets to a seed can impose further bounds; their documented limits still apply.

Aner output after that seed is deterministic pseudorandom output. Replaying the same capture yields the same seed; requesting replay repeatedly does not acquire fresh physical samples. Changing an instrument label also does not create a new seed. Use a new physical recording when the experiment calls for a new acquisition, and retain it for replay.

Exact version 1 derivation

The versioned domain separator is the following 34 bytes, including the final zero byte:

domain = b"Aner.experimental-entropy.seed.v1\x00"
digest = sha256(domain + raw_bytes).digest()
seed = int.from_bytes(digest[:8], "big") & ((1 << 63) - 1)

The resulting seed is in [0, 2^63 - 1], which fits Aner's nonnegative Int64 seed contracts. The full SHA-256 derivation digest and raw file SHA-256 are both retained. The seed is a decimal string in JSON to avoid rounding in consumers with only 53 bits of exact integer precision.

This is a deterministic compression/conditioning experiment. Its output has at most 63 bits of capacity, regardless of input length. Hashing does not establish an entropy estimate, recover missing physical entropy, authenticate an instrument, or make deterministic fixtures unpredictable. This construction has not been validated as a NIST entropy source or an approved random bit generator.

What the smoke checks establish

The custom custom-byte-smoke-v1 rules reject a recording when:

• An identical byte run reaches 32 bytes.
• One byte value occurs more than one quarter of the time.
• The fraction of one bits lies outside the inclusive interval [1/4, 3/4].

These fixed prototype thresholds catch some stuck or extremely biased byte streams. They are deliberately not called the NIST Repetition Count Test or Adaptive Proportion Test. They are not calibrated to a physical source's failure modes or assessed entropy, and they may reject useful but biased raw physical measurements. They also accept many predictable inputs: the ascending byte fixture above passes. Neither passing these checks nor a uniform looking histogram proves randomness or independence.

The source's sampling and byte encoding must be understood before interpreting these results. A video container, compressed file, timestamps, or encoded sensor metadata can look varied while reflecting deterministic structure. Do not hide those effects with a hash and then interpret the hash's appearance as evidence about the source.

Bubble experiment investigation

A useful next experiment records an observable such as bubble arrival intervals or image region changes, together with sample times, sensor settings, and the unmodified measurements. Before proposing an extractor, characterize periodic pumping, camera frame synchronization, quantization, shared drift, correlations, restart behavior, sensor saturation, and missing samples. Device specific start up and ongoing fault checks belong before conditioning.

An experimental adapter should have an explicit acquisition duration/byte limit, stop on disconnect or sensor fault, preserve acquisition failures, and emit a completed file only after a successful bounded capture. A separate repeatable digitization step should document exactly how raw measurements become bytes. Preserve the original measurements as well as the byte file consumed by this tool. No adapter is implemented or claimed here.

Before claiming useful physical entropy, investigate the source model, environmental effects, dependence, conservative min entropy estimation, restart behavior, and source specific health tests. NIST SP 800 to 90B separates noise sources, optional conditioning, and health testing; source validation requires evidence beyond simple statistical checks. Its sections 2.2, 3, 4, and 6 provide the reference framework, not a certification conferred on this prototype. See the NIST publication and current errata notice and full SP 800 to 90B. The source must provide uncertainty before deterministic conditioning can preserve or concentrate it.

This experiment is for scientific investigation and reproducible seed import. Do not use its seeds or Aner's scientific PRNG output for cryptographic keys, authentication tokens, or a certified randomness service.

Validate the protocol implementation

python3 -m unittest discover -s tests -p 'test_experimental_entropy.py' -v

The offline tests cover exact byte retention, a fixed derivation vector, deterministic replay, explicit unverified physical labels, predictable fixtures passing smoke checks, stuck/biased inputs, size limits, existing directory protection, manifest/raw corruption, malformed JSON, forbidden identity claims, symbolic links, and FIFO rejection. Every test input is a local deterministic fixture. These tests validate the software protocol, not a physical source.