Library API

Stable entry point

Import the curated fragcap::deep_capture::api surface. DEEP_CAPTURE_API_VERSION is 1, and STABLE_API_EXPORTS records its exact sorted inventory. Older top-level deep_capture exports remain for compatibility, but the curated module carries the explicit stability policy. API version is independent from product version and artifact schema versions.

use fragcap::deep_capture::api::{DEEP_CAPTURE_API_VERSION, STABLE_API_EXPORTS};

assert_eq!(DEEP_CAPTURE_API_VERSION, 1);
assert!(STABLE_API_EXPORTS.contains(&"SessionConfigBuilder"));

Use SessionConfigBuilder and AdapterSetBuilder for validated configuration and adapter composition. Side-effect-free preparation yields an immutable SessionPlan; Authorization binds to its exact PlanId. Checked session lifecycle operations own start, observation, stop, possible fact writes, cleanup, bundle finalization, and one typed TerminalReport. Caller adapters do not bypass plan authority, budgets, ownership, or cleanup.

Ownership and integration

Session coordinators and adapter sets are thread-confined. Adapter traits do not implicitly promise Send or Sync. CancellationToken is the thread-safe cooperative request handle, observed at coordinator stage boundaries. Finite cooperative budgets are not a promise to preempt an arbitrary blocking third-party adapter. Preserve explicit cancellation, bounded stage work, and exact obligations in an integration.

Evolvable public enums require fallback handling; do not exhaustively match the currently known variants and assume the set will never grow. Typed event-delivery failures, invalid transitions, preflight refusals, cleanup outcomes, and artifact outcomes remain distinct from successful session completion. Compatibility applicability is centralized in fragcap-targets, not reconstructed by each caller.

Optional phase diagnostics

Version-one CompatibilityObservation and TerminalSnapshot keep their existing readable and constructible fields. Phase metadata is additive: a PhaseQualifiedObservation pairs an unchanged observation with its EvidenceWindow; an optional ProxyLease::drain_phase_observations returns a PhaseObservationDrain. Native adapters provide exact semantic timing against the sealed observation cutoff. Late or unavailable native timing never authorizes the earlier calibration case, even though the raw observation remains retained.

The default optional method returns None, preserving the original adapter drain contract and its raw-observation policy. Legacy and controlled producers remain responsible for the evidence they supply under that contract; this fallback does not claim that native timing was measured. An adapter supplying explicit phase metadata must classify unknown timing as unavailable. The new *_in_windows pure policy helpers require index-aligned windows and treat missing indices as unavailable; the existing raw policy signatures retain their version-one semantics.

The non-exhaustive DeepCaptureEvent::Diagnostics carries TerminalDiagnostics before fact and artifact finalization. Its observation_windows vector indexes the retained raw observations in their original order; evidence_windows gives exact lifecycle cutoffs, and proxy independently reports bounded connection causes and completed exchanges. Consumers retain this additive payload alongside the unchanged terminal report. Shared current-case readiness selects the greatest durable row ID for each exact applicable measurement key; older differing measurements remain history, while contradictory same-ID values or absent durable chronology cannot authorize readiness. Missing diagnostics remain explicitly unavailable rather than being inferred from cleanup text.

Native proxy diagnostics also report a frozen inspection decision per retained connection or UDP association, plus directional bytes and datagrams forwarded by an uninspected relay. Aggregate relay totals survive bounded connection-detail eviction. An injected exact-game decider can select blind relay before TLS or application handling; the public Deep Capture CLI continues to select launch-chain inspection until its operator-facing scope control ships. Destination policy and session capability authentication apply to either action.

Reproducible examples, not operator execution

The native library example and public API integration tests exercise the library without routing through the CLI. Controlled adapters require no game, account, capture driver, elevation, external service, or host trust mutation. They establish contract behavior, not universal real-target compatibility.

Read the source API documentation, architecture, and independent-review handoff for ownership and review boundaries. Agents must not run installed sensitive product or real games as a substitute for operator validation on published bytes.