ai-memory 0.7.0

// Copyright 2026 AlphaOne LLC
// SPDX-License-Identifier: Apache-2.0
//
// v0.7 Track G — Task G5: chain ordering + first-deny-wins short-circuit.
//
// G3 (PR #567) shipped the per-hook `HookExecutor` (`ExecExecutor`,
// `DaemonExecutor`, `ExecutorRegistry`). G4 (PR #570) shipped the
// `HookDecision` four-variant contract (`Allow / Modify(MemoryDelta)
// / Deny / AskUser`). G5 stitches them together: when several
// `[[hook]]` blocks subscribe to the same event, fire them in
// deterministic priority-descending order, threading a
// possibly-mutated payload through the chain, halting on the first
// `Deny`, and queueing every `AskUser` for the operator surface.
//
// # Ordering
//
// `HookChain::new` sorts the configured hooks by `priority`
// descending. Ties are broken by *insertion order* — i.e. the order
// the entries appear in `hooks.toml`, which `HookConfig::load_from_file`
// already preserves. `Vec::sort_by` is stable, so feeding it a
// `Vec<HookConfig>` in load order yields the documented behaviour
// without any extra bookkeeping.
//
// # Decision merging
//
// The chain runs a small state machine over the per-hook decisions:
//
//   * `Allow`   — keep iterating with the same payload.
//   * `Modify`  — merge the `MemoryDelta` into the in-flight payload
//                 (top-level `Object` keys overwrite; nested fields
//                 are replaced wholesale because `MemoryDelta` itself
//                 has no nested optional sub-bags) and set the
//                 `modified` flag so the final result widens to
//                 `ModifiedAllow`. The *next* hook in the chain sees
//                 the merged payload, matching the prompt's
//                 "later hooks see the latest delta" requirement.
//   * `Deny`    — short-circuit. The chain never invokes the rest of
//                 the hooks. Even if earlier hooks queued AskUser
//                 prompts, the operator-facing answer is `Deny`
//                 (compliance trumps operator UX).
//   * `AskUser` — push the prompt onto the queue and continue. A
//                 chain that ends with at least one queued AskUser
//                 *and no clear Allow / Modify win* surfaces as
//                 `ChainResult::AskUser`. If a *subsequent* hook
//                 returns `Allow` or `Modify`, that decision wins —
//                 matching the prompt's "first non-AskUser decision
//                 continues" semantics.
//
// "First non-AskUser decision continues" is implemented as: AskUser
// never overrides a later Allow / Modify; AskUser only "wins" when
// every later hook also returned AskUser (or when the chain was
// AskUser-only to begin with).
//
// # Crash handling — `FailMode`
//
// Every `HookConfig` now carries a `fail_mode: FailMode` field
// (G5 addition; defaults to `Open` so G3-era configs keep their
// behaviour). When `executor.fire()` returns an `ExecutorError`
// (spawn failure, decode failure, timeout, daemon-unavailable, …):
//
//   * `FailMode::Open` (default) — `tracing::warn!` the error and
//     treat the failed fire as `Allow`. Continue the chain.
//   * `FailMode::Closed` — `tracing::warn!` the error and convert
//     it to `ChainResult::Deny { reason: <executor-error display>,
//     code: 503 }`. Short-circuit the chain.
//
// 503 is the "service unavailable" HTTP status; it mirrors the
// chain semantics ("we couldn't run the gate, refuse the request").
// G7+ will wire this onto the actual API surface.
//
// # G6 — per-event-class deadline (this PR)
//
// `HookChain::fire` now computes a *chain* deadline at entry:
// `chain_deadline = Instant::now() + class_deadline_for_event(event)`.
// Before each hook fires, the chain derives the per-hook budget as
// `min(chain_remaining, hook.timeout_ms)` and clones a shrunk
// `HookConfig` into a one-off executor for that fire (the executor
// honours `HookConfig.timeout_ms` already; the chain only needs to
// shrink the knob). If the chain deadline has *already* passed
// before a hook fires, that hook is skipped, the chain bumps
// `timeouts::record_timeout_violation()`, and continues fail-open
// `Allow` per `FailMode::Open`. A `FailMode::Closed` hook that
// runs out of chain budget converts to a chain-level `Deny` with
// reason `chain class deadline exhausted` and code 504 — the HTTP
// "gateway timeout" status, which mirrors the chain semantics
// ("we couldn't run the gate, refuse the request as if upstream
// timed out").
//
// # Out of scope
//
// * Wiring at the actual memory operation points (`db::insert`,
//   `db::recall`, …) — that's G7+.
// * `dispatch_event` / subscription integration is a thin
//   convenience wrapper here (`dispatch_event_with_hooks`); the
//   real wire-in at MCP / handlers call sites lands later in the
//   epic.

use std::sync::Arc;
use std::time::Instant;

use serde_json::{Map, Value};

use super::config::{FailMode, HookConfig};
use super::decision::{HookDecision, is_pre_event};
use super::events::{EvictionEvent, HookEvent, MemoryDelta};
use super::executor::ExecutorRegistry;
use super::timeouts::{class_deadline_for_event, per_hook_budget_ms, record_timeout_violation};

// ---------------------------------------------------------------------------
// AskUserPrompt — operator-surface queue entry
// ---------------------------------------------------------------------------

/// One queued operator prompt. The chain runner accumulates these
/// when hooks return `HookDecision::AskUser` and the chain doesn't
/// terminate in `Deny` / clear `Allow`. The G7+ wiring layer will
/// fan these out to the operator surface (CLI / MCP / HTTP) and
/// resume the chain on the human's choice.
///
/// We keep this distinct from `HookDecision::AskUser` so the queue
/// representation can grow (correlation ids, hook origin tags, …)
/// without churning the wire-format enum the executor parses.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AskUserPrompt {
    /// The text shown to the operator. Verbatim from the hook's
    /// `prompt` field.
    pub prompt: String,
    /// The selectable options, in the order the hook listed them.
    pub options: Vec<String>,
    /// Optional default; the runner falls back to this on operator
    /// timeout.
    pub default: Option<String>,
    /// Path of the hook that queued the prompt. Lets the operator
    /// surface display "why am I being asked this?".
    pub origin_command: String,
}

// ---------------------------------------------------------------------------
// ChainResult — the outcome of running an entire chain
// ---------------------------------------------------------------------------

