Module observer 

Phase 1 of #221: the process-observation capability model and the portable process-lifecycle baseline.

This module defines the stable observation types — ObserverConfig, ObserverCapabilities, ObserverEvent, and the ObserverSubscriber handle — plus the always-available lifecycle backend that emits started and exited events for child processes spawned by this crate.

TraceScope dimension (#539)

The capability matrix is negotiated for a TraceScope:

• TraceScope::SystemWide — the historical default, names admin-gated system tracers (ETW kernel providers, eBPF, EndpointSecurity). All syscall categories report Unavailable until the Phase 3 backends from #469 land.
• TraceScope::LaunchedProcessTree — the no-admin tier added by #539. Names per-OS primitives that operate purely on the spawn boundary this crate already owns (Windows Job Object IOCP, Linux subreaper+pidfd, macOS kqueue EVFILT_PROC). Currently every syscall category reports Unavailable; each #539 slice flips one cell to Supported/Partial with no shape change.

Lifecycle is Supported in every scope because owning the spawn boundary is sufficient for started/exited on all three platforms.

ObserverCapabilities::negotiate() preserves the pre-#539 contract and returns the SystemWide matrix; new callers should use negotiate_for_scope.

Off by default

Observation is entirely opt-in. A NativeProcess emits no events unless an ObserverConfig is attached via NativeProcess::with_observer (or the equivalent builder seam). With no observer configured the lifecycle hooks are inert: no channel, no allocation, no events.

The handle is a plain std::sync::mpsc receiver so the lifecycle baseline stays free of the daemon runtime (tokio/IPC). Phase 2 layers the daemon-owned subscriber model on top of these same event types.

Structs

CategoryCapability

Capability report for one EventCategory: the negotiated support level, the backend that would serve it, and a human-readable reason.

ObserverCapabilities

The full capability matrix produced by ObserverCapabilities::negotiate or ObserverCapabilities::negotiate_for_scope.

ObserverConfig

Opt-in configuration that turns process observation on for a single NativeProcess.

ObserverEvent

A single observation emitted by the lifecycle baseline.

ObserverSubscriber

Receiver handle for observation events.

Enums

CapabilitySupport

Negotiated support level for a single EventCategory.

EventCategory

Category of observable process activity.

ObserverEventKind

What happened to an observed process.

TraceScope

Scope at which observation is negotiated.

Functions

read_process_cmdline

Read the live command line of pid using the negotiated no-admin per-OS primitive for the LaunchedProcessTree scope.

read_process_file_handles

Snapshot the file handles currently held by pid, returned as human-readable strings (filesystem paths where possible, socket:[...] / anon_inode:... style labels otherwise).