[fm] Introduce SitrepGuardedInsert.

[mergeconflict]

Add the SitrepGuardedInsert Diesel combinator and the SitrepGuardedResource trait: a generic primitive for FM rendezvous to insert a resource row idempotently and guarded against stale-sitrep execution.

The combinator wraps a caller-supplied resource INSERT in a single CTE statement that:

• aborts (StaleSitrep) unless the executor's expected generation still equals the latest sitrep's generation column;
• short-circuits (AlreadyExists) if a creation marker already exists for the resource id;
• on a successful insert, atomically writes a creation marker.

The result is surfaced as a SitrepGuardedInsertOutcome of Created / AlreadyExists / StaleSitrep.

Context: #10248. This is used in #10533 and #10535 which are split out in hopes of making the review somewhat less miserable.

[hawkw]

style nit, feel free to ignore me: personally, I prefer to stuff the if conditions into the match arms so it feels less nested, like:

Suggested change

	Err(e) => {
	if matches_sentinel(&e, &[STALE_GENERATION_SENTINEL]).is_some()
	{
	Ok(SitrepGuardedInsertOutcome::StaleSitrep)
	} else if matches_sentinel(&e, &[ALREADY_EXISTS_SENTINEL])
	.is_some()
	{
	Ok(SitrepGuardedInsertOutcome::AlreadyExists)
	} else {
	Err(e)
	}
	}
	Err(e) if matches_sentinel(&e, &[STALE_GENERATION_SENTINEL]).is_some() => {
	Ok(SitrepGuardedInsertOutcome::StaleSitrep)
	}
	Err(e) if matches_sentinel(&e, &[ALREADY_EXISTS_SENTINEL]).is_some() => {
	Ok(SitrepGuardedInsertOutcome::AlreadyExists)
	},
	Err(e) => Err(e),

[hawkw]

It would be nice to have an expectorate test (and maybe also an EXPLAIN test) for the kind of queries that this generates.

[hawkw]

I don't love that these are all just &'static strs that have to be the name of the table/column, which you could easily imagine someone typoing and silently breaking something. I wonder if we can instead use the generated diesel schema types, so that you could instead write something like

impl SitrepGuardedResource for nexus_db_model::Alert {
    type MarkerTable = schema::rendezvous_alert_created::table;
    type MarkerIdColumn = schema::rendezvous_alert_created::dsl::alert_id;
    type GenerationColumn = schema::fm_sitrep::dsl::alert_generation;
}

This way, you get the actual table name from the schema and can't mistype it --- and we can probably leverage diesel to enforce that MarkerIdColumn comes from the same table as MarkerTable?

I notice that this is what the DatastoreCollectionConfig trait does:

omicron/nexus/db-model/src/collection.rs

Lines 11 to 77 in 8341849

	/// Trait to be implemented by any structs representing a collection.
	/// For example, since Silos have a one-to-many relationship with
	/// Projects, the Silo datatype should implement this trait.
	/// ```
	/// # use diesel::prelude::*;
	/// # use nexus_db_model::DatastoreCollectionConfig;
	/// # use nexus_db_model::Generation;
	/// #
	/// # table! {
	/// # test_schema.silo (id) {
	/// # id -> Uuid,
	/// # time_deleted -> Nullable<Timestamptz>,
	/// # rcgen -> Int8,
	/// # }
	/// # }
	/// #
	/// # table! {
	/// # test_schema.project (id) {
	/// # id -> Uuid,
	/// # time_deleted -> Nullable<Timestamptz>,
	/// # silo_id -> Uuid,
	/// # }
	/// # }
	///
	/// #[derive(Queryable, Insertable, Debug, Selectable)]
	/// #[diesel(table_name = project)]
	/// struct Project {
	/// pub id: uuid::Uuid,
	/// pub time_deleted: Option<chrono::DateTime<chrono::Utc>>,
	/// pub silo_id: uuid::Uuid,
	/// }
	///
	/// #[derive(Queryable, Insertable, Debug, Selectable)]
	/// #[diesel(table_name = silo)]
	/// struct Silo {
	/// pub id: uuid::Uuid,
	/// pub time_deleted: Option<chrono::DateTime<chrono::Utc>>,
	/// pub rcgen: Generation,
	/// }
	///
	/// impl DatastoreCollectionConfig<Project> for Silo {
	/// // Type of Silo::identity::id and Project::silo_id
	/// type CollectionId = uuid::Uuid;
	///
	/// type GenerationNumberColumn = silo::dsl::rcgen;
	/// type CollectionTimeDeletedColumn = silo::dsl::time_deleted;
	///
	/// type CollectionIdColumn = project::dsl::silo_id;
	/// }
	/// ```
	pub trait DatastoreCollectionConfig<ResourceType> {
	/// The Rust type of the collection id (typically Uuid for us)
	type CollectionId: Copy + Debug;
	/// The column in the CollectionTable that acts as a generation number.
	/// This is the "child-resource-generation-number" in RFD 192.
	type GenerationNumberColumn: Column + Default;
	/// The time deleted column in the CollectionTable
	// We enforce that this column comes from the same table as
	// GenerationNumberColumn when defining insert_resource() below.
	type CollectionTimeDeletedColumn: Column + Default;
	/// The column in the ResourceTable that acts as a foreign key into
	/// the CollectionTable
	type CollectionIdColumn: Column;
	}

[hawkw]

i feel like this should probably be a Generation?