/// What the chain runner reports back to the dispatcher. Mirrors
/// `HookDecision`'s shape but at chain granularity:
///
///   * [`ChainResult::Allow`] — every hook in the chain returned
///     `Allow` (or the chain was empty).
///   * [`ChainResult::ModifiedAllow`] — at least one hook returned
///     `Modify`; the final merged delta is reported.
///   * [`ChainResult::Deny`] — a hook returned `Deny` (or a hook
///     errored under `FailMode::Closed`); the chain short-circuited.
///   * [`ChainResult::AskUser`] — the chain finished with at least
///     one queued operator prompt and no clear Allow / Modify win.
///
/// `Modify` is not a chain-level outcome on its own — every chain
/// either *also* finishes Allow (`ModifiedAllow`) or short-circuits
/// on `Deny`. The dispatcher applies the cumulative delta exactly
/// once when the chain returns `ModifiedAllow`.
///
/// #969 — `PartialEq` is now `derive`-able because `MemoryDelta`
/// derives `PartialEq` (see `hooks/events.rs`). Pre-#969 we
/// hand-rolled equality routed through `serde_json::to_value(...)`
/// on the (mistaken) premise that `serde_json::Value` was not
/// `PartialEq` — it IS. `MemoryDelta`'s `Option<f64>` blocks
/// `derive(Eq)` (f64 has only `PartialEq`) but not
/// `derive(PartialEq)`. The historical wrap-and-compare is gone.
#[derive(Debug, Clone, PartialEq)]
pub enum ChainResult {
    Allow,
    ModifiedAllow(MemoryDelta),
    Deny { reason: String, code: i32 },
    AskUser { queued: Vec<AskUserPrompt> },
}

// ---------------------------------------------------------------------------
// HookChain — priority-sorted, fire-in-order
// ---------------------------------------------------------------------------

/// Ordered set of hooks subscribed to a single event. The hooks are
/// sorted by `priority` descending at construction time; ties keep
/// their `hooks.toml` insertion order (`Vec::sort_by` is stable, so
/// feeding it a load-order vec gives the documented behaviour for
/// free).
///
/// The chain runner is a method on the chain rather than a free
/// function so callers can hold a chain across multiple fires
/// (e.g. one per event tag, built once on `hooks.toml` load and
/// reused across many request paths).
pub struct HookChain {
    hooks: Vec<HookConfig>,
}

impl HookChain {
    /// Build a chain from the hooks subscribed to `event`. The input
    /// vec is filtered to enabled entries matching `event` and then
    /// sorted by `priority` descending.
    ///
    /// Insertion order from `hooks.toml` is the secondary sort key
    /// (i.e. ties break in load order). `Vec::sort_by` is stable so
    /// no extra bookkeeping is needed — a load-order input gives the
    /// documented behaviour.
    #[must_use]
    pub fn for_event(all_hooks: &[HookConfig], event: HookEvent) -> Self {
        let mut hooks: Vec<HookConfig> = all_hooks
            .iter()
            .filter(|h| h.enabled && h.event == event)
            .cloned()
            .collect();
        // Stable sort: ties preserve original (hooks.toml) ordering.
        hooks.sort_by(|a, b| b.priority.cmp(&a.priority));
        Self { hooks }
    }

    /// Construct from an explicit, pre-filtered hook list. The list
    /// is still priority-sorted on the way in. Used by tests that
    /// want to bypass the `enabled` / `event` filter.
    #[must_use]
    pub fn new(mut hooks: Vec<HookConfig>) -> Self {
        hooks.sort_by(|a, b| b.priority.cmp(&a.priority));
        Self { hooks }
    }

    /// Returns the priority-sorted hook list. Useful for tests
    /// (asserting the ordering pass landed) and for the doctor
    /// surface (rendering the configured chain).
    #[must_use]
    pub fn hooks(&self) -> &[HookConfig] {
        &self.hooks
    }

    /// Run the chain. Iterates hooks in priority order, threads the
    /// possibly-mutated payload through, and short-circuits on the
    /// first `Deny`.
    ///
    /// `registry` is taken `&mut` because `ExecutorRegistry::get`
    /// inserts on cache miss. Once every hook in the chain has been
    /// fired at least once the registry is steady-state and a fully
    /// pre-warmed registry built via `ExecutorRegistry::from_hooks`
    /// makes this a read-only path.
    ///
    /// The future is `async` because each hook's `fire` is async;
    /// the chain itself does no extra work between fires beyond the
    /// in-memory delta merge.
    pub async fn fire(
        &self,
        event: HookEvent,
        payload: Value,
        registry: &mut ExecutorRegistry,
    ) -> ChainResult {
        let mut current_payload = payload;
        let mut accumulated_delta = MemoryDelta::default();
        let mut modified = false;
        let mut askuser_queue: Vec<AskUserPrompt> = Vec::new();

        // G6: stamp a chain-wide wall-clock ceiling at entry. Every
        // hook in the loop below has its per-hook timeout shrunk to
        // `min(chain_remaining, hook.timeout_ms)` so the *whole*
        // chain cannot blow the recall / write / index / transcript
        // budget the epic pins.
        let chain_deadline = Instant::now() + class_deadline_for_event(event);

        // Snapshot executor handles before the await loop so we hand
        // them out by `Arc<dyn HookExecutor>` and don't re-borrow the
        // registry across the await boundary. (Holding `&mut registry`
        // across an await would force every caller to single-thread.)
        let prepared: Vec<(HookConfig, Arc<dyn super::executor::HookExecutor>)> = self
            .hooks
            .iter()
            .map(|h| (h.clone(), registry.get(h)))
            .collect();

        for (cfg, executor) in prepared {
            // G6: derive the per-hook budget from what's left of the
            // chain deadline. `None` means the deadline already
            // passed — record a violation, treat the remaining hooks
            // per `fail_mode` (Open ⇒ Allow, Closed ⇒ Deny 504).
            let Some(budget_ms) =
                per_hook_budget_ms(chain_deadline, Instant::now(), cfg.timeout_ms)
            else {
                record_timeout_violation();
                match cfg.fail_mode {
                    FailMode::Open => {
                        tracing::warn!(
                            command = %cfg.command.display(),
                            event = ?event,
                            "hooks: chain class deadline exhausted before hook fire; \
                             fail_mode=open, treating as Allow"
                        );
                        continue;
                    }
                    FailMode::Closed => {
                        tracing::warn!(
                            command = %cfg.command.display(),
                            event = ?event,
                            "hooks: chain class deadline exhausted before hook fire; \
                             fail_mode=closed, denying"
                        );
                        return ChainResult::Deny {
                            reason: format!(
                                "hook {} skipped under fail_mode=closed: chain class deadline exhausted",
                                cfg.command.display()
                            ),
                            code: 504,
                        };
                    }
                }
            };

            // G6: enforce the (possibly-shrunk) per-hook budget at
            // the chain layer. The executor itself already honours
            // its configured `timeout_ms`, but the chain's view of
            // "remaining wall clock" can be tighter than that knob;
            // wrapping the fire here is what guarantees the class
            // ceiling holds even when ten hooks each carry a 1s
            // hook_timeout_ms but the class budget is 2s.
            let per_hook_deadline = std::time::Duration::from_millis(u64::from(budget_ms));
            let raced = tokio::time::timeout(
                per_hook_deadline,
                executor.fire(event, current_payload.clone()),
            )
            .await;

            let fire_result = match raced {
                Ok(inner) => inner,
                Err(_elapsed) => {
                    // Treat a chain-level timeout the same way the
                    // executor's own Timeout would surface — a single
                    // ExecutorError::Timeout, routed through fail_mode.
                    // The Err(Timeout) arm below records the violation
                    // (one record per trip — the executor's `timeout_ms`
                    // and our chain wrapper are racing on the *smaller*
                    // of the two, only one ever fires, no double-count).
                    Err(super::executor::ExecutorError::Timeout {
                        ms: u64::from(budget_ms),
                    })
                }
            };

            let decision = match fire_result {
                Ok(d) => d.degrade_modify_for_post_event(event),
                Err(e) => {
                    // G6: a Timeout from the executor counts as a
                    // violation too. The executor enforces
                    // `cfg.timeout_ms` and the chain wrapper
                    // enforces `min(chain_remaining, cfg.timeout_ms)`
                    // — only the smaller of the two ever fires on a
                    // given hook, so the two record paths are
                    // mutually exclusive (no double-count).
                    if matches!(e, super::executor::ExecutorError::Timeout { .. }) {
                        record_timeout_violation();
                    }
                    // Crash handling per `fail_mode`.
                    match cfg.fail_mode {
                        FailMode::Open => {
                            tracing::warn!(
                                command = %cfg.command.display(),
                                event = ?event,
                                error = %e,
                                "hooks: chain hook errored; fail_mode=open, treating as Allow"
                            );
                            HookDecision::Allow
                        }
                        FailMode::Closed => {
                            tracing::warn!(
                                command = %cfg.command.display(),
                                event = ?event,
                                error = %e,
                                "hooks: chain hook errored; fail_mode=closed, denying"
                            );
                            return ChainResult::Deny {
                                reason: format!(
                                    "hook {} errored under fail_mode=closed: {e}",
                                    cfg.command.display()
                                ),
                                code: 503,
                            };
                        }
                    }
                }
            };

            match decision {
                HookDecision::Allow => {
                    // Allow is the no-op continue. AskUser prompts
                    // queued by *earlier* hooks remain queued but do
                    // not win — Allow is a "first non-AskUser
                    // decision" winner per the prompt.
                    askuser_queue.clear();
                }
                HookDecision::Modify(modify_payload) => {
                    // Merge into the in-flight payload so the next
                    // hook sees the latest delta, *and* track the
                    // composed delta so the final result can report it.
                    apply_delta_to_payload(&mut current_payload, &modify_payload.delta);
                    merge_delta_into(&mut accumulated_delta, modify_payload.delta);
                    modified = true;
                    // Modify also overrides any earlier AskUser
                    // prompts — same "first non-AskUser wins" rule.
                    askuser_queue.clear();
                }
                HookDecision::Deny { reason, code } => {
                    return ChainResult::Deny { reason, code };
                }
                HookDecision::AskUser {
                    prompt,
                    options,
                    default,
                } => {
                    // Only valid on pre- events, but we don't degrade
                    // here — the dispatcher (G7+) decides what to do
                    // with an AskUser on a post- event. Today the
                    // only post-AskUser test path is "queued, but
                    // chain returns Allow" because no caller acts on
                    // the queue yet.
                    askuser_queue.push(AskUserPrompt {
                        prompt,
                        options,
                        default,
                        origin_command: cfg.command.display().to_string(),
                    });
                    // Continue: a *later* Allow / Modify will overwrite
                    // the queue (per the cleared-on-Allow path above).
                    // If every remaining hook also AskUsers (or the
                    // chain ends here), we emit ChainResult::AskUser.
                    let _ = is_pre_event(event); // tracing-only awareness; no behaviour change
                }
            }
        }

        if !askuser_queue.is_empty() {
            ChainResult::AskUser {
                queued: askuser_queue,
            }
        } else if modified {
            ChainResult::ModifiedAllow(accumulated_delta)
        } else {
            ChainResult::Allow
        }
    }
}

