docs(db): document set_object_fields replace semantics and required-field deferral

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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,

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);
 }