autumn_web/

hooks.rs

//! Mutation hook types for repository lifecycle callbacks.
//!
//! This module provides the types and trait that power before/after mutation
//! hooks on generated repositories (create, update, delete).
//!
//! # Opting in
//!
//! By default, repositories generated by `#[repository(Model)]` perform
//! plain CRUD with no hook overhead. To enable hooks, pass a hooks type:
//!
//! ```rust,ignore
//! #[derive(Clone, Default)]
//! struct ArticleHooks;
//!
//! impl MutationHooks for ArticleHooks {
//!     type Model = Article;
//!     type NewModel = NewArticle;
//!     type UpdateModel = UpdateArticle;
//!
//!     // override only the callbacks you need …
//! }
//!
//! #[repository(Article, hooks = ArticleHooks)]
//! pub trait ArticleRepository {}
//! ```
//!
//! The durable `after_*_commit` hooks are opt-in because they require Autumn's
//! framework-owned commit-hook queue table. Enable them explicitly with
//! `#[repository(Article, hooks = ArticleHooks, commit_hooks = true)]`.
//!
//! The hooks type **must** implement [`Default`] and [`Clone`] (the
//! generated extractor constructs it via `Default::default()` and the
//! repository struct derives `Clone`).
//!
//! # Lifecycle
//!
//! Every mutating CRUD operation follows the same lifecycle:
//!
//! 1. **`before_*`** -- called before the mutation with a mutable
//!    reference to the [`MutationContext`] and the input/model. The hook
//!    may validate, enrich, or reject (by returning `Err`).
//! 2. **persist** -- the actual `INSERT`, `UPDATE`, or `DELETE` runs.
//!
//! # Error semantics
//!
//! - `before_*` errors prevent the mutation entirely.
//!
//! # Helper types
//!
//! - [`Patch<T>`] -- tri-state value for partial-update (PATCH) payloads.
//! - [`FieldDiff<T>`] -- per-field before/after diff for inspecting and
//!   overriding changes inside hooks.
//! - [`MutationOp`] -- discriminant for create / update / delete.
//! - [`MutationContext`] -- carries actor identity, request ID, and
//!   timestamp into every hook invocation.

use std::borrow::Cow;

use serde::de::Deserializer;
use serde::{Deserialize, Serialize};

// ── Mutation operation & context ─────────────────────────────────────

/// The kind of mutation being performed on a repository record.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[non_exhaustive]
pub enum MutationOp {
    /// A new record is being created.
    Create,
    /// An existing record is being updated.
    Update,
    /// An existing record is being deleted.
    Delete,
}

impl MutationOp {
    /// Returns the operation name as a static string slice.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Create => "create",
            Self::Update => "update",
            Self::Delete => "delete",
        }
    }
}

impl std::fmt::Display for MutationOp {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// Context available to mutation hooks.
///
/// Carries actor identity, request metadata, and timestamps so that
/// hook implementations can perform auditing, validation, or enrichment.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MutationContext {
    /// The mutation operation type.
    pub op: MutationOp,
    /// Actor identity (user ID or service name). `None` for anonymous.
    pub actor: Option<String>,
    /// Correlation / request ID for tracing.
    pub request_id: Option<String>,
    /// Timestamp of the mutation.
    pub now: chrono::DateTime<chrono::Utc>,
    /// Cache keys to invalidate after the mutation.
    pub invalidate_keys: Vec<String>,
    /// Framework-scoped idempotency key for this mutation, when the mutation
    /// came from an idempotent HTTP request or a hook set one explicitly.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub idempotency_key: Option<String>,
}

impl MutationContext {
    /// Create a new context for the given operation.
    ///
    /// Auto-populates `now` with `Utc::now()`, `request_id` with a freshly
    /// generated UUID v4, and `actor` from the ambient
    /// [`Current::actor`](crate::current::Current::actor) (the authenticated
    /// principal when inside a request; `None` otherwise).
    #[must_use]
    pub fn new(op: MutationOp) -> Self {
        Self {
            op,
            // Seed the actor from the ambient request-scoped current actor so
            // generated writes auto-attribute to the authenticated principal
            // with zero per-call wiring. `None` outside any scope, preserving
            // the previous behavior. A `before_*` hook still overrides this,
            // since hooks run after construction.
            actor: crate::current::Current::actor(),
            request_id: Some(uuid::Uuid::new_v4().to_string()),
            now: chrono::Utc::now(),
            invalidate_keys: Vec::new(),
            idempotency_key: None,
        }
    }

    /// Add a cache key to the invalidation list.
    pub fn invalidate(&mut self, key: impl Into<String>) {
        self.invalidate_keys.push(key.into());
    }

    /// Set a scoped idempotency key for durable side-effect deduplication.
    pub fn set_idempotency_key(&mut self, key: impl Into<String>) {
        self.idempotency_key = Some(key.into());
    }
}

// ── Mutation hooks trait ─────────────────────────────────────────────

use crate::AutumnResult;
use std::future::Future;

