fix(core): harden ABI cancellation contracts

core/include/versevdi_core.h

@@ -41,6 +41,7 @@ typedef uint32_t verse_status_t;
 
 typedef struct verse_core verse_core_t;
 
+/* data may be NULL only when length is zero. The view never transfers ownership. */
 typedef struct verse_bytes_view {
     const uint8_t *data;
     size_t length;
@@ -87,6 +88,12 @@ typedef struct verse_control_event_v1 {
     verse_bytes_view_t payload;
 } verse_control_event_v1_t;
 
+/*
+ * Signers run synchronously. transcript/tls_message is borrowed only for the call;
+ * signature_out is exactly 64 writable bytes. Admission may return OK,
+ * AUTHORITY_REJECTED, CANCELLED, or INTERNAL. TLS may return OK, TLS, CANCELLED,
+ * or INTERNAL. Any other value is normalized to INTERNAL.
+ */
 typedef verse_status_t (*verse_sign_admission_v1_fn)(
     void *signer_context,
     verse_bytes_view_t transcript,
@@ -95,6 +102,10 @@ typedef verse_status_t (*verse_sign_tls_ed25519_v1_fn)(
     void *signer_context,
     verse_bytes_view_t tls_message,
     uint8_t signature_out[64]);
+/*
+ * Event callbacks are serialized with one another. Each event and nested byte view
+ * is borrowed only for its callback and must not be retained.
+ */
 typedef void (*verse_state_event_v1_fn)(
     void *context,
     const verse_state_event_v1_t *event);
@@ -111,6 +122,10 @@ typedef void (*verse_control_event_v1_fn)(
     void *context,
     const verse_control_event_v1_t *event);
 
+/*
+ * create copies this table. context and every non-NULL callback must remain valid
+ * until destroy succeeds; BUSY does not end that lifetime.
+ */
 typedef struct verse_core_config_v1 {
     uint32_t struct_size;
     uint32_t abi_version;
@@ -141,6 +156,13 @@ typedef struct verse_input_event_v1 {
 } verse_input_event_v1_t;
 
 uint32_t verse_core_abi_version(void);
+/*
+ * During a signer callback, every API below except verse_core_abi_version returns
+ * REENTRANT for every handle. During an event callback, only cancel on that event's
+ * originating handle is allowed; all other calls and cross-handle cancel return
+ * REENTRANT. Connect copies both byte inputs before returning, so callers may
+ * mutate or release their buffers afterward.
+ */
 verse_status_t verse_core_create_v1(
     const verse_core_config_v1_t *config,
     verse_core_t **out_core);
@@ -151,7 +173,14 @@ verse_status_t verse_core_send_input_v1(
     verse_core_t *core,
     const verse_input_event_v1_t *event);
 verse_status_t verse_core_request_idr_v1(verse_core_t *core);
+/* Idempotent and nonblocking; it does not wait for an internal state lock. */
 verse_status_t verse_core_cancel_v1(verse_core_t *core);
+/*
+ * OK suppresses all later callbacks, releases session resources, and invalidates
+ * core. Calls admitted before destruction are accounted safely, but no API call
+ * may begin after OK. BUSY retains core, context, and callback ownership and
+ * requires a later retry.
+ */
 verse_status_t verse_core_destroy_v1(verse_core_t *core, uint32_t timeout_ms);
 
 #if defined(__APPLE__) && defined(__aarch64__)