No public description

PiperOrigin-RevId: 1024688515
diff --git a/centipede/engine_abi.h b/centipede/engine_abi.h
index cdb1f84..a139500 100644
--- a/centipede/engine_abi.h
+++ b/centipede/engine_abi.h
@@ -28,6 +28,10 @@
 
 // Opaque handles for in-memory input objects used by the test, which
 // may be serialized/deserialized by the engine.
+//
+// The engine never inspects or fabricates handle values. It only passes back
+// handles that the adapter emitted through a `FuzzTestInputSink` and that the
+// engine has not yet passed to `FuzzTestAdapter::FreeInput`.
 typedef uintptr_t FuzzTestInputHandle;
 
 typedef struct {
@@ -76,9 +80,10 @@
 typedef struct {
   FuzzTestInputSinkCtx* ctx;
 
-  // Emits a test `input` to the engine. Engine would call
-  // `FuzzTestAdapter::FreeInput` on the emitted input after the engine is
-  // done with it.
+  // Emits a test `input` to the engine. The engine may call
+  // `FuzzTestAdapter::FreeInput` on the emitted input after it is done with it.
+  // An adapter must never emit the same `input` handle twice to input sinks
+  // without the engine freeing it via `FreeInput` in between.
   void (*Emit)(FuzzTestInputSinkCtx* ctx, FuzzTestInputHandle input);
 } FuzzTestInputSink;
 
@@ -141,6 +146,22 @@
                    const FuzzTestCoverageDomain* domain);
 } FuzzTestCoverageDomainRegistry;
 
+// Test adapter callbacks.
+//
+// The engine upholds the following when it invokes the callbacks of a
+// `FuzzTestAdapter` and of its `FuzzTestAdapterManager`:
+//
+//   - Callbacks are invoked sequentially, on the thread that called into the
+//     engine with the manager (e.g. `FuzzTestWorkerMaybeRun`). A callback is
+//     never invoked while another one is running.
+//   - Pointer arguments (sinks, views and registries) are non-null and remain
+//     valid until the callback returns. Calling a method of a sink or registry
+//     passed to a callback never invokes an adapter or manager callback.
+//   - Every input emitted by the adapter is passed to `FreeInput` at most once,
+//     and only before `FreeCtx` is called. An input is not used after the input
+//     or the belonging context is freed.
+//   - A callback is invoked with the `ctx` of the struct that holds it. Once
+//     `FreeCtx` is called, no callback is invoked with that `ctx` again.
 typedef struct FuzzTestAdapterCtx FuzzTestAdapterCtx;
 typedef struct FuzzTestAdapter {
   FuzzTestAdapterCtx* ctx;
@@ -169,7 +190,7 @@
                  int shrink, const FuzzTestInputSink* sink);
 
   // [Optional] Performs cross-over mutation using `origin` and `other`, and
-  // emits the mutant using `sink`.
+  // emits the mutant using `sink`. `origin` and `other` may be the same input.
   //
   // It should not change the content/metadata of `origin` or `other`.
   void (*CrossOver)(FuzzTestAdapterCtx* ctx, FuzzTestInputHandle origin,
diff --git a/centipede/engine_controller_abi.h b/centipede/engine_controller_abi.h
index 74b2714..181d92b 100644
--- a/centipede/engine_controller_abi.h
+++ b/centipede/engine_controller_abi.h
@@ -36,6 +36,9 @@
 } FuzzTestBytesViews;
 
 // Run the FuzzTest controller with `flags` and `manager`.
+//
+// `manager` and `flags` are only used during the call: the engine does not
+// retain them after this function returns.
 FuzzTestControllerStatus FuzzTestControllerRun(
     const FuzzTestAdapterManager* manager, const FuzzTestBytesViews* flags);
 
diff --git a/centipede/engine_worker_abi.h b/centipede/engine_worker_abi.h
index 6d79441..079122c 100644
--- a/centipede/engine_worker_abi.h
+++ b/centipede/engine_worker_abi.h
@@ -40,6 +40,9 @@
 } FuzzTestWorkerStatus;
 
 // Try to run as a FuzzTest worker with `manager` if needed.
+//
+// `manager` and its context are only used during the call: the engine does not
+// retain them after this function returns.
 FuzzTestWorkerStatus FuzzTestWorkerMaybeRun(
     const FuzzTestAdapterManager* manager);
 
diff --git a/rust/engine/src/engine_ffi.rs b/rust/engine/src/engine_ffi.rs
index 276b3e1..e1c0f07 100644
--- a/rust/engine/src/engine_ffi.rs
+++ b/rust/engine/src/engine_ffi.rs
@@ -24,8 +24,12 @@
 use core::marker::PhantomPinned;
 use core::ptr;
 