/// Repository-scoped mutation lifecycle hooks.
///
/// All methods have default no-op implementations, so you only need to
/// override the callbacks you care about. Each method receives a
/// [`MutationContext`] (mutable for "before" hooks) and the relevant
/// model/changeset.
///
/// # Associated types
///
/// - `Model` -- the read model returned by queries (e.g., `User`).
/// - `NewModel` -- the insertable changeset (e.g., `NewUser`).
/// - `UpdateModel` -- the partial-update changeset (e.g., `UpdateUser`).
pub trait MutationHooks: Send + Sync + 'static {
    /// The read model (e.g., the `Queryable` struct).
    type Model: Send + Sync;
    /// The insertable changeset for new records.
    type NewModel: Send + Sync;
    /// The partial-update changeset.
    type UpdateModel: Send + Sync;

    /// Called before a new record is inserted.
    fn before_create(
        &self,
        _ctx: &mut MutationContext,
        _new: &mut Self::NewModel,
    ) -> impl Future<Output = AutumnResult<()>> + Send {
        async { Ok(()) }
    }

    /// Called before an existing record is updated.
    ///
    /// The `draft` holds the merged before/after state. Use per-field
    /// accessors (generated by `#[model]`) to inspect and rewrite:
    ///
    /// ```rust,ignore
    /// if draft.status().changed_to(&Status::Approved) {
    ///     draft.approved_at().set(Some(ctx.now));
    /// }
    /// ```
    fn before_update(
        &self,
        _ctx: &mut MutationContext,
        _draft: &mut UpdateDraft<Self::Model>,
    ) -> impl Future<Output = AutumnResult<()>> + Send
    where
        Self::Model: Clone,
    {
        async { Ok(()) }
    }

    /// Called before an existing record is deleted.
    fn before_delete(
        &self,
        _ctx: &mut MutationContext,
        _record: &Self::Model,
    ) -> impl Future<Output = AutumnResult<()>> + Send {
        async { Ok(()) }
    }

    /// Called after a new record is inserted.
    fn after_create(
        &self,
        _ctx: &mut MutationContext,
        _record: &Self::Model,
    ) -> impl Future<Output = AutumnResult<()>> + Send {
        async { Ok(()) }
    }

    /// Called after an existing record is updated.
    fn after_update(
        &self,
        _ctx: &mut MutationContext,
        _record: &Self::Model,
    ) -> impl Future<Output = AutumnResult<()>> + Send {
        async { Ok(()) }
    }

    /// Called after a new record is inserted **and the transaction commits**.
    ///
    /// Unlike `after_create`, this hook fires only when the surrounding
    /// database transaction has been durably committed. Use this variant for
    /// side-effects (job enqueues, emails, cache invalidation) that must not
    /// execute if the transaction rolls back.
    ///
    /// When the repository is declared with `commit_hooks = true`, generated
    /// repository code writes this hook's intent to Autumn's framework-owned
    /// durable commit-hook queue in the same transaction as the mutation.
    /// Replicas claim queued hooks with Postgres row locks, so a process-local
    /// task disappearing is recovered by retrying or dead-lettering the row
    /// instead of silently losing the side effect.
    fn after_create_commit(
        &self,
        _ctx: &mut MutationContext,
        _record: &Self::Model,
    ) -> impl Future<Output = AutumnResult<()>> + Send {
        async { Ok(()) }
    }

    /// Called after an existing record is updated **and the transaction commits**.
    ///
    /// The same transactional guarantee as `after_create_commit` applies:
    /// this hook is not called when the surrounding transaction rolls back.
    fn after_update_commit(
        &self,
        _ctx: &mut MutationContext,
        _record: &Self::Model,
    ) -> impl Future<Output = AutumnResult<()>> + Send {
        async { Ok(()) }
    }

    /// Called after a record is deleted **and the transaction commits**.
    ///
    /// The same transactional guarantee as `after_create_commit` applies:
    /// this hook is not called when the surrounding transaction rolls back.
    fn after_delete_commit(
        &self,
        _ctx: &mut MutationContext,
        _record: &Self::Model,
    ) -> impl Future<Output = AutumnResult<()>> + Send {
        async { Ok(()) }
    }
}

/// Stable hook-construction contract used by generated repositories.
///
/// This indirection keeps compile-time diagnostics anchored on Autumn-owned
/// trait names instead of compiler-rendered `Default` wording, which is more
/// brittle across platforms and environments.
pub trait RepositoryHooksDefault: Sized {
    /// Construct a hook instance for generated repository state.
    fn autumn_default() -> Self;
}

impl<T> RepositoryHooksDefault for T
where
    T: Default,
{
    fn autumn_default() -> Self {
        Self::default()
    }
}

/// Stable hook-cloning contract used by generated repositories.
///
/// Generated repository implementations clone their hook state through this
/// trait so compile-fail diagnostics stay deterministic across toolchains.
pub trait RepositoryHooksClone: Sized {
    /// Clone hook state for generated repository values.
    #[must_use]
    fn autumn_clone(&self) -> Self;
}

impl<T> RepositoryHooksClone for T
where
    T: Clone,
{
    fn autumn_clone(&self) -> Self {
        self.clone()
    }
}

// ── Default no-op hooks ──────────────────────────────────────────────

/// Zero-cost no-op implementation of [`MutationHooks`].
///
/// Used by generated repository code when the user has not configured any
/// hooks. All methods use the trait defaults (immediate `Ok(())`).
pub struct NoHooks<M, N, U> {
    _phantom: std::marker::PhantomData<(M, N, U)>,
}

impl<M, N, U> Default for NoHooks<M, N, U> {
    fn default() -> Self {
        Self {
            _phantom: std::marker::PhantomData,
        }
    }
}

impl<M, N, U> MutationHooks for NoHooks<M, N, U>
where
    M: Send + Sync + Clone + 'static,
    N: Send + Sync + 'static,
    U: Send + Sync + 'static,
{
    type Model = M;
    type NewModel = N;
    type UpdateModel = U;
}

