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.

DumpResult

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.

ProcessEvent

ProcessIdentity

ProcessObservation

ProcessObservationCapabilities

ProcessObservationError

ProcessWatch

ProcessWatchConfigurationError

ProcessWatchCursor

ProcessWatchGap

ProcessWatchLoss

ProcessWatchMatch

ProcessWatchSubscriber

StackDump

Enums

CapabilitySupport

Negotiated support level for a single EventCategory.

CaptureSource

EventCategory

Category of observable process activity.

ObservationGrade

ObservationPolicy

ObserverEventKind

What happened to an observed process.

ProcessEventKind

ProcessWatchRead

StackCapture

TraceScope

Scope at which observation is negotiated.

Functions

observe_launched_tree

Observe the launched process tree of an already-running process.

read_process_argv

Read a process’s argument vector without flattening argument boundaries.

read_process_cmdline

Read a stable human-readable process command display string.

read_process_file_handles