-// Opaque handles for in-memory input objects used by the test, which
-// may be serialized/deserialized by the engine.
+/// Opaque handles for in-memory input objects used by the test, which
+/// may be serialized/deserialized by the engine.
+///
+/// The engine never inspects or fabricates handle values. It only passes back
+/// handles that the adapter emitted through a `FuzzTestInputSink` and that the
+/// engine has not yet passed to `FuzzTestAdapter::FreeInput`.
 #[repr(transparent)]
 pub struct FuzzTestInputHandle(pub usize);
 
@@ -155,9 +159,10 @@
 pub struct FuzzTestInputSink {
     pub ctx: *mut FuzzTestInputSinkCtx,
 
-    /// Emits a test `input` to the engine. Engine would call
-    /// `FuzzTestAdapter::FreeInput` on the emitted input after the engine is
-    /// done with it.
+    /// Emits a test `input` to the engine. The engine may call
+    /// `FuzzTestAdapter::FreeInput` on the emitted input after it is done with it.
+    /// An adapter must never emit the same `input` handle twice to input sinks
+    /// without the engine freeing it via `FreeInput` in between.
     pub emit:
         Option<unsafe extern "C" fn(ctx: *mut FuzzTestInputSinkCtx, input: FuzzTestInputHandle)>,
 }
@@ -192,12 +197,10 @@
 /// Constants for the layout of the coverage feature as a 64-bit unsigned
 /// integer:
 ///
-///   - Bits 63..59: 5-bit domain ID of the feature. Each domain is a
-///     logically independent feature namespace registered in
-///     `FuzzTestAdapter::SetUpCoverageDomains`.
+///   - Bits 63..59: 5-bit domain ID of the feature. Each domain is a logically independent feature
+///     namespace registered in `FuzzTestAdapter::SetUpCoverageDomains`.
 ///   - Bits 58..32: 27-bit feature ID within the domain.
 ///   - Bits 31..0:  32-bit counter value of the feature.
-///
 pub struct FuzzTestCoverageFeatureLayout;
 
 impl FuzzTestCoverageFeatureLayout {
@@ -276,6 +279,21 @@
     _not_unpin: PhantomPinned,
 }
 
+/// Test adapter callbacks.
+///
+/// The engine upholds the following when it invokes the callbacks of a
+/// `FuzzTestAdapter` and of its `FuzzTestAdapterManager`:
+///
+///   - Callbacks are invoked sequentially, on the thread that called into the engine with the
+///     manager (e.g. `FuzzTestWorkerMaybeRun`). A callback is never invoked while another one is
+///     running.
+///   - Pointer arguments (sinks, views and registries) are non-null and remain valid until the
+///     callback returns. Calling a method of a sink or registry passed to a callback never invokes
+///     an adapter or manager callback.
+///   - Every input emitted by the adapter is passed to `FreeInput` at most once, and only before
+///     `FreeCtx` is called. An input is not used after the input or the belonging context is freed.
+///   - A callback is invoked with the `ctx` of the struct that holds it. Once `FreeCtx` is called,
+///     no callback is invoked with that `ctx` again.
 #[repr(C)]
 pub struct FuzzTestAdapter {
     pub ctx: *mut FuzzTestAdapterCtx,
@@ -314,7 +332,7 @@
     >,
 
     /// [Optional] Performs cross-over mutation using `origin` and `other`, and
-    /// emits the mutant using `sink`.
+    /// emits the mutant using `sink`. `origin` and `other` may be the same input.
     ///
     /// It should not change the content/metadata of `origin` or `other`.
     pub cross_over: Option<
@@ -438,6 +456,9 @@
 #[allow(improper_ctypes)]
 unsafe extern "C" {
     /// Try to run as a FuzzTest worker with `manager` if needed.
+    ///
+    /// `manager` and its context are only used during the call: the engine does not
+    /// retain them after this function returns.
     pub fn FuzzTestWorkerMaybeRun(manager: *const FuzzTestAdapterManager) -> FuzzTestWorkerStatus;
 
     /// Returns whether the current process is running as a FuzzTest worker -
@@ -445,6 +466,9 @@
     pub fn FuzzTestWorkerIsRequired() -> c_int;
 
     /// Run the FuzzTest controller with `flags` and `manager`.
+    ///
+    /// `manager` and `flags` are only used during the call: the engine does not
+    /// retain them after this function returns.
     pub fn FuzzTestControllerRun(
         manager: *const FuzzTestAdapterManager,
         flags: *const FuzzTestBytesViews,