/// Tri-state sparse update value.
///
/// `Patch<T>` distinguishes between "field not mentioned" ([`Unchanged`](Patch::Unchanged)),
/// "field explicitly set" ([`Set`](Patch::Set)), and "field explicitly cleared"
/// ([`Clear`](Patch::Clear), mapping to SQL `NULL`).
///
/// This is the building block for partial-update (PATCH) payloads where
/// omitting a field means "leave it alone" rather than "set it to its
/// default".
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub enum Patch<T> {
    /// The field was not included in the update payload.
    #[default]
    Unchanged,
    /// The field was explicitly set to a new value.
    Set(T),
    /// The field was explicitly cleared (maps to SQL `NULL`).
    Clear,
}

impl<T> Patch<T> {
    /// Returns `true` if the field was not included in the update.
    #[must_use]
    pub const fn is_unchanged(&self) -> bool {
        matches!(self, Self::Unchanged)
    }

    /// Returns `true` if the field was explicitly set to a new value.
    #[must_use]
    pub const fn is_set(&self) -> bool {
        matches!(self, Self::Set(_))
    }

    /// Returns `true` if the field was explicitly cleared.
    #[must_use]
    pub const fn is_clear(&self) -> bool {
        matches!(self, Self::Clear)
    }

    /// Returns a reference to the inner value if [`Set`](Patch::Set), or `None`.
    #[must_use]
    pub const fn as_set(&self) -> Option<&T> {
        match self {
            Self::Set(v) => Some(v),
            _ => None,
        }
    }

    /// Converts into a nested `Option`:
    ///
    /// - `Set(v)` -> `Some(Some(v))`
    /// - `Clear` -> `Some(None)`
    /// - `Unchanged` -> `None`
    #[must_use]
    pub fn into_option(self) -> Option<Option<T>> {
        match self {
            Self::Set(v) => Some(Some(v)),
            Self::Clear => Some(None),
            Self::Unchanged => None,
        }
    }
}

impl<T: Serialize> Serialize for Patch<T> {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        match self {
            Self::Unchanged | Self::Clear => serializer.serialize_none(),
            Self::Set(v) => v.serialize(serializer),
        }
    }
}

impl<'de, T: Deserialize<'de>> Deserialize<'de> for Patch<T> {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        // When this method is called, the field WAS present in the JSON.
        // Absent fields use the Default impl (→ Unchanged) via #[serde(default)].
        let opt: Option<T> = Option::deserialize(deserializer)?;
        Ok(opt.map_or_else(|| Self::Clear, Self::Set))
    }
}

// ── `Patch<T>` validator per-field trait impls (#1719) ───────────────
//
// The `#[repository(api = ...)]` macro generates an `UpdateModel` whose mutable
// fields are `Patch<T>`. So that the model's declarative `#[validate(...)]`
// rules are enforced on PATCH/PUT (returning a 422 with the same per-field
// error map as create), the generated `UpdateModel` derives
// `validator::Validate` and carries the field `#[validate]` attributes. That
// derive expands to per-field calls like `self.title.validate_length(..)`,
// so `Patch<T>` must implement validator's per-field traits.
//
// These impls mirror validator's own `Option<T>` impls: an absent field
// (`Unchanged`/`Clear`) is skipped — it behaves like `None` and always passes —
// while `Set(v)` delegates to the inner value's rule. `Patch` is a local type,
// so implementing these foreign traits raises no orphan-rule issue.
//
// Only the *declarative, single-field* validators are implemented.
// `must_match`/`nested`/`custom` are intentionally omitted: they are
// meaningless or ill-typed on a tri-state patch field. `required` IS implemented
// (below), but with distinct, non-skip semantics: unlike the other rules, an
// absent field is not uniformly "pass" — `Clear` (explicit null on a required
// field) must FAIL so a PATCH/PUT cannot violate the model's `required` contract
// by nulling the column. `ValidateDoesNotContain`
// is deliberately NOT implemented here — validator provides it automatically via
// its blanket `impl<T: ValidateContains> ValidateDoesNotContain for T`, which
// covers `Patch<T>` through the `ValidateContains` impl below (a manual impl
// would collide with that blanket). `ValidateCreditCard` (validator's `card`
// feature) and `ValidateNonControlCharacter` (its `unic` feature) are not
// exported under this workspace's `validator` feature set, so they are omitted.

impl<T: validator::ValidateLength<u64>> validator::ValidateLength<u64> for Patch<T> {
    fn length(&self) -> Option<u64> {
        match self {
            Self::Set(v) => validator::ValidateLength::length(v),
            _ => None,
        }
    }
}

impl<N, T: validator::ValidateRange<N>> validator::ValidateRange<N> for Patch<T> {
    fn greater_than(&self, max: N) -> Option<bool> {
        match self {
            Self::Set(v) => validator::ValidateRange::greater_than(v, max),
            _ => None,
        }
    }

    fn less_than(&self, min: N) -> Option<bool> {
        match self {
            Self::Set(v) => validator::ValidateRange::less_than(v, min),
            _ => None,
        }
    }
}

impl<T: validator::ValidateEmail> validator::ValidateEmail for Patch<T> {
    fn as_email_string(&self) -> Option<Cow<'_, str>> {
        match self {
            Self::Set(v) => validator::ValidateEmail::as_email_string(v),
            _ => None,
        }
    }
}