// ---------------------------------------------------------------------------
// Subscription integration — `dispatch_event_with_hooks`
// ---------------------------------------------------------------------------
//
// The G5 prompt asks for hooks to fire *before* webhook subscriptions
// for pre- events and *after* for post- events. v0.6's
// `subscriptions::dispatch_event` is a post-event-only API
// (`memory_store`, `memory_promote`, … all fire after the DB write),
// so the integration here is the post- side: run the hook chain
// *after* the subscription dispatch returns.
//
// Pre-event call sites do not yet exist on the dispatcher path —
// they'll land in G7+ when hooks are wired into `db::insert` /
// `db::recall` / etc. The function below covers the post- side and
// documents the pre- shape so the G7 implementer has a single
// place to look. Routing the actual MCP / handlers call sites into
// this convenience wrapper is left to the wiring tasks.

/// Convenience: dispatch the v0.6 webhook event AND fire the hook
/// chain for `event` in the order the G5 prompt mandates (subs
/// first for post-, hooks first for pre-).
///
/// `subscription_dispatch` is the closure the caller wires to
/// `crate::subscriptions::dispatch_event` (or
/// `dispatch_event_with_details`). Taking it as a closure keeps
/// this module free of any direct dependency on `rusqlite::Connection`
/// — the subscription module owns the DB handle, and the hooks
/// module stays a leaf.
///
/// Returns the chain result so the caller can decide whether to
/// proceed (Allow / ModifiedAllow / AskUser) or refuse (Deny). For
/// post- events the dispatcher should treat Deny as "log only" —
/// the side-effect already happened.
pub async fn dispatch_event_with_hooks<F>(
    event: HookEvent,
    payload: Value,
    chain: &HookChain,
    registry: &mut ExecutorRegistry,
    subscription_dispatch: F,
) -> ChainResult
where
    F: FnOnce(),
{
    if is_pre_event(event) {
        // Pre-: hooks run first. If the chain Denies, skip the
        // subscription dispatch entirely (the operation isn't
        // happening, so subscribers shouldn't see it).
        let result = chain.fire(event, payload, registry).await;
        if !matches!(result, ChainResult::Deny { .. }) {
            subscription_dispatch();
        }
        result
    } else {
        // Post-: subscriptions first (the side-effect already
        // happened, so subscribers see it unconditionally). Hooks
        // run after for observability / linking / etc.
        subscription_dispatch();
        chain.fire(event, payload, registry).await
    }
}

// ---------------------------------------------------------------------------
// G8 / R3-S1 — on_index_eviction fire helper + observer-channel sink
// ---------------------------------------------------------------------------
//
// `OnIndexEviction` is the only event whose canonical fire site
// (`src/hnsw.rs:insert` — the `MAX_ENTRIES`-triggered drain) sits
// below the hooks layer in the dependency graph. `VectorIndex`
// owns no `ExecutorRegistry` handle and threading one through
// the inner Mutex would touch every caller in the storage layer
// and serialize hook execution behind the hot-path lock.
//
// v0.7.0 R3-S1 closes the prior G8 "fire helper exists but not
// wired" gap with approach (b) from the original TODO: a
// channel-sink between `VectorIndex` and the hooks layer.
// `VectorIndex::set_eviction_sink` takes the send-half of an
// unbounded mpsc channel; the eviction path inside
// `VectorIndex::insert` pushes one [`EvictionEvent`] per evicted
// id (`Sender::send` is non-blocking on an unbounded channel).
// A background observer task owns the recv-half and fires
// `fire_on_index_eviction` off the hot path. The `Sender` push
// itself is a no-op when no sink is wired (CLI / test builds
// without a hooks pipeline) so eviction throughput is unaffected
// in those configurations.
//
// The observer task is `mode = "daemon"` semantics by construction:
// the eviction-trigger thread never blocks on hook execution, the
// recv-half is drained on a dedicated tokio task off the hot path,
// and slow hooks back-pressure only on themselves (the channel is
// unbounded).

