diff --git a/crates/db/src/catalog.rs b/crates/db/src/catalog.rs
index 38ddcab..4d8f9bc 100644
--- a/crates/db/src/catalog.rs
+++ b/crates/db/src/catalog.rs
@@ -282,6 +282,14 @@ pub enum FieldError {
 /// Replace an object's flexible field values, validating each against the registry
 /// (type + term/authority resolution), and audit the per-field diff — all on `conn`.
 /// A no-op (identical to the current values) writes nothing and records no audit.
+///
+/// **Replace semantics:** `values` is the *complete* desired set. Omitting a key that
+/// was previously set REMOVES it (recorded in the audit as a removal); send every key
+/// the caller wants to retain.
+///
+/// Required-field *completeness* is intentionally NOT enforced here — a caller may set
+/// any subset. That check belongs to the publish gate (when moving to
+/// `Visibility::Public`, Plan 7).
 pub async fn set_object_fields(
     conn: &mut sqlx::PgConnection,
     actor: AuditActor,
diff --git a/crates/db/tests/object_fields.rs b/crates/db/tests/object_fields.rs
index ac24cea..7c14c53 100644
--- a/crates/db/tests/object_fields.rs
+++ b/crates/db/tests/object_fields.rs
@@ -161,4 +161,5 @@ async fn unknown_field_and_type_mismatch_are_rejected(pool: PgPool) {
             .await,
         Err(FieldError::TypeMismatch { .. })
     ));
+    drop(tx);
 }