impl<T: validator::ValidateUrl> validator::ValidateUrl for Patch<T> {
    fn as_url_string(&self) -> Option<Cow<'_, str>> {
        match self {
            Self::Set(v) => validator::ValidateUrl::as_url_string(v),
            _ => None,
        }
    }
}

impl<T: validator::ValidateContains> validator::ValidateContains for Patch<T> {
    fn validate_contains(&self, needle: &str) -> bool {
        match self {
            Self::Set(v) => validator::ValidateContains::validate_contains(v, needle),
            _ => true,
        }
    }
}

impl<T: validator::ValidateIp> validator::ValidateIp for Patch<T> {
    fn validate_ipv4(&self) -> bool {
        match self {
            Self::Set(v) => validator::ValidateIp::validate_ipv4(v),
            _ => true,
        }
    }

    fn validate_ipv6(&self) -> bool {
        match self {
            Self::Set(v) => validator::ValidateIp::validate_ipv6(v),
            _ => true,
        }
    }

    fn validate_ip(&self) -> bool {
        match self {
            Self::Set(v) => validator::ValidateIp::validate_ip(v),
            _ => true,
        }
    }
}

impl<T: validator::ValidateRegex> validator::ValidateRegex for Patch<T> {
    fn validate_regex(&self, regex: impl validator::AsRegex) -> bool {
        match self {
            Self::Set(v) => validator::ValidateRegex::validate_regex(v, regex),
            _ => true,
        }
    }
}

// `required` has *tri-state* semantics that differ from the skip-on-absent rules
// above (#1719 / Codex P2). `required` is meaningful only on `Option`-typed model
// fields, whose `UpdateModel` field is `Patch<Option<T>>`, so the bound is
// `T: ValidateRequired` (satisfied by validator's `impl<T> ValidateRequired for
// Option<T>`). The derive calls `self.field.validate_required()`:
//   - `Unchanged` -> `true`: the field was omitted from the patch, so the
//     existing (non-null) value is kept — nothing to reject.
//   - `Clear`     -> `false`: an explicit JSON `null` on a required field would
//     write SQL `NULL`, violating the `required` contract — reject (422).
//   - `Set(v)`    -> delegate to the inner `Option<T>`: `Set(Some)` passes,
//     `Set(None)` fails (same as create).
impl<T: validator::ValidateRequired> validator::ValidateRequired for Patch<T> {
    fn validate_required(&self) -> bool {
        match self {
            Self::Unchanged => true,
            Self::Clear => false,
            Self::Set(v) => validator::ValidateRequired::validate_required(v),
        }
    }

    fn is_some(&self) -> bool {
        match self {
            Self::Set(v) => validator::ValidateRequired::is_some(v),
            _ => false,
        }
    }
}

/// Per-field before/after diff accessor for mutation hooks.
///
/// `FieldDiff<T>` holds the previous and proposed values for a single field,
/// allowing hook authors to inspect what changed and optionally override the
/// new value via [`set`](FieldDiff::set).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FieldDiff<T> {
    before: T,
    after: T,
}

impl<T: PartialEq> FieldDiff<T> {
    /// Create a new diff from before and after values.
    #[must_use]
    pub const fn new(before: T, after: T) -> Self {
        Self { before, after }
    }

    /// Reference to the value before the mutation.
    #[must_use]
    pub const fn before(&self) -> &T {
        &self.before
    }

    /// Reference to the (possibly overridden) value after the mutation.
    #[must_use]
    pub const fn after(&self) -> &T {
        &self.after
    }

    /// Returns `true` if the field value changed.
    #[must_use]
    pub fn changed(&self) -> bool {
        self.before != self.after
    }

    /// Returns `true` if the field value did not change.
    #[must_use]
    pub fn unchanged(&self) -> bool {
        self.before == self.after
    }

    /// Returns `true` if the field changed **and** the new value equals `value`.
    #[must_use]
    pub fn changed_to(&self, value: &T) -> bool {
        self.changed() && self.after == *value
    }

    /// Returns `true` if the field changed **and** the old value equals `value`.
    #[must_use]
    pub fn changed_from(&self, value: &T) -> bool {
        self.changed() && self.before == *value
    }

    /// Override the after value. Does not affect `before`.
    pub fn set(&mut self, value: T) {
        self.after = value;
    }
}

impl<T: PartialEq> FieldDiff<Option<T>> {
    /// Returns `true` if the field went from `None` to `Some`.
    #[must_use]
    pub const fn was_set(&self) -> bool {
        self.before.is_none() && self.after.is_some()
    }

    /// Returns `true` if the field went from `Some` to `None`.
    #[must_use]
    pub const fn was_cleared(&self) -> bool {
        self.before.is_some() && self.after.is_none()
    }
}

// ── UpdateDraft & DraftField ─────────────────────────────────────────

/// Merged before/after snapshot of a model for `before_update` hooks.
///
/// `UpdateDraft<T>` holds the original (`before`) and proposed (`after`)
/// state of a model. The `after` copy starts as a clone of `before` and
/// can be mutated via [`after_mut`](UpdateDraft::after_mut) or through
/// per-field [`DraftField`] accessors generated by `#[model]`.
///
/// # Usage
///
/// ```rust,ignore
/// let mut draft = UpdateDraft::new(existing_article);
/// // apply partial changes from the request …
/// draft.after_mut().title = new_title;
///
/// // per-field inspection via DraftField:
/// let title = DraftField::new(&draft.before().title, &mut draft.after_mut().title);
/// if title.changed() { /* … */ }
/// ```
#[derive(Debug, Clone)]
pub struct UpdateDraft<T: Clone> {
    /// The original (pre-mutation) model state.
    ///
    /// Public so that `#[model]`-generated per-field `DraftField` accessors
    /// can split-borrow `before` and `after` simultaneously.
    pub before: T,
    /// The proposed (post-mutation) model state.
    ///
    /// Public so that `#[model]`-generated per-field `DraftField` accessors
    /// can split-borrow `before` and `after` simultaneously.
    pub after: T,
}