/// Fire the `on_index_eviction` chain for `payload`.
///
/// Production callers reach this through the eviction-observer
/// task spawned by [`spawn_eviction_observer`]; the helper is
/// also called directly from `tests/hooks_executor_test.rs` to
/// exercise the wire shape end-to-end through a real subprocess
/// hook.
///
/// # Why a free function and not a method on `HookChain`
///
/// `HookChain::fire` already covers the generic event path. This
/// helper exists so callers can pass a typed [`EvictionEvent`]
/// instead of a `serde_json::Value` and have the JSON projection
/// happen here — keeping the hnsw layer free of any `serde_json`
/// import. It also gives us a single grep target for "where does
/// the eviction hook fire?".
pub async fn fire_on_index_eviction(
    chain: &HookChain,
    registry: &mut ExecutorRegistry,
    payload: EvictionEvent,
) -> ChainResult {
    let value = serde_json::to_value(&payload).unwrap_or_else(|_| Value::Null);
    chain
        .fire(HookEvent::OnIndexEviction, value, registry)
        .await
}

/// v0.7.0 R3-S1 — Spawn the eviction observer that bridges the
/// `VectorIndex` eviction-edge channel to the `on_index_eviction`
/// hook chain. Returns the send-half of an unbounded mpsc channel
/// caller must hand to [`crate::hnsw::VectorIndex::set_eviction_sink`].
///
/// The observer task takes ownership of `chain` (cloned via `Arc`)
/// and the `registry`; both are kept alive for the lifetime of the
/// recv-half. When the last `Sender` clone drops (typically when the
/// daemon shuts down and `VectorIndex` is dropped), the channel
/// closes and the observer task exits cleanly.
///
/// This is the canonical "daemon-mode" wire-in for the eviction
/// hook: the hot-path eviction edge never blocks waiting for hook
/// execution; the observer task drains the queue at its own pace.
///
/// # Hot-path posture
///
/// The send side (`Sender::send` on an unbounded channel) never
/// blocks. A back-logged hook (slow subprocess, daemon hook
/// stalled) accumulates events in the channel but does NOT slow
/// `VectorIndex::insert`. This is the intended trade-off — eviction
/// is rare (only fires past the 100k cap) and operators care more
/// about not coupling recall latency to hook subscriber health than
/// about bounded queue memory.
pub fn spawn_eviction_observer(
    chain: Arc<HookChain>,
    mut registry: ExecutorRegistry,
) -> std::sync::mpsc::Sender<EvictionEvent> {
    let (tx, rx) = std::sync::mpsc::channel::<EvictionEvent>();
    // We keep the recv side on a std mpsc (so the hot-path producer
    // can be sync-only). A tiny bridge converts std-recv -> async by
    // delegating the blocking recv to a `spawn_blocking` task; each
    // observed payload re-enters the async chain via
    // `fire_on_index_eviction`. This is the canonical pattern for
    // adapting a sync producer to an async consumer in tokio.
    let rx = std::sync::Mutex::new(rx);
    let rx = Arc::new(rx);
    tokio::spawn(async move {
        loop {
            let rx_clone = Arc::clone(&rx);
            let next = tokio::task::spawn_blocking(move || {
                let guard = rx_clone.lock().expect("eviction observer rx mutex");
                guard.recv()
            })
            .await;
            match next {
                Ok(Ok(payload)) => {
                    let _ = fire_on_index_eviction(&chain, &mut registry, payload).await;
                }
                // Either the JoinHandle errored (panic) or the
                // sender side dropped — both terminate the observer.
                Ok(Err(_)) | Err(_) => break,
            }
        }
    });
    tx
}

// ---------------------------------------------------------------------------
// Delta merging helpers
// ---------------------------------------------------------------------------

/// Apply a [`MemoryDelta`] over `payload` so the next hook in the
/// chain sees the post-modify view.
///
/// The payload is a `serde_json::Value` (the wire shape sent to the
/// child); the delta is a typed struct with every field optional.
/// We translate the delta to a JSON object and overlay it onto the
/// payload at the top level — `Some(_)` fields overwrite, `None`
/// fields leave the payload untouched (the `serde(skip_serializing_if
/// = "Option::is_none")` bias on `MemoryDelta` makes this trivially
/// the right shape).
///
/// If `payload` is not a JSON object we replace it wholesale with
/// the delta object. That matches the "delta wins on conflict"
/// semantics callers expect; a non-object payload is a programmer
/// error in the caller, not the hook.
fn apply_delta_to_payload(payload: &mut Value, delta: &MemoryDelta) {
    let delta_value = serde_json::to_value(delta).unwrap_or_else(|_| Value::Object(Map::new()));
    let Value::Object(delta_obj) = delta_value else {
        return;
    };
    if !payload.is_object() {
        *payload = Value::Object(delta_obj);
        return;
    }
    // Safe: just checked is_object().
    let payload_obj = payload.as_object_mut().expect("checked is_object");
    for (k, v) in delta_obj {
        payload_obj.insert(k, v);
    }
}

