Crate cellos_telemetry 

In-guest telemetry agent for the CellOS runner-evidence wedge (Phase F).

Phase F3a — implementation. ADR-0006 is the doctrine reference.

Operating model (ADR-0006 §5):

• This agent runs as PID 2, forked by cellos-init BEFORE the workload process (PID 3+) starts.
• Workload seccomp profile blocks kill(2), tgkill(2), and ptrace(2) against PIDs ≤ 2; the agent is structurally unreachable from the workload. (TODO seccomp gate — config lives in cellos-host-firecracker.)
• The agent holds NO private key. Authenticity comes from WHICH vsock CID:port its frames arrive on — the host bound the channel before the workload existed.
• The agent fills only probe_source, guest_pid, guest_comm, guest_monotonic_ns, and the leading content_version. The supervisor host-stamps cell_id, run_id, host_received_at, spec_signature_hash, and the ADG output block on receipt; anything the agent puts in those fields is overwritten.

Wire shape (ADR-0006 §12):

u32 LE length || CBOR map(5) {
    "content_version"     => u16  (FIRST — host short-circuits unknown major)
    "probe_source"        => text
    "guest_pid"           => u32
    "guest_comm"          => text
    "guest_monotonic_ns"  => u64
}

The CBOR encoder/decoder is hand-rolled and minimal: definite-length map(5), uint major (0), text major (3), no floats, no tags, no indefinite lengths. content_version is always emitted first so the host can reject unknown majors before walking unknown probe-source strings.

Probes the agent declares (Phase F3):

• process.spawned, process.exited (/proc delta walker)
• capability.denied (stub — kernel surface not yet wired)
• declared inotify watch (one)
• net.connect_attempted (stub)

Back-pressure (ADR-0006 §5.3): drop-with-counter. The agent surfaces drops via cell.observability.guest.telemetry.dropped, never by blocking the workload.

See [docs/adr/0006-in-vm-observability-runner-evidence.md] for the complete decision record.

Modules

probe_source

Probe source identifiers the agent emits.

probes

Probe surfaces — Linux-only.

Structs

GuestTelemetryDeclaration

Guest-side telemetry declaration — what the in-VM agent claims it will exercise. The host validates declared ⊆ authorized before accepting these events (ADR-0006 §11 admission validation, Doctrine #11).

ProbeEvent

One probe-firing the agent emits.

Enums

WireError

Errors surfaced by the wire encoder/decoder.

Constants

MAX_FRAME_BODY_BYTES

Maximum frame body size (CBOR map payload) the agent ever emits. 4 KiB is generous for our 5-field map; the host enforces the same bound.

VMADDR_CID_HOST

Vsock CID for the host (VMADDR_CID_HOST). Firecracker maps guest-initiated connect(CID=2) to the host listener.

VSOCK_TELEMETRY_PORT

Vsock port the guest agent connects to on the host. Must match cellos_host_telemetry::VSOCK_TELEMETRY_PORT.

WIRE_CONTENT_VERSION_MAJOR

CBOR wire-format major version. Must match cellos_host_telemetry::WIRE_CONTENT_VERSION_MAJOR or the host rejects the frame (ADR-0006 §12 wire-schema versioning).

Functions

decode_event_body

Decode a frame body (no length prefix) into a ProbeEvent.

decode_frame

Decode a length-prefixed frame: u32 LE length || CBOR body.

encode_event_body

CBOR-encode a ProbeEvent body (no length prefix).

encode_frame

CBOR-encode a ProbeEvent and prepend the 4-byte LE frame-length header.