impl<T: Clone> UpdateDraft<T> {
    /// Create a new draft from the current model state.
    ///
    /// Clones `before` into `after` so that `after` starts as an
    /// identical copy that can be selectively mutated.
    #[must_use]
    pub fn new(before: T) -> Self {
        let after = before.clone();
        Self { before, after }
    }

    /// Create a draft with explicit before and after values.
    ///
    /// Useful in tests or when changes have already been applied.
    #[must_use]
    pub const fn new_with_changes(before: T, after: T) -> Self {
        Self { before, after }
    }

    /// Reference to the original (pre-mutation) model.
    #[must_use]
    pub const fn before(&self) -> &T {
        &self.before
    }

    /// Reference to the proposed (post-mutation) model.
    #[must_use]
    pub const fn after(&self) -> &T {
        &self.after
    }

    /// Mutable reference to the proposed (post-mutation) model.
    ///
    /// Use this to apply changes before the update is persisted.
    #[must_use]
    pub const fn after_mut(&mut self) -> &mut T {
        &mut self.after
    }

    /// Consume the draft and return the proposed model.
    #[must_use]
    pub fn into_after(self) -> T {
        self.after
    }
}

/// Borrowing per-field accessor into an [`UpdateDraft`].
///
/// `DraftField` borrows `before` immutably and `after` mutably from the
/// parent draft. Because each `DraftField` is a temporary that drops at
/// statement end, you can inspect and mutate fields one at a time without
/// running into overlapping borrow issues:
///
/// ```rust,ignore
/// // generated by #[model]:
/// draft.status().changed_to(&Status::Published);
/// draft.title().set("New title".into());
/// ```
///
/// # Lifetime
///
/// `'a` ties the field references back to the `UpdateDraft` they came
/// from. The borrow is released when the `DraftField` is dropped.
#[derive(Debug)]
pub struct DraftField<'a, T> {
    before: &'a T,
    after: &'a mut T,
}

impl<'a, T> DraftField<'a, T> {
    /// Create a new field accessor borrowing from a draft.
    #[must_use]
    pub const fn new(before: &'a T, after: &'a mut T) -> Self {
        Self { before, after }
    }

    /// Reference to the original (pre-mutation) field value.
    #[must_use]
    pub const fn before(&self) -> &T {
        self.before
    }

    /// Reference to the proposed (post-mutation) field value.
    #[must_use]
    pub const fn after(&self) -> &T {
        self.after
    }

    /// Override the proposed value for this field.
    pub fn set(&mut self, value: T) {
        *self.after = value;
    }
}

impl<T: PartialEq> DraftField<'_, T> {
    /// Returns `true` if the field value changed.
    #[must_use]
    pub fn changed(&self) -> bool {
        self.before != self.after
    }

    /// Returns `true` if the field value did not change.
    #[must_use]
    pub fn unchanged(&self) -> bool {
        self.before == self.after
    }

    /// Returns `true` if the field changed **and** the new value equals `value`.
    #[must_use]
    pub fn changed_to(&self, value: &T) -> bool {
        self.changed() && *self.after == *value
    }

    /// Returns `true` if the field changed **and** the old value equals `value`.
    #[must_use]
    pub fn changed_from(&self, value: &T) -> bool {
        self.changed() && *self.before == *value
    }
}