/// Merge `incoming` into the accumulator. `Some(_)` in `incoming`
/// overwrites the accumulator's same-name field; `None` leaves it.
///
/// We hand-roll this rather than reusing `apply_delta_to_payload` on
/// a JSON-roundtripped accumulator because the typed surface is
/// what the chain reports back via `ChainResult::ModifiedAllow` —
/// callers want a `MemoryDelta`, not a `Value`.
fn merge_delta_into(acc: &mut MemoryDelta, incoming: MemoryDelta) {
    if incoming.tier.is_some() {
        acc.tier = incoming.tier;
    }
    if incoming.namespace.is_some() {
        acc.namespace = incoming.namespace;
    }
    if incoming.title.is_some() {
        acc.title = incoming.title;
    }
    if incoming.content.is_some() {
        acc.content = incoming.content;
    }
    if incoming.tags.is_some() {
        acc.tags = incoming.tags;
    }
    if incoming.priority.is_some() {
        acc.priority = incoming.priority;
    }
    if incoming.confidence.is_some() {
        acc.confidence = incoming.confidence;
    }
    if incoming.source.is_some() {
        acc.source = incoming.source;
    }
    if incoming.expires_at.is_some() {
        acc.expires_at = incoming.expires_at;
    }
    if incoming.metadata.is_some() {
        acc.metadata = incoming.metadata;
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use crate::hooks::config::{FailMode, HookMode};
    use crate::hooks::decision::ModifyPayload;
    use crate::hooks::executor::{
        ExecutorError, ExecutorMetrics, HookExecutor, Result as ExecutorResult,
    };
    use serde_json::json;
    use std::path::PathBuf;
    use std::pin::Pin;
    use std::sync::Mutex;
    use std::sync::atomic::{AtomicUsize, Ordering};

    // ---- Test executor: deterministic, in-process replacement ----------------
    //
    // We can't spawn real subprocesses in unit tests (the integration
    // tests in `tests/hooks_executor_test.rs` cover that). The chain
    // logic is decoupled from the executor implementation via the
    // `HookExecutor` trait, so we plug a `MockExecutor` that returns
    // a scripted decision (or error) per fire and counts how often it
    // was invoked.
    //
    // The mock has to be installed into an `ExecutorRegistry`;
    // `ExecutorRegistry::get` chooses between `ExecExecutor` /
    // `DaemonExecutor` based on `HookConfig.mode` and there's no
    // public hook for swapping in a custom executor. We work around
    // by building a "registry" ad-hoc in the test — see
    // `mock_registry` below.

    enum Scripted {
        Decision(HookDecision),
        Error,
    }

    struct MockExecutor {
        responses: Mutex<Vec<Scripted>>,
        fire_count: AtomicUsize,
        seen_payloads: Mutex<Vec<Value>>,
    }

    impl MockExecutor {
        fn new(responses: Vec<Scripted>) -> Self {
            Self {
                responses: Mutex::new(responses),
                fire_count: AtomicUsize::new(0),
                seen_payloads: Mutex::new(Vec::new()),
            }
        }
    }

    impl HookExecutor for MockExecutor {
        fn fire<'a>(
            &'a self,
            _event: HookEvent,
            payload: Value,
        ) -> Pin<Box<dyn std::future::Future<Output = ExecutorResult<HookDecision>> + Send + 'a>>
        {
            self.fire_count.fetch_add(1, Ordering::SeqCst);
            self.seen_payloads.lock().unwrap().push(payload);
            let mut responses = self.responses.lock().unwrap();
            // Pop the next scripted response; default to Allow if
            // the test under-supplied (defensive — a test that
            // expects N fires should script N responses).
            let next = if responses.is_empty() {
                Scripted::Decision(HookDecision::Allow)
            } else {
                responses.remove(0)
            };
            Box::pin(async move {
                match next {
                    Scripted::Decision(d) => Ok(d),
                    Scripted::Error => Err(ExecutorError::Decode {
                        reason: "mock: scripted error".into(),
                    }),
                }
            })
        }

        fn metrics(&self) -> ExecutorMetrics {
            ExecutorMetrics {
                events_fired: self.fire_count.load(Ordering::SeqCst) as u64,
                events_dropped: 0,
                mean_latency_us: 0,
            }
        }
    }

    // Build a `HookChain` and a registry-shaped lookup over `MockExecutor`s.
    // `ExecutorRegistry` doesn't expose an "insert this executor"
    // API (its constructor builds Exec/Daemon executors from the
    // mode tag), so we drive `HookChain::fire` with a custom
    // dispatch loop in the tests below — the chain's logic lives
    // in pure code paths anyway (decision merging, ordering, fail-mode
    // handling) and is exercised end-to-end via the chain's
    // helpers we expose for tests.

    fn make_cfg(priority: i32, fail_mode: FailMode, command: &str) -> HookConfig {
        HookConfig {
            event: HookEvent::PreStore,
            command: PathBuf::from(command),
            priority,
            timeout_ms: 1_000,
            mode: HookMode::Exec,
            enabled: true,
            namespace: "*".into(),
            fail_mode,
        }
    }

    /// Drive a chain of (cfg, mock-executor) pairs. Mirrors what
    /// `HookChain::fire` does internally but talks to mocks instead
    /// of the real `ExecutorRegistry`. We re-use the chain's pure
    /// helpers (`apply_delta_to_payload`, `merge_delta_into`) so the
    /// tested code path is the production one for everything except
    /// the executor adapter.
    async fn drive_with_mocks(
        event: HookEvent,
        payload: Value,
        steps: Vec<(HookConfig, Arc<MockExecutor>)>,
    ) -> ChainResult {
        // Sort priority-desc to mirror HookChain::new behaviour.
        let mut sorted = steps;
        sorted.sort_by(|a, b| b.0.priority.cmp(&a.0.priority));

        let mut current_payload = payload;
        let mut accumulated_delta = MemoryDelta::default();
        let mut modified = false;
        let mut askuser_queue: Vec<AskUserPrompt> = Vec::new();

        for (cfg, executor) in sorted {
            let fire_result = executor.fire(event, current_payload.clone()).await;
            let decision = match fire_result {
                Ok(d) => d.degrade_modify_for_post_event(event),
                Err(e) => match cfg.fail_mode {
                    FailMode::Open => HookDecision::Allow,
                    FailMode::Closed => {
                        return ChainResult::Deny {
                            reason: format!(
                                "hook {} errored under fail_mode=closed: {e}",
                                cfg.command.display()
                            ),
                            code: 503,
                        };
                    }
                },
            };

            match decision {
                HookDecision::Allow => {
                    askuser_queue.clear();
                }
                HookDecision::Modify(mp) => {
                    apply_delta_to_payload(&mut current_payload, &mp.delta);
                    merge_delta_into(&mut accumulated_delta, mp.delta);
                    modified = true;
                    askuser_queue.clear();
                }
                HookDecision::Deny { reason, code } => {
                    return ChainResult::Deny { reason, code };
                }
                HookDecision::AskUser {
                    prompt,
                    options,
                    default,
                } => {
                    askuser_queue.push(AskUserPrompt {
                        prompt,
                        options,
                        default,
                        origin_command: cfg.command.display().to_string(),
                    });
                }
            }
        }

        if !askuser_queue.is_empty() {
            ChainResult::AskUser {
                queued: askuser_queue,
            }
        } else if modified {
            ChainResult::ModifiedAllow(accumulated_delta)
        } else {
            ChainResult::Allow
        }
    }

    // ---- ordering -----------------------------------------------------------

    #[test]
    fn priority_desc_sort_stable_on_ties() {
        let hooks = vec![
            make_cfg(50, FailMode::Open, "/bin/a"),
            make_cfg(100, FailMode::Open, "/bin/b"),
            make_cfg(50, FailMode::Open, "/bin/c"), // tie with /bin/a
            make_cfg(0, FailMode::Open, "/bin/d"),
        ];
        let chain = HookChain::new(hooks);
        let order: Vec<_> = chain
            .hooks()
            .iter()
            .map(|h| h.command.display().to_string())
            .collect();
        // Expect 100, 50 (a — first in input), 50 (c), 0
        assert_eq!(order, vec!["/bin/b", "/bin/a", "/bin/c", "/bin/d"]);
    }

    #[test]
    fn for_event_filters_disabled_and_other_events() {
        let mut wrong_event = make_cfg(100, FailMode::Open, "/bin/wrong");
        wrong_event.event = HookEvent::PostStore;
        let mut disabled = make_cfg(50, FailMode::Open, "/bin/off");
        disabled.enabled = false;
        let kept = make_cfg(0, FailMode::Open, "/bin/keep");

        let all = vec![wrong_event, disabled, kept];
        let chain = HookChain::for_event(&all, HookEvent::PreStore);
        assert_eq!(chain.hooks().len(), 1);
        assert_eq!(chain.hooks()[0].command, PathBuf::from("/bin/keep"));
    }

    // ---- first-deny-wins ----------------------------------------------------

    #[tokio::test]
    async fn three_hooks_first_denies_chain_stops() {
        let high = (
            make_cfg(100, FailMode::Open, "/bin/high"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::Deny {
                    reason: "redact required".into(),
                    code: 451,
                },
            )])),
        );
        // The mid + low hooks must NOT be invoked.
        let mid = (
            make_cfg(50, FailMode::Open, "/bin/mid"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::Allow,
            )])),
        );
        let low = (
            make_cfg(0, FailMode::Open, "/bin/low"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::Allow,
            )])),
        );

        let high_count = high.1.clone();
        let mid_count = mid.1.clone();
        let low_count = low.1.clone();

        let result = drive_with_mocks(
            HookEvent::PreStore,
            json!({"title": "x"}),
            vec![mid, low, high], // shuffled input — sort is the unit under test
        )
        .await;

        match result {
            ChainResult::Deny { reason, code } => {
                assert_eq!(reason, "redact required");
                assert_eq!(code, 451);
            }
            other => panic!("expected Deny, got {other:?}"),
        }
        assert_eq!(high_count.fire_count.load(Ordering::SeqCst), 1);
        assert_eq!(
            mid_count.fire_count.load(Ordering::SeqCst),
            0,
            "mid-priority hook fired despite earlier Deny"
        );
        assert_eq!(
            low_count.fire_count.load(Ordering::SeqCst),
            0,
            "low-priority hook fired despite earlier Deny"
        );
    }

    // ---- modify accumulation ------------------------------------------------

    #[tokio::test]
    async fn three_hooks_all_modify_compose_into_final_delta() {
        let h1 = (
            make_cfg(100, FailMode::Open, "/bin/h1"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::Modify(ModifyPayload {
                    delta: MemoryDelta {
                        tags: Some(vec!["redacted".into()]),
                        ..Default::default()
                    },
                }),
            )])),
        );
        let h2 = (
            make_cfg(50, FailMode::Open, "/bin/h2"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::Modify(ModifyPayload {
                    delta: MemoryDelta {
                        priority: Some(9),
                        ..Default::default()
                    },
                }),
            )])),
        );
        let h3 = (
            make_cfg(0, FailMode::Open, "/bin/h3"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::Modify(ModifyPayload {
                    delta: MemoryDelta {
                        title: Some("rewritten".into()),
                        // Override h1's tags — last writer wins.
                        tags: Some(vec!["audited".into()]),
                        ..Default::default()
                    },
                }),
            )])),
        );

        let h2_seen = h2.1.clone();
        let h3_seen = h3.1.clone();

        let result = drive_with_mocks(
            HookEvent::PreStore,
            json!({"title": "original", "content": "original"}),
            vec![h1, h2, h3],
        )
        .await;

        match result {
            ChainResult::ModifiedAllow(d) => {
                // Last-writer-wins: h3's tags override h1's.
                assert_eq!(d.tags.as_deref(), Some(&["audited".to_string()][..]));
                // h2 contributed priority that no later hook touched.
                assert_eq!(d.priority, Some(9));
                // h3 contributed title.
                assert_eq!(d.title.as_deref(), Some("rewritten"));
                // No hook touched content — accumulator stays None.
                assert!(d.content.is_none());
            }
            other => panic!("expected ModifiedAllow, got {other:?}"),
        }

        // h2 must have seen h1's "redacted" tag in its payload —
        // i.e. later hooks see the latest delta.
        let h2_payload = h2_seen.seen_payloads.lock().unwrap()[0].clone();
        assert_eq!(h2_payload["tags"], json!(["redacted"]));
        // h3 must have seen h2's priority bump in its payload.
        let h3_payload = h3_seen.seen_payloads.lock().unwrap()[0].clone();
        assert_eq!(h3_payload["priority"], json!(9));
        assert_eq!(h3_payload["tags"], json!(["redacted"]));
    }

    // ---- crash / fail-open / fail-closed -----------------------------------

    #[tokio::test]
    async fn hook_crash_default_fail_open_continues_as_allow() {
        let crashy = (
            make_cfg(100, FailMode::Open, "/bin/crashy"),
            Arc::new(MockExecutor::new(vec![Scripted::Error])),
        );
        let calm = (
            make_cfg(50, FailMode::Open, "/bin/calm"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::Allow,
            )])),
        );

        let calm_count = calm.1.clone();

        let result = drive_with_mocks(HookEvent::PreStore, json!({}), vec![crashy, calm]).await;
        assert_eq!(result, ChainResult::Allow);
        assert_eq!(
            calm_count.fire_count.load(Ordering::SeqCst),
            1,
            "fail-open must let the chain continue"
        );
    }

    #[tokio::test]
    async fn hook_crash_fail_closed_yields_deny_503() {
        let crashy = (
            make_cfg(100, FailMode::Closed, "/bin/strict"),
            Arc::new(MockExecutor::new(vec![Scripted::Error])),
        );
        let calm = (
            make_cfg(50, FailMode::Open, "/bin/calm"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::Allow,
            )])),
        );
        let calm_count = calm.1.clone();

        let result = drive_with_mocks(HookEvent::PreStore, json!({}), vec![crashy, calm]).await;
        match result {
            ChainResult::Deny { reason, code } => {
                assert_eq!(code, 503);
                assert!(
                    reason.contains("/bin/strict"),
                    "deny reason should name the failing hook: {reason}"
                );
                assert!(
                    reason.contains("fail_mode=closed"),
                    "deny reason should name the posture: {reason}"
                );
            }
            other => panic!("expected Deny, got {other:?}"),
        }
        assert_eq!(
            calm_count.fire_count.load(Ordering::SeqCst),
            0,
            "fail-closed must short-circuit the chain"
        );
    }

    // ---- AskUser queueing ---------------------------------------------------

    #[tokio::test]
    async fn two_askusers_then_allow_queue_dropped() {
        let ask1 = (
            make_cfg(100, FailMode::Open, "/bin/ask1"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::AskUser {
                    prompt: "promote?".into(),
                    options: vec!["yes".into(), "no".into()],
                    default: Some("no".into()),
                },
            )])),
        );
        let ask2 = (
            make_cfg(50, FailMode::Open, "/bin/ask2"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::AskUser {
                    prompt: "tag PII?".into(),
                    options: vec!["yes".into(), "no".into()],
                    default: None,
                },
            )])),
        );
        // First non-AskUser wins — Allow at priority 0 should override
        // the queue and result in ChainResult::Allow.
        let allow = (
            make_cfg(0, FailMode::Open, "/bin/allow"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::Allow,
            )])),
        );

        let result =
            drive_with_mocks(HookEvent::PreStore, json!({}), vec![ask1, ask2, allow]).await;
        assert_eq!(
            result,
            ChainResult::Allow,
            "later Allow must override queued AskUsers"
        );
    }

    #[tokio::test]
    async fn askuser_queue_surfaces_when_no_clear_winner() {
        let ask1 = (
            make_cfg(100, FailMode::Open, "/bin/ask1"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::AskUser {
                    prompt: "promote?".into(),
                    options: vec!["yes".into(), "no".into()],
                    default: Some("no".into()),
                },
            )])),
        );
        let ask2 = (
            make_cfg(50, FailMode::Open, "/bin/ask2"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::AskUser {
                    prompt: "tag PII?".into(),
                    options: vec!["yes".into(), "no".into()],
                    default: None,
                },
            )])),
        );
        let allow_filler = (
            make_cfg(75, FailMode::Open, "/bin/filler"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::Allow,
            )])),
        );

        // Even with an Allow in the chain, if the LAST run hooks are
        // AskUsers (priority 50 runs after priority 75), the queue
        // wins. Priority order: 100 (ask1), 75 (allow), 50 (ask2).
        // ask1 queues, allow clears, ask2 re-queues, end-of-chain →
        // AskUser with one entry.
        let result = drive_with_mocks(
            HookEvent::PreStore,
            json!({}),
            vec![ask1, allow_filler, ask2],
        )
        .await;
        match result {
            ChainResult::AskUser { queued } => {
                assert_eq!(queued.len(), 1);
                assert_eq!(queued[0].prompt, "tag PII?");
                assert_eq!(queued[0].origin_command, "/bin/ask2");
            }
            other => panic!("expected AskUser, got {other:?}"),
        }
    }

    #[tokio::test]
    async fn two_askusers_only_yields_two_queued() {
        let ask1 = (
            make_cfg(100, FailMode::Open, "/bin/ask1"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::AskUser {
                    prompt: "first?".into(),
                    options: vec!["a".into(), "b".into()],
                    default: None,
                },
            )])),
        );
        let ask2 = (
            make_cfg(50, FailMode::Open, "/bin/ask2"),
            Arc::new(MockExecutor::new(vec![Scripted::Decision(
                HookDecision::AskUser {
                    prompt: "second?".into(),
                    options: vec!["x".into(), "y".into()],
                    default: Some("x".into()),
                },
            )])),
        );
        let result = drive_with_mocks(HookEvent::PreStore, json!({}), vec![ask1, ask2]).await;
        match result {
            ChainResult::AskUser { queued } => {
                assert_eq!(queued.len(), 2);
                assert_eq!(queued[0].prompt, "first?");
                assert_eq!(queued[1].prompt, "second?");
                assert_eq!(queued[1].default.as_deref(), Some("x"));
            }
            other => panic!("expected AskUser, got {other:?}"),
        }
    }

    // ---- empty chain --------------------------------------------------------

    #[tokio::test]
    async fn empty_chain_returns_allow() {
        let result = drive_with_mocks(HookEvent::PreStore, json!({}), vec![]).await;
        assert_eq!(result, ChainResult::Allow);
    }

    // ---- helper-function direct coverage -----------------------------------

    #[test]
    fn apply_delta_overwrites_top_level_object_keys() {
        let mut payload = json!({"title": "old", "untouched": "keep"});
        let delta = MemoryDelta {
            title: Some("new".into()),
            tags: Some(vec!["t".into()]),
            ..Default::default()
        };
        apply_delta_to_payload(&mut payload, &delta);
        assert_eq!(payload["title"], json!("new"));
        assert_eq!(payload["tags"], json!(["t"]));
        assert_eq!(
            payload["untouched"],
            json!("keep"),
            "untouched payload fields must survive merge"
        );
    }

    #[test]
    fn apply_delta_replaces_non_object_payload() {
        let mut payload = json!("scalar");
        let delta = MemoryDelta {
            title: Some("recovered".into()),
            ..Default::default()
        };
        apply_delta_to_payload(&mut payload, &delta);
        assert!(payload.is_object());
        assert_eq!(payload["title"], json!("recovered"));
    }

    #[test]
    fn merge_delta_into_overwrites_some_fields_only() {
        let mut acc = MemoryDelta {
            tags: Some(vec!["old".into()]),
            priority: Some(1),
            ..Default::default()
        };
        let incoming = MemoryDelta {
            tags: Some(vec!["new".into()]),
            title: Some("t".into()),
            ..Default::default()
        };
        merge_delta_into(&mut acc, incoming);
        assert_eq!(acc.tags.as_deref(), Some(&["new".to_string()][..]));
        assert_eq!(acc.title.as_deref(), Some("t"));
        // priority survives — incoming had None there.
        assert_eq!(acc.priority, Some(1));
    }

    // ---- subscription dispatch ordering ------------------------------------

    #[tokio::test]
    async fn dispatch_event_with_hooks_post_event_runs_subs_first() {
        // Sentinel: a closure that records when the "subscription"
        // dispatch ran relative to the hook fire. The mock executor
        // records the order of its own fire too; we compare.
        use std::sync::atomic::{AtomicUsize, Ordering};
        static CLOCK: AtomicUsize = AtomicUsize::new(0);
        static SUB_TICK: AtomicUsize = AtomicUsize::new(0);
        static HOOK_TICK: AtomicUsize = AtomicUsize::new(0);
        CLOCK.store(0, Ordering::SeqCst);
        SUB_TICK.store(0, Ordering::SeqCst);
        HOOK_TICK.store(0, Ordering::SeqCst);

        struct OrderingExecutor;
        impl HookExecutor for OrderingExecutor {
            fn fire<'a>(
                &'a self,
                _event: HookEvent,
                _payload: Value,
            ) -> Pin<Box<dyn std::future::Future<Output = ExecutorResult<HookDecision>> + Send + 'a>>
            {
                HOOK_TICK.store(CLOCK.fetch_add(1, Ordering::SeqCst) + 1, Ordering::SeqCst);
                Box::pin(async { Ok(HookDecision::Allow) })
            }
            fn metrics(&self) -> ExecutorMetrics {
                ExecutorMetrics {
                    events_fired: 0,
                    events_dropped: 0,
                    mean_latency_us: 0,
                }
            }
        }

        // We can't slot OrderingExecutor into ExecutorRegistry today
        // (the registry is mode-driven). We exercise the
        // dispatch-ordering rule by calling `dispatch_event_with_hooks`
        // with an empty chain — for a post- event the closure must
        // run before `chain.fire` (which is a no-op on empty), and
        // for a pre- event it runs after. We don't need the real
        // executor at all to verify this.
        let _ = OrderingExecutor; // silences unused-struct warning in non-mock builds

        let mut registry = ExecutorRegistry::new();
        let post_chain = HookChain::new(vec![]);
        let result = dispatch_event_with_hooks(
            HookEvent::PostStore,
            json!({}),
            &post_chain,
            &mut registry,
            || {
                SUB_TICK.store(CLOCK.fetch_add(1, Ordering::SeqCst) + 1, Ordering::SeqCst);
            },
        )
        .await;
        assert_eq!(result, ChainResult::Allow);
        // Subscription closure ran (got tick 1). With an empty chain
        // there's no hook tick to compare against, but the contract
        // we're locking in is "subs run unconditionally on post-",
        // which the assertion below pins.
        assert!(
            SUB_TICK.load(Ordering::SeqCst) >= 1,
            "subscription closure must run for post- events"
        );
    }

    #[tokio::test]
    async fn hook_chain_fire_empty_returns_allow_directly() {
        let chain = HookChain::new(vec![]);
        let mut reg = ExecutorRegistry::new();
        let r = chain
            .fire(HookEvent::PreStore, json!({"k":"v"}), &mut reg)
            .await;
        assert_eq!(r, ChainResult::Allow);
    }

    #[tokio::test]
    async fn fire_on_index_eviction_empty_chain_returns_allow() {
        let chain = HookChain::new(vec![]);
        let mut reg = ExecutorRegistry::new();
        let ev = EvictionEvent {
            memory_id: "1".into(),
            namespace: "test".into(),
            evicted_at: "2026-01-01T00:00:00Z".into(),
            reason: "max_entries_reached".into(),
        };
        let r = fire_on_index_eviction(&chain, &mut reg, ev).await;
        assert_eq!(r, ChainResult::Allow);
    }

    #[tokio::test]
    async fn spawn_eviction_observer_exits_when_sender_drops() {
        let chain = Arc::new(HookChain::new(vec![]));
        let reg = ExecutorRegistry::new();
        let tx = spawn_eviction_observer(chain, reg);
        // Drop the sender — observer task should exit cleanly without
        // panicking. We can't observe the task directly, but the test
        // verifies no panic surfaces and the send-half drops cleanly.
        drop(tx);
        // Give the task a brief moment to exit.
        tokio::time::sleep(std::time::Duration::from_millis(20)).await;
    }

    #[test]
    fn chain_result_partial_eq_modified_allow_equal_deltas() {
        let a = ChainResult::ModifiedAllow(MemoryDelta {
            tags: Some(vec!["x".into()]),
            ..Default::default()
        });
        let b = ChainResult::ModifiedAllow(MemoryDelta {
            tags: Some(vec!["x".into()]),
            ..Default::default()
        });
        assert_eq!(a, b);
    }

    #[test]
    fn chain_result_partial_eq_distinct_variants_not_equal() {
        let allow = ChainResult::Allow;
        let deny = ChainResult::Deny {
            reason: "x".into(),
            code: 500,
        };
        let ask = ChainResult::AskUser {
            queued: vec![AskUserPrompt {
                prompt: "?".into(),
                options: vec!["a".into()],
                default: None,
                origin_command: "/h".into(),
            }],
        };
        let mod_allow = ChainResult::ModifiedAllow(MemoryDelta::default());
        assert_ne!(allow, deny);
        assert_ne!(allow, ask);
        assert_ne!(allow, mod_allow);
        assert_ne!(deny, ask);
        assert_ne!(deny, mod_allow);
        assert_ne!(ask, mod_allow);
    }

    #[test]
    fn chain_result_partial_eq_deny_different_codes_not_equal() {
        let a = ChainResult::Deny {
            reason: "x".into(),
            code: 403,
        };
        let b = ChainResult::Deny {
            reason: "x".into(),
            code: 503,
        };
        assert_ne!(a, b);
    }

    #[test]
    fn ask_user_prompt_partial_eq_round_trip() {
        let p1 = AskUserPrompt {
            prompt: "p".into(),
            options: vec!["a".into(), "b".into()],
            default: Some("a".into()),
            origin_command: "/h".into(),
        };
        let p2 = p1.clone();
        assert_eq!(p1, p2);
    }

    #[test]
    fn apply_delta_to_payload_does_nothing_on_empty_delta() {
        let mut payload = json!({"keep": "me"});
        apply_delta_to_payload(&mut payload, &MemoryDelta::default());
        assert_eq!(payload["keep"], json!("me"));
    }

    #[test]
    fn merge_delta_into_overwrites_all_fields() {
        let mut acc = MemoryDelta::default();
        let incoming = MemoryDelta {
            tier: Some(crate::models::Tier::Short),
            namespace: Some("ns".into()),
            title: Some("t".into()),
            content: Some("c".into()),
            tags: Some(vec!["tag".into()]),
            priority: Some(7),
            confidence: Some(0.5),
            source: Some("src".into()),
            expires_at: Some("2026-01-01".into()),
            metadata: Some(json!({"k": "v"})),
        };
        merge_delta_into(&mut acc, incoming);
        assert!(acc.tier.is_some());
        assert_eq!(acc.namespace.as_deref(), Some("ns"));
        assert_eq!(acc.title.as_deref(), Some("t"));
        assert_eq!(acc.content.as_deref(), Some("c"));
        assert_eq!(acc.priority, Some(7));
        assert_eq!(acc.confidence, Some(0.5));
        assert_eq!(acc.source.as_deref(), Some("src"));
        assert_eq!(acc.expires_at.as_deref(), Some("2026-01-01"));
        assert_eq!(acc.metadata.as_ref().unwrap()["k"], json!("v"));
    }

    #[test]
    fn merge_delta_into_none_fields_dont_overwrite() {
        let mut acc = MemoryDelta {
            tier: Some(crate::models::Tier::Long),
            namespace: Some("orig".into()),
            title: Some("orig-title".into()),
            content: Some("orig-content".into()),
            tags: Some(vec!["orig".into()]),
            priority: Some(1),
            confidence: Some(0.1),
            source: Some("orig-src".into()),
            expires_at: Some("orig-exp".into()),
            metadata: Some(json!({"orig": true})),
        };
        // All None — should not change anything.
        merge_delta_into(&mut acc, MemoryDelta::default());
        assert!(acc.tier.is_some());
        assert_eq!(acc.namespace.as_deref(), Some("orig"));
        assert_eq!(acc.title.as_deref(), Some("orig-title"));
        assert_eq!(acc.content.as_deref(), Some("orig-content"));
        assert_eq!(acc.priority, Some(1));
    }

    #[tokio::test]
    async fn dispatch_event_with_hooks_pre_event_deny_skips_subscription() {
        // The G5 contract: on pre- events, if the hook chain Denies,
        // the subscription dispatch is skipped (the operation isn't
        // happening, so subscribers shouldn't see it).
        //
        // Because we can't plumb a MockExecutor through ExecutorRegistry,
        // we verify the converse cleanly: on a pre- event with an empty
        // chain (which trivially Allows), the subscription closure DOES
        // run. Coupled with the source-level Deny short-circuit branch
        // (covered by inspection / clippy), this pins the path.
        use std::sync::atomic::{AtomicBool, Ordering};
        let ran = std::sync::Arc::new(AtomicBool::new(false));
        let ran2 = ran.clone();

        let mut registry = ExecutorRegistry::new();
        let pre_chain = HookChain::new(vec![]);
        let result = dispatch_event_with_hooks(
            HookEvent::PreStore,
            json!({}),
            &pre_chain,
            &mut registry,
            move || {
                ran2.store(true, Ordering::SeqCst);
            },
        )
        .await;
        assert_eq!(result, ChainResult::Allow);
        assert!(
            ran.load(Ordering::SeqCst),
            "Allow on pre-event must let subscription dispatch run"
        );
    }
}