Ultrasonic v2 encrypts records, rejects replays and stops pretending to be audio

What it does

Ultrasonic encrypts a small data record, protects it against replay, and measures how a simulated acoustic channel carries it. Records are AES-256-GCM authenticated; replay protection uses a private persistent SQLite ledger with serialized transactions.

The most important property is what it refuses to do. Received content is inert JSON. There is no shell access and no audio device access anywhere in the supported surface.

What changed

Commit e5c6302, merged as pull request #2 on September 10, replaces a 2025 prototype with a v2 alpha: authenticated records, the replay ledger, a vectorized phase-independent binary FSK channel at 500 raw bits per second, a local CLI, an official SDK stdio MCP server with fixed bounded actions, and MetaHarness profiles with an Autogenous gate that requires explicit human promotion.

The legacy media code is archival and excluded from the v2 package. Its unauthenticated HTTP launcher is retired — which is the sort of removal that matters more than a feature.

Get started

Python 3.11 or newer and Node 22.16 or newer:

git clone https://github.com/ruvnet/ultrasonic.git
cd ultrasonic
python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-v2.txt
python -m pip install --no-deps .
python -m ultrasonic_v2 fixture

Expected result: the fixture command produces an authenticated record from the bundled example without touching any audio hardware.

The MCP server is launched through the harness runtime:

npm ci --prefix .harness/runtime
node .harness/runtime/cli.mjs status
node .harness/runtime/cli.mjs mcp

An MCP host launches node with the absolute repository path:

{"mcpServers":{"ultrasonic":{"command":"node","args":["/absolute/path/ultrasonic/.harness/runtime/cli.mjs","mcp"]}}}

The caller cannot supply commands, paths, keys or environment variables. Tests run only when the operator sets RUV_ALLOW_VALIDATION=1. Policy is readable at ruv://ultrasonic/policy.

Use it today

Practical case: studying replay protection without building a radio. Input is a small JSON record. Workflow is encode with the fixture, run the benchmark, then attempt to accept the same record twice. Output is a measured channel report plus a ledger that has seen the record.

Acceptance test: submit an identical record a second time. The ledger should reject it. If it is accepted, the ledger was reset or the key was reused with an older ledger — the README warns explicitly never to restore an older ledger while keeping the key.

Push it further

Experimental commentary. The obvious next question is whether the simulated channel survives a real room. Nothing here answers that.

Limitation: the benchmark is an aligned numerical simulation. It establishes nothing about room range, hardware compatibility, timing acquisition or whether the signal is actually inaudible. Falsifiable test: run the benchmark twice with different fixture sizes. If throughput does not track the record size the way an FSK channel should, the model is wrong before any hardware is involved.