impl<T: PartialEq> DraftField<'_, Option<T>> {
    /// Returns `true` if the field went from `None` to `Some`.
    #[must_use]
    pub const fn was_set(&self) -> bool {
        self.before.is_none() && self.after.is_some()
    }

    /// Returns `true` if the field went from `Some` to `None`.
    #[must_use]
    pub const fn was_cleared(&self) -> bool {
        self.before.is_some() && self.after.is_none()
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // ── Patch tests ──────────────────────────────────────────────

    #[test]
    fn patch_unchanged_is_default() {
        let p: Patch<String> = Patch::default();
        assert!(p.is_unchanged());
        assert!(!p.is_set());
        assert!(!p.is_clear());
    }

    #[test]
    fn patch_set_holds_value() {
        let p = Patch::Set("hello");
        assert!(p.is_set());
        assert!(!p.is_unchanged());
        assert!(!p.is_clear());
        assert_eq!(p.as_set(), Some(&"hello"));
    }

    #[test]
    fn patch_clear_is_clear() {
        let p: Patch<i32> = Patch::Clear;
        assert!(p.is_clear());
        assert!(!p.is_set());
        assert!(!p.is_unchanged());
    }

    #[test]
    fn patch_into_option_set() {
        assert_eq!(Patch::Set(42).into_option(), Some(Some(42)));
    }

    #[test]
    fn patch_into_option_clear() {
        assert_eq!(Patch::<i32>::Clear.into_option(), Some(None));
    }

    #[test]
    fn patch_into_option_unchanged() {
        assert_eq!(Patch::<i32>::Unchanged.into_option(), None);
    }

    // ── Patch validator-trait tests (#1719) ─────────────────────
    //
    // `Patch<T>` mirrors validator's `Option<T>` impls: an absent field
    // (`Unchanged`/`Clear`) always passes; a `Set(v)` field delegates to the
    // inner value's rule. This lets the generated `UpdateModel` derive
    // `validator::Validate` and enforce `#[validate(...)]` on PATCH/PUT.

    #[test]
    fn patch_validate_length_set_delegates_to_inner() {
        use validator::ValidateLength;
        // `Set` with an empty string fails a `length(min = 1)` rule …
        assert!(!Patch::Set(String::new()).validate_length(Some(1), None, None));
        // … while a `Set` with a satisfying value passes.
        assert!(Patch::Set(String::from("ok")).validate_length(Some(1), None, None));
    }

    #[test]
    fn patch_validate_length_absent_passes() {
        use validator::ValidateLength;
        // Absent variants behave like `None`: the rule is skipped (passes).
        assert!(Patch::<String>::Unchanged.validate_length(Some(1), None, None));
        assert!(Patch::<String>::Clear.validate_length(Some(1), None, None));
    }

    // `required` has tri-state semantics (#1719 / Codex P2): unlike the
    // skip-on-absent rules, `Clear` and `Set(None)` must FAIL so a PATCH/PUT
    // cannot null a `#[validate(required)]` column; `Unchanged` skips.
    #[test]
    fn patch_validate_required_unchanged_passes() {
        use validator::ValidateRequired;
        assert!(Patch::<Option<String>>::Unchanged.validate_required());
    }

    #[test]
    fn patch_validate_required_clear_fails() {
        use validator::ValidateRequired;
        assert!(!Patch::<Option<String>>::Clear.validate_required());
    }

    #[test]
    fn patch_validate_required_set_some_passes() {
        use validator::ValidateRequired;
        assert!(Patch::Set(Some(String::from("x"))).validate_required());
    }

    #[test]
    fn patch_validate_required_set_none_fails() {
        use validator::ValidateRequired;
        assert!(!Patch::<Option<String>>::Set(None).validate_required());
    }

    // ── FieldDiff tests ──────────────────────────────────────────

    #[test]
    fn field_diff_unchanged() {
        let diff = FieldDiff::new(1, 1);
        assert!(diff.unchanged());
        assert!(!diff.changed());
    }

    #[test]
    fn field_diff_changed() {
        let diff = FieldDiff::new(1, 2);
        assert!(diff.changed());
    }

    #[test]
    fn field_diff_changed_to() {
        let diff = FieldDiff::new(1, 2);
        assert!(diff.changed_to(&2));
    }

    #[test]
    fn field_diff_changed_from() {
        let diff = FieldDiff::new(1, 2);
        assert!(diff.changed_from(&1));
    }

    #[test]
    fn field_diff_set_updates_after() {
        let mut diff = FieldDiff::new(1, 1);
        assert!(diff.unchanged());
        diff.set(5);
        assert!(diff.changed());
        assert_eq!(diff.after(), &5);
        assert_eq!(diff.before(), &1);
    }

    #[test]
    fn field_diff_option_was_set() {
        let diff = FieldDiff::new(None, Some(42));
        assert!(diff.was_set());
        let diff2 = FieldDiff::new(Some(42), Some(42));
        assert!(!diff2.was_set());
        let diff3 = FieldDiff::new(None::<i32>, None);
        assert!(!diff3.was_set());
        let diff4 = FieldDiff::new(Some(42), None);
        assert!(!diff4.was_set());
    }

    #[test]
    fn field_diff_option_was_cleared() {
        let diff = FieldDiff::new(Some(42), None);
        assert!(diff.was_cleared());
        let diff2 = FieldDiff::new(Some(42), Some(42));
        assert!(!diff2.was_cleared());
        let diff3 = FieldDiff::new(None::<i32>, None);
        assert!(!diff3.was_cleared());
        let diff4 = FieldDiff::new(None, Some(42));
        assert!(!diff4.was_cleared());
    }

    // ── MutationOp tests ────────────────────────────────────────────

    #[test]
    fn mutation_op_as_str() {
        assert_eq!(MutationOp::Create.as_str(), "create");
        assert_eq!(MutationOp::Update.as_str(), "update");
        assert_eq!(MutationOp::Delete.as_str(), "delete");
    }

    #[test]
    fn mutation_op_display() {
        assert_eq!(format!("{}", MutationOp::Create), "create");
    }

    // ── MutationContext tests ───────────────────────────────────────

    #[tokio::test]
    async fn mutation_context_auto_populates() {
        // Construct inside an (empty) request scope so `actor` is deterministically
        // `None`: an in-scope read never consults the process-global default actor,
        // which a concurrent test (`current::…default_actor_is_used_only_out_of_scope`)
        // may transiently have set. Avoids a test-isolation race on that global.
        crate::current::scope_request(async {
            let ctx = MutationContext::new(MutationOp::Create);
            assert!(ctx.actor.is_none());
            assert!(ctx.request_id.is_some());
            // UUID v4 format: 8-4-4-4-12 = 36 chars
            assert_eq!(ctx.request_id.as_ref().unwrap().len(), 36);
            assert!(matches!(ctx.op, MutationOp::Create));
            assert!(ctx.invalidate_keys.is_empty());
        })
        .await;
    }

    #[test]
    fn mutation_context_invalidate_pushes_key() {
        let mut ctx = MutationContext::new(MutationOp::Create);
        assert!(ctx.invalidate_keys.is_empty());
        ctx.invalidate("cache:key");
        assert_eq!(ctx.invalidate_keys, vec!["cache:key".to_string()]);
    }

    #[test]
    fn mutation_context_with_actor() {
        let mut ctx = MutationContext::new(MutationOp::Update);
        ctx.actor = Some("user-123".into());
        assert_eq!(ctx.actor.as_deref(), Some("user-123"));
    }

    #[tokio::test]
    async fn mutation_context_seeds_actor_from_ambient_scope() {
        // Inside an (empty) request scope the constructor yields `None`
        // deterministically — an in-scope read never consults the process-global
        // default actor a concurrent test may transiently have set (isolation).
        crate::current::scope_request(async {
            assert!(MutationContext::new(MutationOp::Create).actor.is_none());
        })
        .await;

        // Inside `with_actor(...)` the constructor auto-populates the actor.
        crate::current::with_actor("u1", async {
            let ctx = MutationContext::new(MutationOp::Create);
            assert_eq!(ctx.actor.as_deref(), Some("u1"));
        })
        .await;
    }

    #[test]
    fn mutation_context_carries_scoped_idempotency_key() {
        let mut ctx = MutationContext::new(MutationOp::Create);
        assert!(ctx.idempotency_key.is_none());

        ctx.set_idempotency_key("v2:scoped-http-key");

        assert_eq!(ctx.idempotency_key.as_deref(), Some("v2:scoped-http-key"));
    }

    #[test]
    fn mutation_context_deserializes_without_idempotency_key() {
        let ctx: MutationContext = serde_json::from_value(serde_json::json!({
            "op": "Create",
            "actor": null,
            "request_id": "request-1",
            "now": "2026-05-17T00:00:00Z",
            "invalidate_keys": []
        }))
        .expect("old durable hook payloads should deserialize");

        assert!(ctx.idempotency_key.is_none());
    }

    // ── MutationHooks / NoHooks tests ───────────────────────────────

    #[tokio::test]
    async fn no_hooks_all_methods_are_noop() {
        let hooks: NoHooks<(), (), ()> = NoHooks::default();
        let mut ctx = MutationContext::new(MutationOp::Create);
        let mut new_model = ();
        let model = ();
        let mut draft = UpdateDraft::new(());

        assert!(hooks.before_create(&mut ctx, &mut new_model).await.is_ok());
        assert!(hooks.before_update(&mut ctx, &mut draft).await.is_ok());
        assert!(hooks.before_delete(&mut ctx, &model).await.is_ok());
        assert!(hooks.after_create(&mut ctx, &model).await.is_ok());
        assert!(hooks.after_update(&mut ctx, &model).await.is_ok());
    }

    #[tokio::test]
    async fn no_hooks_commit_variants_are_noop() {
        // after_*_commit variants must also be no-ops on NoHooks
        let hooks: NoHooks<(), (), ()> = NoHooks::default();
        let mut ctx = MutationContext::new(MutationOp::Create);
        let model = ();

        assert!(
            hooks.after_create_commit(&mut ctx, &model).await.is_ok(),
            "after_create_commit must default to Ok(())"
        );
        assert!(
            hooks.after_update_commit(&mut ctx, &model).await.is_ok(),
            "after_update_commit must default to Ok(())"
        );
        assert!(
            hooks.after_delete_commit(&mut ctx, &model).await.is_ok(),
            "after_delete_commit must default to Ok(())"
        );
    }

    #[tokio::test]
    async fn custom_hooks_can_override_commit_variants() {
        use std::sync::Arc;
        use std::sync::atomic::{AtomicU32, Ordering};

        static CALLS: AtomicU32 = AtomicU32::new(0);

        #[derive(Clone, Default)]
        struct CountingHooks;

        impl MutationHooks for CountingHooks {
            type Model = ();
            type NewModel = ();
            type UpdateModel = ();

            async fn after_create_commit(
                &self,
                _ctx: &mut MutationContext,
                _record: &Self::Model,
            ) -> AutumnResult<()> {
                CALLS.fetch_add(1, Ordering::SeqCst);
                Ok(())
            }

            async fn after_update_commit(
                &self,
                _ctx: &mut MutationContext,
                _record: &Self::Model,
            ) -> AutumnResult<()> {
                CALLS.fetch_add(1, Ordering::SeqCst);
                Ok(())
            }

            async fn after_delete_commit(
                &self,
                _ctx: &mut MutationContext,
                _record: &Self::Model,
            ) -> AutumnResult<()> {
                CALLS.fetch_add(1, Ordering::SeqCst);
                Ok(())
            }
        }

        CALLS.store(0, Ordering::SeqCst);
        let hooks = CountingHooks;
        let mut ctx = MutationContext::new(MutationOp::Create);
        let model = ();

        hooks.after_create_commit(&mut ctx, &model).await.unwrap();
        hooks.after_update_commit(&mut ctx, &model).await.unwrap();
        hooks.after_delete_commit(&mut ctx, &model).await.unwrap();

        assert_eq!(CALLS.load(Ordering::SeqCst), 3);
        let _ = Arc::new(CountingHooks); // ensure Arc usage works (Clone check)
    }

    // ── Patch serde tests ──────────────────────────────────────────

    #[test]
    fn patch_serde_set_roundtrip() {
        let p = Patch::Set(42);
        let json = serde_json::to_string(&p).unwrap();
        assert_eq!(json, "42");
        let back: Patch<i32> = serde_json::from_str(&json).unwrap();
        assert_eq!(back, Patch::Set(42));
    }

    #[test]
    fn patch_serde_clear_serializes_as_null() {
        let p: Patch<i32> = Patch::Clear;
        let json = serde_json::to_string(&p).unwrap();
        assert_eq!(json, "null");
    }

    #[test]
    fn patch_serde_null_deserializes_as_clear() {
        let p: Patch<i32> = serde_json::from_str("null").unwrap();
        assert_eq!(p, Patch::Clear);
    }

    #[test]
    fn patch_serde_absent_field_is_unchanged() {
        #[derive(Deserialize, PartialEq, Debug)]
        struct Payload {
            #[serde(default)]
            name: Patch<String>,
            #[serde(default)]
            age: Patch<i32>,
        }
        let p: Payload = serde_json::from_str(r#"{"name": "Alice"}"#).unwrap();
        assert_eq!(p.name, Patch::Set("Alice".to_string()));
        assert_eq!(p.age, Patch::Unchanged);
    }

    #[test]
    fn patch_serde_explicit_null_is_clear() {
        #[derive(Deserialize, PartialEq, Debug)]
        struct Payload {
            #[serde(default)]
            name: Patch<String>,
        }
        let p: Payload = serde_json::from_str(r#"{"name": null}"#).unwrap();
        assert_eq!(p.name, Patch::Clear);
    }

    // ── UpdateDraft tests ───────────────────────────────────────────

    #[test]
    fn update_draft_before_after() {
        let draft = UpdateDraft::new_with_changes("old".to_string(), "new".to_string());
        assert_eq!(draft.before(), "old");
        assert_eq!(draft.after(), "new");
    }

    #[test]
    fn update_draft_into_after() {
        let draft = UpdateDraft::new_with_changes(1, 2);
        assert_eq!(draft.into_after(), 2);
    }

    #[test]
    fn update_draft_new_clones() {
        let draft = UpdateDraft::new(42);
        assert_eq!(draft.before(), &42);
        assert_eq!(draft.after(), &42);
    }

    #[test]
    fn update_draft_after_mut() {
        let mut draft = UpdateDraft::new_with_changes(1, 2);
        *draft.after_mut() = 3;
        assert_eq!(draft.after(), &3);
    }

    // ── DraftField tests ────────────────────────────────────────────

    #[test]
    fn draft_field_before_after() {
        let before = 1;
        let mut after = 2;
        let field = DraftField::new(&before, &mut after);
        assert_eq!(field.before(), &1);
        assert_eq!(field.after(), &2);
    }

    #[test]
    fn draft_field_changed() {
        let before = 1;
        let mut after = 2;
        let field = DraftField::new(&before, &mut after);
        assert!(field.changed());
        assert!(!field.unchanged());
    }

    #[test]
    fn draft_field_unchanged() {
        let before = 1;
        let mut after = 1;
        let field = DraftField::new(&before, &mut after);
        assert!(field.unchanged());
        assert!(!field.changed());
    }

    #[test]
    fn draft_field_changed_to() {
        let before = "draft".to_string();
        let mut after = "published".to_string();
        let field = DraftField::new(&before, &mut after);
        assert!(field.changed_to(&"published".to_string()));
        assert!(!field.changed_to(&"draft".to_string()));
    }

    #[test]
    fn draft_field_changed_from() {
        let before = "draft".to_string();
        let mut after = "published".to_string();
        let field = DraftField::new(&before, &mut after);
        assert!(field.changed_from(&"draft".to_string()));
        assert!(!field.changed_from(&"published".to_string()));
    }

    #[test]
    fn draft_field_set_mutates_after() {
        let before = 10;
        let mut after = 10;
        {
            let mut field = DraftField::new(&before, &mut after);
            assert!(field.unchanged());
            field.set(20);
            assert!(field.changed());
            assert_eq!(field.after(), &20);
        }
        // Verify mutation propagated to the original variable
        assert_eq!(after, 20);
    }

    #[test]
    fn draft_field_option_was_set() {
        let before: Option<i32> = None;
        let mut after: Option<i32> = Some(42);
        let field = DraftField::new(&before, &mut after);
        assert!(field.was_set());
        assert!(!field.was_cleared());

        let before2: Option<i32> = Some(42);
        let mut after2: Option<i32> = Some(42);
        let field2 = DraftField::new(&before2, &mut after2);
        assert!(!field2.was_set());

        let before3: Option<i32> = None;
        let mut after3: Option<i32> = None;
        let field3 = DraftField::new(&before3, &mut after3);
        assert!(!field3.was_set());

        let before4: Option<i32> = Some(42);
        let mut after4: Option<i32> = None;
        let field4 = DraftField::new(&before4, &mut after4);
        assert!(!field4.was_set());
    }

    #[test]
    fn draft_field_option_was_cleared() {
        let before: Option<i32> = Some(42);
        let mut after: Option<i32> = None;
        let field = DraftField::new(&before, &mut after);
        assert!(field.was_cleared());
        assert!(!field.was_set());

        let before2: Option<i32> = Some(42);
        let mut after2: Option<i32> = Some(42);
        let field2 = DraftField::new(&before2, &mut after2);
        assert!(!field2.was_cleared());

        let before3: Option<i32> = None;
        let mut after3: Option<i32> = None;
        let field3 = DraftField::new(&before3, &mut after3);
        assert!(!field3.was_cleared());

        let before4: Option<i32> = None;
        let mut after4: Option<i32> = Some(42);
        let field4 = DraftField::new(&before4, &mut after4);
        assert!(!field4.was_cleared());
    }
}