skilj-core 0.2.0

//! sqlx queries and migrations - persistence for every module in this
//! crate. See docs/architecture.md §2.2 for why `sqlx`, and §2.2.1 for
//! why every `Integer`-typed column is `BIGINT`, not `INT`.
//!
//! Every rule in `access_control`/`event_store` is a pure function that
//! takes already-loaded state as parameters (no I/O of its own - §1.1's
//! `decide()`/`project()` split, extended to this crate's own rules) -
//! this module is where that state actually gets loaded from and written
//! back to Postgres. Uses `sqlx::query`/`query_as` (the runtime-checked
//! API), not the `query!`/`query_as!` macros - this workspace has no live
//! database to check them against at compile time, and a library
//! embedding its own migrations for a consuming application to run
//! shouldn't assume one exists at `cargo build` time either.
//!
//! **Two-tier schema** (docs/architecture.md §2.2.2): `roles`,
//! `bounded_contexts`, `role_access_mappings` and `access_token_index`
//! live in the global (`public`) schema, tracked by the static
//! `sqlx::migrate!` set in `migrations/`. Everything scoped to one
//! bounded context - event/command types, events, commands, projections,
//! access tokens, read cursors, the sequence counter - lives in that
//! context's own Postgres schema (`bc_<name>`) instead, provisioned
//! dynamically by `provision_bounded_context_schema` when the context is
//! created and torn down in one statement by `hard_delete_bounded_context`,
//! never tracked by `sqlx::migrate!`. This is why most functions below
//! take `bounded_context: &str` as a schema selector, not a `WHERE`
//! filter value: a per-context table's own rows never carry a
//! `bounded_context` column at all, since the schema they live in already
//! says which context they belong to.
//!
//! Scoped, for now, to what's actually wired or registerable - see
//! `migrations/0001_init.sql`'s own doc comment for the full list of
//! what's deliberately not here yet (`EncryptionKey`).

mod master_key;
pub use master_key::{
    assign_encryption_key, bounded_context_key, check_data_key_wraps, data_keys_behind,
    delete_unused_key, encryption_key_assignments, forget_assignments_of_deleted_contexts,
    key_in_use, mark_data_keys_behind, mark_data_keys_rewrapped, master_key_state,
    master_key_states, register_known_keys, register_master_key_event_types,
    retire_master_key_versions, rewrap_data_keys, rewrap_data_keys_once, rotate_master_key,
    schedule_key_deletion, DataKeyWraps, MasterKeyState, RewrapOutcome, Rotation,
};

use crate::access_control::{
    AccessLevel, CommandToken, DirectCreationToken, EventReadStartPosition, EventReadToken,
    ExternalEventToken, PrivateFieldGrant, Role, RoleAccessMapping, RoleStatus, TokenStatus,
};
use crate::access_trail::{fold_access_events, AccessChange, AccessEventKind, AccessEventRecord};
use crate::approvals::{CommandApprovalPolicy, CommandProposal, CommandProposalStatus};
use crate::bootstrap::ContextCreator;
use crate::encryption::{self, DataKey, KeyService};
use crate::event_store::{
    AckMode, BoundedContext, BoundedContextStatus, Command, CommandType, CursorUpdate,
    EncryptionKey, EncryptionKeyStatus, Event, EventOrigin, EventType, MissedOccurrencePolicy,
    ReadCursor, WouldBeEvent,
};
use crate::projections::{Projection, ProjectionRebuild, ProjectionRebuildStatus};
use crate::secrets::{self, Secret, SecretGrant, SecretGrantStatus, SecretStatus, SecretValue};
use crate::shared::{Metadata, PrivateField, QueryItem, SensitiveField, Tag, TagMapping};
use chrono::{DateTime, Utc};
use opentelemetry::metrics::{Counter, Histogram, Meter};
use opentelemetry::KeyValue;
use sqlx::types::Json;
use sqlx::{Acquire, Postgres, Transaction};
use std::sync::LazyLock;

/// This crate's own OTel instrumentation scope. `opentelemetry::global::meter(...)`
/// **snapshot-binds** to whichever `MeterProvider` is globally registered
/// at the moment it's first called (its own doc comment says so
/// explicitly) - unlike the `tracing`/`tracing-opentelemetry` bridge,
/// which is wired to a concrete provider once, inside the consuming
/// app's own `init_telemetry`. Every instrument below is a `LazyLock`,
/// so this is only ever called the first time a metric is actually
/// recorded (the first command processed, the first event appended) -
/// always strictly after a real consuming app's `main()` has already
/// called `opentelemetry::global::set_meter_provider(...)`, since that
/// has to happen before `.build()` even runs. If a future change ever
/// moves telemetry init to *after* `Skilj::builder(...).build()`, this
/// silently goes back to recording into a no-op meter forever - see
/// docs/architecture.md's tracing section.
fn meter() -> &'static Meter {
    static METER: LazyLock<Meter> = LazyLock::new(|| opentelemetry::global::meter("skilj-core"));
    &METER
}

static COMMANDS_PROCESSED: LazyLock<Counter<u64>> = LazyLock::new(|| {
    meter()
        .u64_counter("skilj.commands.processed")
        .with_description("Commands processed by ProcessCommand, by outcome.")
        .build()
});

static EVENTS_APPENDED: LazyLock<Counter<u64>> = LazyLock::new(|| {
    meter()
        .u64_counter("skilj.events.appended")
        .with_description("Events appended to the event store.")
        .build()
});

/// How many commands `CommandBatcher::run_as_leader` actually coalesced
/// into one `commit_command_batch` lock acquisition - the one number
/// none of the `docs/load-test-report-2026-09-18*.md` passes ever
/// measured (all three skipped OTel/Grafana), even though it's exactly
/// what would confirm or refute their shared "batch amortisation is
/// maxed out, per-command work now dominates" reading of the throughput
/// numbers. Recorded once per `commit_command_batch` call, by
/// `bounded_context` - a distribution consistently near 1 under real
/// concurrent load would mean the self-tuning batcher isn't actually
/// forming large batches, a very different diagnosis than "batches are
/// large but per-command work inside them is the bottleneck".
static COMMAND_BATCH_SIZE: LazyLock<Histogram<u64>> = LazyLock::new(|| {
    meter()
        .u64_histogram("skilj.command_batch.size")
        .with_description("Commands coalesced into one command-batch lock acquisition.")
        .build()
});

/// Called at each of this module's five `broadcaster.publish(event)` call
/// sites, never inside `insert_event` itself - `insert_event` runs inside
/// a still-open transaction its own caller might yet roll back (a later
/// step in the same transaction failing), while `publish` is only ever
/// reached after `tx.commit()` succeeds (see e.g.
/// `insert_event_and_update_sync_projections`'s own doc comment: "after
/// the commit, not before"). Counting at `insert_event` itself would
/// over-count on any such rollback.
fn record_event_appended(event: &Event) {
    EVENTS_APPENDED.add(
        1,
        &[
            KeyValue::new("bounded_context", event.bounded_context.name.clone()),
            KeyValue::new("event_type", event.event_type.name.clone()),
        ],
    );
}

/// `crate::cross_instance`'s sending half for the `skilj_events` channel -
/// called alongside `record_event_appended`, at the same five call sites,
/// for the identical "only after the commit" reason. Every *other*
/// listening instance fetches the real event and republishes it into its
/// own local `EventBroadcaster` - see `crate::cross_instance`'s own
/// module doc comment for the full design. `origin_instance_id` is
/// `EventBroadcaster::instance_id`'s own value at this call site (the
/// broadcaster `publish` was already just called on, immediately above
/// every one of these five call sites) - carried in the payload purely
/// so this same instance's own `NOTIFY` echoing back to itself can be
/// recognised and skipped rather than republished into that identical
/// broadcaster a second time (see `EventBroadcaster::instance_id`'s own
/// doc comment for why that duplication would otherwise happen). A
/// `NOTIFY` failure is logged and swallowed, never propagated: the event
/// it accompanies already committed, and this channel is a pure
/// liveliness signal - a missed notification self-heals via the same
/// DB-backed catch-up path a same-process lagged subscriber already
/// takes, per `@guarantee DeliverySpansInstances` in specs/skilj.allium.
/// [`notify_event_appended`] for many events in one statement - one
/// round trip for a whole command batch instead of one per event, sent
/// before the batch's callers get their answers (docs/architecture.md
/// §196). Each notification carries the same payload as one sent alone.
async fn notify_events_appended(pool: &Pool, events: &[&Event], origin_instance_id: &str) {
    match events {
        [] => return,
        [event] => return notify_event_appended(pool, event, origin_instance_id).await,
        _ => {}
    }
    let payloads: Vec<String> = events
        .iter()
        .map(|event| {
            serde_json::json!({
                "bounded_context": event.bounded_context.name,
                "sequence": event.sequence,
                "origin_instance_id": origin_instance_id,
            })
            .to_string()
        })
        .collect();
    if let Err(err) =
        sqlx::query("SELECT pg_notify('skilj_events', payload) FROM unnest($1::text[]) AS payload")
            .bind(&payloads)
            .execute(pool)
            .await
    {
        tracing::warn!(
            error = %err,
            "NOTIFY skilj_events failed - other instances may miss these events' live push \
             until their next poll-based read"
        );
    }
}

async fn notify_event_appended(pool: &Pool, event: &Event, origin_instance_id: &str) {
    let payload = serde_json::json!({
        "bounded_context": event.bounded_context.name,
        "sequence": event.sequence,
        "origin_instance_id": origin_instance_id,
    })
    .to_string();
    if let Err(err) = sqlx::query("SELECT pg_notify('skilj_events', $1)")
        .bind(payload)
        .execute(pool)
        .await
    {
        tracing::warn!(
            error = %err,
            "NOTIFY skilj_events failed - other instances may miss this event's live push \
             until their next poll-based read"
        );
    }
}

/// `crate::cross_instance`'s sending half for the `skilj_registration_changed`
/// channel - called from every DB-layer function that changes what the
/// GraphQL schema needs to expose (`upsert_event_type`/`upsert_command_type`/
/// `upsert_projection`/`register_new_sync_projection`/
/// `promote_projection_rebuild`/`insert_bounded_context`/
/// `update_bounded_context_status`/`hard_delete_bounded_context`). No payload: which exact type or bounded
/// context changed doesn't matter, every listener reacts identically (a
/// full schema rebuild) - see `crate::cross_instance`'s own module doc
/// comment. Same "log and swallow, never propagate" treatment as
/// `notify_event_appended` and for the identical reason.
async fn notify_registration_changed(pool: &Pool) {
    if let Err(err) = sqlx::query("SELECT pg_notify('skilj_registration_changed', '')")
        .execute(pool)
        .await
    {
        tracing::warn!(
            error = %err,
            "NOTIFY skilj_registration_changed failed - other instances' GraphQL schema may \
             lag until their next registration change or restart"
        );
    }
}

/// `crate::cross_instance`'s sending half for the `skilj_revocations`
/// channel - `skilj-graphql`'s `access_management` resolvers are the only
/// two callers (alongside their own `RevocationBroadcaster::publish`),
/// hence `pub`: this is the one `notify_*` helper reached from outside
/// this module, since revocation, unlike event/registration writes, is
/// driven entirely from the GraphQL layer with no `db::` choke point of
/// its own to hook. `origin_instance_id` gets the identical
/// self-NOTIFY-dedup treatment `notify_event_appended`'s own doc comment
/// describes, here against `RevocationBroadcaster::instance_id`. Same
/// "log and swallow" treatment as its siblings.
pub async fn notify_revocation(
    pool: &Pool,
    mapping: &crate::access_control::RevokedMapping,
    origin_instance_id: &str,
) {
    let payload = serde_json::json!({
        "role_id": mapping.role_id,
        "bounded_context": mapping.bounded_context,
        "origin_instance_id": origin_instance_id,
    })
    .to_string();
    if let Err(err) = sqlx::query("SELECT pg_notify('skilj_revocations', $1)")
        .bind(payload)
        .execute(pool)
        .await
    {
        tracing::warn!(
            error = %err,
            "NOTIFY skilj_revocations failed - other instances may miss this revocation's live \
             push until their next direct database re-check"
        );
    }
}

/// An opaque handle to the connection pool - re-exported so `skilj-rest`/
/// `skilj-graphql` can hold one without depending on `sqlx` directly
/// themselves, the same crate-boundary reasoning docs/architecture.md
/// §3.1 gives for keeping `skilj-core` the only crate that owns the
/// database driver.
pub type Pool = sqlx::PgPool;

/// Re-exported for the identical reason `Pool` is - `SkiljBuilder::
/// pool_options` (skilj's own builder) accepts one of these without
/// `skilj` itself depending on `sqlx` directly.
pub use sqlx::postgres::PgPoolOptions;

/// `sqlx`'s own bare default (`PgPoolOptions::new()`, currently a
/// 10-connection cap with no configured timeouts) - unchanged behaviour
/// for every existing caller. Callers that need to tune pool sizing for
/// real production load (background pollers - async-projection,
/// snapshot, scheduler - already compete with foreground requests for
/// whatever this pool provides) use [`connect_with`] instead, the same
/// "sensible default, escape hatch alongside it" register every other
/// `SkiljBuilder` tunable (`async_projection_poll_interval`,
/// `event_broadcast_capacity`, ...) already uses.
#[tracing::instrument(skip_all)]
pub async fn connect(database_url: &str) -> Result<Pool, sqlx::Error> {
    connect_with(database_url, PgPoolOptions::new()).await
}

/// [`connect`] with caller-supplied pool options (`max_connections`,
/// `min_connections`, `acquire_timeout`, `idle_timeout`, ...) - see that
/// function's own doc comment for why this exists alongside it.
#[tracing::instrument(skip_all)]
pub async fn connect_with(database_url: &str, options: PgPoolOptions) -> Result<Pool, sqlx::Error> {
    connect_with_statement_cache(database_url, options, None).await
}

/// [`connect_with`], with `statement_cache_capacity` (when `Some`)
/// overriding both the database URL's `statement-cache-capacity`
/// parameter and sqlx's default (docs/architecture.md §193).
#[tracing::instrument(skip_all)]
pub async fn connect_with_statement_cache(
    database_url: &str,
    options: PgPoolOptions,
    statement_cache_capacity: Option<usize>,
) -> Result<Pool, sqlx::Error> {
    let mut connect_options: sqlx::postgres::PgConnectOptions = database_url.parse()?;
    if let Some(capacity) = statement_cache_capacity {
        connect_options = connect_options.statement_cache_capacity(capacity);
    }
    options.connect_with(connect_options).await
}

/// sqlx's own default for how many prepared statements each connection
/// keeps (least recently used out).
pub const DEFAULT_STATEMENT_CACHE_CAPACITY: usize = 100;

/// The statement cache capacity a pool connected with
/// [`connect_with_statement_cache`] ends up with: `explicit`, else the
/// database URL's last `statement-cache-capacity` parameter, else
/// [`DEFAULT_STATEMENT_CACHE_CAPACITY`]. sqlx has no getter for it.
pub fn effective_statement_cache_capacity(database_url: &str, explicit: Option<usize>) -> usize {
    explicit
        .or_else(|| {
            let (_, query) = database_url.split_once('?')?;
            // sqlx applies the parameters in order, so a repeated one's
            // last value is what the pool gets.
            query.rsplit('&').find_map(|pair| {
                let (key, value) = pair.split_once('=')?;
                (key == "statement-cache-capacity")
                    .then(|| value.parse().ok())
                    .flatten()
            })
        })
        .unwrap_or(DEFAULT_STATEMENT_CACHE_CAPACITY)
}

/// Statements a bounded context needs cached, at least: the command path
/// alone sends 14-20 distinct statements per bounded context, and
/// throughput fell 20-40% once the cache held fewer than about 10 per
/// busy one (docs/architecture.md §193).
pub const STATEMENT_CACHE_MIN_PER_BOUNDED_CONTEXT: usize = 10;

/// Runs every embedded migration under `skilj-core/migrations/` - see
/// this module's own doc comment and docs/architecture.md §2.2 for why
/// `skilj-core` owns its schema this way. Only ever touches the global
/// tables - per-bounded-context schemas are provisioned separately, see
/// `provision_bounded_context_schema`.
#[tracing::instrument(skip_all)]
pub async fn migrate(pool: &Pool) -> Result<(), sqlx::migrate::MigrateError> {
    sqlx::migrate!("./migrations").run(pool).await
}

// --- small str <-> enum conversions, shared by more than one entity below ---

fn bounded_context_status_to_str(status: BoundedContextStatus) -> &'static str {
    match status {
        BoundedContextStatus::Active => "active",
        BoundedContextStatus::Archived => "archived",
    }
}

fn bounded_context_status_from_str(s: &str) -> BoundedContextStatus {
    match s {
        "archived" => BoundedContextStatus::Archived,
        _ => BoundedContextStatus::Active,
    }
}

fn role_status_to_str(status: RoleStatus) -> &'static str {
    match status {
        RoleStatus::Active => "active",
        RoleStatus::Revoked => "revoked",
    }
}

fn role_status_from_str(s: &str) -> RoleStatus {
    match s {
        "revoked" => RoleStatus::Revoked,
        _ => RoleStatus::Active,
    }
}

fn token_status_to_str(status: TokenStatus) -> &'static str {
    match status {
        TokenStatus::Active => "active",
        TokenStatus::Revoked => "revoked",
    }
}

fn token_status_from_str(s: &str) -> TokenStatus {
    match s {
        "revoked" => TokenStatus::Revoked,
        _ => TokenStatus::Active,
    }
}

fn ack_mode_to_str(mode: AckMode) -> &'static str {
    match mode {
        AckMode::AutoAdvance => "auto_advance",
        AckMode::ManualAck => "manual_ack",
    }
}

fn ack_mode_from_str(s: &str) -> AckMode {
    match s {
        "manual_ack" => AckMode::ManualAck,
        _ => AckMode::AutoAdvance,
    }
}

fn event_read_start_position_to_str(position: EventReadStartPosition) -> &'static str {
    match position {
        EventReadStartPosition::Beginning => "beginning",
        EventReadStartPosition::Latest => "latest",
        EventReadStartPosition::AtSequence => "at_sequence",
        EventReadStartPosition::AtTime => "at_time",
    }
}

fn event_read_start_position_from_str(s: &str) -> EventReadStartPosition {
    match s {
        "latest" => EventReadStartPosition::Latest,
        "at_sequence" => EventReadStartPosition::AtSequence,
        "at_time" => EventReadStartPosition::AtTime,
        _ => EventReadStartPosition::Beginning,
    }
}

fn access_level_to_str(level: AccessLevel) -> &'static str {
    match level {
        AccessLevel::Read => "read",
        AccessLevel::Write => "write",
        AccessLevel::Admin => "admin",
    }
}

fn access_level_from_str(s: &str) -> AccessLevel {
    match s {
        "write" => AccessLevel::Write,
        "admin" => AccessLevel::Admin,
        _ => AccessLevel::Read,
    }
}

/// The Postgres schema a bounded context's own tables live in, as a
/// double-quoted identifier ready to interpolate into SQL. The `bc_`
/// prefix keeps a context from ever colliding with a real schema
/// (`public`, `pg_catalog`, ...); the quoting is defence in depth, not
/// the only thing standing between this and SQL injection - `name` is
/// only ever a value `AddBoundedContext`'s own `requires` already
/// restricted to a safe identifier pattern (specs/skilj.allium) by the
/// time it reaches here. For the quoting to actually be that second line
/// of defence, an embedded `"` is doubled (Postgres's own escape inside a
/// quoted identifier) rather than left to close the identifier early.
pub(crate) fn schema_ident(bounded_context: &str) -> String {
    format!("\"bc_{}\"", bounded_context.replace('"', "\"\""))
}

/// Whether `err` is a bounded context's schema or table gone: deleted
/// since it was listed (docs/architecture.md §157).
pub(crate) fn is_missing_schema(err: &crate::error::Error) -> bool {
    matches!(err, crate::error::Error::Database(e) if e
        .as_database_error()
        .and_then(|d| d.code())
        .is_some_and(|code| code == "42P01" || code == "3F000"))
}

/// `value` as a SQL string literal.
fn sql_literal(value: &str) -> String {
    format!("'{}'", value.replace('\'', "''"))
}

/// `ddl`, adding `columns` to `table` in the bounded context's `schema`,
/// run only when one of them is missing (docs/architecture.md §158).
/// `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` takes its `ACCESS
/// EXCLUSIVE` lock before finding there's nothing to add, so run bare on
/// every startup it queued behind any open read of the table, and every
/// later query queued behind it. The catalog check takes no table lock.
/// A missing table still runs `ddl`, and fails as before.
fn add_columns_patch(schema: &str, table: &str, columns: &[&str], ddl: String) -> String {
    let table = sql_literal(&format!("{schema}.{table}"));
    let missing = columns
        .iter()
        .map(|column| {
            format!(
                "NOT EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = to_regclass({table}) \
                 AND attname = {} AND attnum > 0 AND NOT attisdropped)",
                sql_literal(column)
            )
        })
        .collect::<Vec<_>>()
        .join(" OR ");
    format!("DO $patch$ BEGIN IF {missing} THEN {ddl}; END IF; END $patch$")
}

/// `ddl`, creating `index` in the bounded context's `schema`, run only
/// when no relation of that name exists: `CREATE INDEX IF NOT EXISTS`
/// takes its `SHARE` lock, which blocks writes, before finding the index
/// already there (docs/architecture.md §158).
fn create_index_patch(schema: &str, index: &str, ddl: String) -> String {
    format!(
        "DO $patch$ BEGIN IF to_regclass({}) IS NULL THEN {ddl}; END IF; END $patch$",
        sql_literal(&format!("{schema}.{index}"))
    )
}

/// `ddl`, adding constraint `name` to `table` in the bounded context's
/// `schema`, run only when the table has no constraint of that name
/// (docs/architecture.md §158/§159).
fn add_constraint_patch(schema: &str, table: &str, name: &str, ddl: String) -> String {
    format!(
        "DO $patch$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_constraint \
         WHERE conrelid = to_regclass({}) AND conname = {}) THEN {ddl}; END IF; END $patch$",
        sql_literal(&format!("{schema}.{table}")),
        sql_literal(name)
    )
}

// --- per-bounded-context schema provisioning / hard deletion ---

/// Every `CREATE TABLE` a bounded context's own schema needs, in
/// dependency order (each table only ever references one created earlier
/// in this same list). Run once, inside the same transaction as the
/// `bounded_contexts` registry insert - see `insert_bounded_context`.
async fn provision_bounded_context_schema(
    tx: &mut Transaction<'_, Postgres>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);

    sqlx::query(sqlx::AssertSqlSafe(format!("CREATE SCHEMA {schema}")))
        .execute(&mut **tx)
        .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.event_types (
            name TEXT PRIMARY KEY,
            schema TEXT NOT NULL,
            schema_version BIGINT NOT NULL,
            tag_mappings JSONB NOT NULL DEFAULT '[]',
            owner_tag_key TEXT,
            sensitive_fields JSONB NOT NULL DEFAULT '[]',
            private_fields JSONB NOT NULL DEFAULT '[]',
            external_creation_allowed BOOLEAN NOT NULL,
            direct_creation_allowed BOOLEAN NOT NULL,
            system_triggered_allowed BOOLEAN NOT NULL,
            system_triggered_schedule TEXT,
            missed_occurrence_policy TEXT CHECK (missed_occurrence_policy IN \
                ('skip', 'fire_once', 'replay_backlog')),
            schedule_position TIMESTAMPTZ,
            last_fired_at TIMESTAMPTZ,
            event_read_allowed BOOLEAN NOT NULL
        )"
    )))
    .execute(&mut **tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.command_types (
            name TEXT PRIMARY KEY,
            schema TEXT NOT NULL,
            schema_version BIGINT NOT NULL,
            tag_mappings JSONB NOT NULL DEFAULT '[]',
            owner_tag_key TEXT,
            sensitive_fields JSONB NOT NULL DEFAULT '[]',
            private_fields JSONB NOT NULL DEFAULT '[]',
            rest_trigger_allowed BOOLEAN NOT NULL
        )"
    )))
    .execute(&mut **tx)
    .await?;

    // See `entity EncryptionKey`. No FK to what a `SensitiveField`
    // declares it for - identified by `(subject_key, subject_value)`
    // alone, shared across every `EventType`/`CommandType` that
    // references the same subject (docs/architecture.md's write-up of
    // this pass). `wrapped_key`/`wrap_nonce` are this process's own
    // envelope-encryption detail (`skilj_core::encryption`), never part
    // of the spec's own entity - `NULL` once destroyed
    // (`db::destroy_encryption_key`), real crypto-shredding rather than
    // a status flag alone. The partial unique index is the identical
    // pattern `roles_unique_active_external_subject` already uses: at
    // most one *active* key per subject, while a destroyed one stays
    // around permanently (append-only, like everything else here) so a
    // later event for the same subject provisions a genuinely new key
    // rather than colliding with the old row.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.encryption_keys (
            id BIGSERIAL PRIMARY KEY,
            subject_key TEXT NOT NULL,
            subject_value TEXT NOT NULL,
            status TEXT NOT NULL CHECK (status IN ('active', 'destroyed')),
            created_at TIMESTAMPTZ NOT NULL,
            destroyed_at TIMESTAMPTZ,
            wrapped_key BYTEA,
            wrap_nonce BYTEA,
            key_provider TEXT,
            master_key_version INTEGER,
            unreadable_since TIMESTAMPTZ
        )"
    )))
    .execute(&mut **tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE UNIQUE INDEX encryption_keys_unique_active ON {schema}.encryption_keys \
         (subject_key, subject_value) WHERE status = 'active'"
    )))
    .execute(&mut **tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(encryption_keys_master_key_index_ddl(
        &schema,
    )))
    .execute(&mut **tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.commands (
            id BIGSERIAL PRIMARY KEY,
            external_id TEXT NOT NULL UNIQUE,
            command_type_name TEXT NOT NULL REFERENCES {schema}.command_types (name),
            payload TEXT NOT NULL,
            metadata_type TEXT NOT NULL,
            metadata_version BIGINT NOT NULL,
            metadata_client_id TEXT NOT NULL,
            metadata_created_at TIMESTAMPTZ NOT NULL,
            metadata_correlation_id TEXT,
            metadata_causation_id TEXT,
            consistency_tags JSONB NOT NULL DEFAULT '[]',
            consistency_boundary BIGINT,
            consistency_query JSONB NOT NULL DEFAULT '[]'
        )"
    )))
    .execute(&mut **tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE INDEX commands_by_created_at ON {schema}.commands (metadata_created_at)"
    )))
    .execute(&mut **tx)
    .await?;
    // issue #18 - backs `event_store::fetch_commands`' own new
    // correlation_id filter, same "cold-start/large-history nicety, not
    // a correctness requirement" register the `events` table's own
    // sibling index below has, since that function already filters an
    // in-memory slice like every other criterion it supports.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE INDEX commands_by_correlation_id ON {schema}.commands (metadata_correlation_id) \
         WHERE metadata_correlation_id IS NOT NULL"
    )))
    .execute(&mut **tx)
    .await?;
    ensure_idempotency_keys_table(&mut **tx, bounded_context).await?;
    ensure_cross_context_route_cursors_table(&mut **tx, bounded_context).await?;
    ensure_external_message_cursors_table(&mut **tx, bounded_context).await?;
    ensure_external_message_keys_table(&mut **tx, bounded_context).await?;
    ensure_deadline_cursors_table(&mut **tx, bounded_context).await?;
    // issue #21 - `parked_deliveries`, a brand-new table, so no
    // `ALTER TABLE` patch is needed here the way `cross_context_route_cursors`'
    // own new retry columns need `ensure_cross_context_route_retry_columns`
    // (build()'s own startup loop only, not here - see that function's
    // own doc comment).
    ensure_parked_deliveries_table(&mut **tx, bounded_context).await?;
    // Created here too, not only by `build()`'s own startup migration:
    // `insert_parked_delivery`'s `ON CONFLICT` can't run at all without
    // it, and a bounded context added at runtime (`addBoundedContext`)
    // would otherwise lack it until the next restart. Safe unguarded -
    // the table was only just created, so it has no rows to conflict.
    sqlx::query(sqlx::AssertSqlSafe(parked_deliveries_occurrence_index_ddl(
        &schema,
    )))
    .execute(&mut **tx)
    .await?;
    // issue #20 - `ensure_deadlines_table`'s own two-index shape
    // run directly against this transaction rather than calling that
    // function (it takes `&Pool`, not a transaction - see its own doc
    // comment), the identical split `private_field_grants_table_ddl`'s
    // own two call sites already use.
    sqlx::query(sqlx::AssertSqlSafe(deadlines_table_ddl(&schema)))
        .execute(&mut **tx)
        .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE INDEX IF NOT EXISTS deadlines_due ON {schema}.deadlines (fire_at) \
         WHERE status = 'pending'"
    )))
    .execute(&mut **tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE INDEX IF NOT EXISTS deadlines_tags_gin ON {schema}.deadlines USING GIN (tags)"
    )))
    .execute(&mut **tx)
    .await?;
    // `EncryptionKey` is a real, independently-lived entity (its own
    // status/lifecycle - see `entity EncryptionKey`), so it's referenced
    // here, not JSONB-embedded like `tag_mappings`/`sensitive_fields` -
    // the same distinction `projection_rebuilds`/`consumed_event_types`
    // already draw for the identical reason.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.command_encryption_keys (
            command_id BIGINT NOT NULL REFERENCES {schema}.commands (id),
            encryption_key_id BIGINT NOT NULL REFERENCES {schema}.encryption_keys (id),
            PRIMARY KEY (command_id, encryption_key_id)
        )"
    )))
    .execute(&mut **tx)
    .await?;

    // Secrets (docs/architecture.md §Secret) - both tables are created here
    // for a brand-new context and by `ensure_secret_tables` on startup for
    // one provisioned before this pass. `secret_versions` FK-references
    // `encryption_keys` above, so it must come after it.
    sqlx::query(sqlx::AssertSqlSafe(secret_versions_table_ddl(&schema)))
        .execute(&mut **tx)
        .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE UNIQUE INDEX secret_versions_unique_active \
         ON {schema}.secret_versions (name) WHERE status = 'active'"
    )))
    .execute(&mut **tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE INDEX secret_versions_by_name ON {schema}.secret_versions (name, version DESC)"
    )))
    .execute(&mut **tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(secret_grants_table_ddl(&schema)))
        .execute(&mut **tx)
        .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE INDEX secret_grants_by_grantee ON {schema}.secret_grants (grantee_role_id, status)"
    )))
    .execute(&mut **tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.projections (
            name TEXT PRIMARY KEY,
            schema TEXT NOT NULL,
            schema_version BIGINT NOT NULL,
            sync BOOLEAN NOT NULL,
            caught_up_to BIGINT,
            requires_capability TEXT
        )"
    )))
    .execute(&mut **tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.projection_consumed_event_types (
            projection_name TEXT NOT NULL REFERENCES {schema}.projections (name),
            event_type_name TEXT NOT NULL REFERENCES {schema}.event_types (name),
            PRIMARY KEY (projection_name, event_type_name)
        )"
    )))
    .execute(&mut **tx)
    .await?;

    // `PRIMARY KEY (projection_name, status)` - not `projection_name`
    // alone - is what actually lets a pending and a building row coexist
    // for the same projection (invariant `UniqueRebuildPerProjectionAndStatus`'s
    // own "at most one pending and at most one building... the two
    // coexisting is the deliberate case"), rather than structurally
    // capping every projection at one rebuild, full stop, regardless of
    // status. `projection_rebuild_consumed_event_types`/
    // `projection_rebuild_state` below both follow suit, carrying their
    // own `status` column and FK-ing against the composite key, so a
    // pending row's own consumed-types set and a building row's own
    // fold-in-progress state never get mixed up when both exist at once.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.projection_rebuilds (
            projection_name TEXT NOT NULL REFERENCES {schema}.projections (name),
            schema TEXT NOT NULL,
            schema_version BIGINT NOT NULL,
            sync BOOLEAN NOT NULL,
            caught_up_to BIGINT,
            status TEXT NOT NULL CHECK (status IN ('pending', 'building')),
            PRIMARY KEY (projection_name, status)
        )"
    )))
    .execute(&mut **tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.projection_rebuild_consumed_event_types (
            projection_name TEXT NOT NULL,
            status TEXT NOT NULL,
            event_type_name TEXT NOT NULL REFERENCES {schema}.event_types (name),
            PRIMARY KEY (projection_name, status, event_type_name),
            FOREIGN KEY (projection_name, status)
                REFERENCES {schema}.projection_rebuilds (projection_name, status)
        )"
    )))
    .execute(&mut **tx)
    .await?;

    // A building `ProjectionRebuild`'s own private fold - "second ...
    // nothing reads until it is complete" (the note above
    // `RegisterProjection`), never the same rows as the live projection's
    // own `projection_state` below, since both can exist at once during a
    // replay window. `key` names which instance a row is (§9's "keyed /
    // multi-row Projections" pass - see the `entity Projection` note in
    // the spec) - `""` for a projection that never overrides
    // `Projection::keys()`, the same single implicit instance every such
    // projection already had. Always created lazily, on first touch, by
    // whichever of `insert_event_and_update_sync_projections`/
    // `catch_up_bounded_context` reaches this key first - there is no
    // single call site that knows every instance a projection will ever
    // have ahead of time.
    // `as_of_sequence` (issue #25's investigation - see
    // `apply_projection_fold_update`'s own doc comment for the full
    // story): the highest event sequence actually folded into *this row*,
    // mirroring `snapshots.as_of_sequence` exactly. Without it, two
    // instances racing the same key's row lock both re-read the
    // already-folded state and fold the same event into it a second time
    // - proven by a real concurrent test, not just reasoned about.
    // `owner`, like `projection_state.owner` below, is the derived
    // owner-tag value this instance's own folded events carry - see
    // `plugin::Projection::OWNER_TAG_KEY`'s own doc comment. Nullable:
    // most projections declare no owner dimension at all.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.projection_rebuild_state (
            projection_name TEXT NOT NULL,
            status TEXT NOT NULL,
            key TEXT NOT NULL,
            state TEXT NOT NULL,
            owner TEXT,
            as_of_sequence BIGINT NOT NULL DEFAULT -1,
            updated_at TIMESTAMPTZ NOT NULL,
            PRIMARY KEY (projection_name, status, key),
            FOREIGN KEY (projection_name, status)
                REFERENCES {schema}.projection_rebuilds (projection_name, status)
        )"
    )))
    .execute(&mut **tx)
    .await?;

    // A sync projection's own materialised state (`project()`'s own
    // fold output, JSON-encoded, one row per instance/`key` - see the
    // note on `projection_rebuild_state` just above) - see
    // docs/architecture.md's write-up of §8 item 6 and §9's "keyed /
    // multi-row Projections" pass. Created lazily, on first touch, not
    // seeded at registration time - a projection's own instances aren't
    // known until events actually name them.
    //
    // `owner` (cross-tenant projection read fix, docs/architecture.md's
    // own write-up of this pass): this instance's own derived owner-tag
    // value, or null when the projection declares no
    // `Projection::OWNER_TAG_KEY` or no consuming event has supplied one
    // yet. Set/refreshed by whichever fold call site (`insert_event_and_
    // update_sync_projections_in_tx`/`catch_up_bounded_context`/
    // `fold_history_into_new_sync_projection`) touches this row -
    // `apply_projection_fold_update`'s own doc comment. Read by
    // `get_projection_state`/`projections::query_projection`'s own
    // enforcement.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.projection_state (
            projection_name TEXT NOT NULL REFERENCES {schema}.projections (name),
            key TEXT NOT NULL,
            state TEXT NOT NULL,
            owner TEXT,
            as_of_sequence BIGINT NOT NULL DEFAULT -1,
            updated_at TIMESTAMPTZ NOT NULL,
            PRIMARY KEY (projection_name, key)
        )"
    )))
    .execute(&mut **tx)
    .await?;
    // issue #25 - `projection_partition_progress`, a brand-new
    // table, so `ensure_projection_partition_progress_table`'s own
    // `CREATE TABLE IF NOT EXISTS` is the whole story here too - see its
    // own doc comment. Must run after `projections` (just above) exists,
    // since its own `projection_name` column references it.
    ensure_projection_partition_progress_table(&mut **tx, bounded_context).await?;

    // Backs `next_sequence` - one row, seeded below, incremented under
    // the row lock its own `UPDATE ... RETURNING` acquires. `-1` is
    // "nothing allocated yet", so the first call returns `0` - the same
    // convention `after_sequence.unwrap_or(-1)`/`highest_sequence`'s
    // `None` case use throughout skilj-core.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.sequence (next_value BIGINT NOT NULL)"
    )))
    .execute(&mut **tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.sequence (next_value) VALUES (-1)"
    )))
    .execute(&mut **tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.events (
            sequence BIGINT PRIMARY KEY,
            event_type_name TEXT NOT NULL REFERENCES {schema}.event_types (name),
            payload TEXT NOT NULL,
            metadata_type TEXT NOT NULL,
            metadata_version BIGINT NOT NULL,
            metadata_client_id TEXT NOT NULL,
            metadata_created_at TIMESTAMPTZ NOT NULL,
            metadata_correlation_id TEXT,
            metadata_causation_id TEXT,
            tags JSONB NOT NULL DEFAULT '[]',
            origin_kind TEXT NOT NULL CHECK (
                origin_kind IN ('external_triggered', 'directly_created', 'command_triggered', 'system_triggered')
            ),
            origin_source_content TEXT,
            origin_source_context TEXT,
            origin_command_id BIGINT REFERENCES {schema}.commands (id)
        )"
    )))
    .execute(&mut **tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE INDEX events_by_type ON {schema}.events (event_type_name, sequence)"
    )))
    .execute(&mut **tx)
    .await?;
    // issue #18 - backs `event_store::query_events`/`count_events`'
    // own new correlation_id filter. Same "cold-start/large-history
    // nicety, not a correctness requirement" register as §19's tag index
    // was: both functions already operate on an in-memory slice.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE INDEX events_by_correlation_id ON {schema}.events (metadata_correlation_id) \
         WHERE metadata_correlation_id IS NOT NULL"
    )))
    .execute(&mut **tx)
    .await?;
    // No index on `tags`: tag reads go through `event_tags` (§198, §210).
    // §19's GIN index on it, `events_by_tags`, is dropped from bounded
    // contexts provisioned before (`drop_events_by_tags_index`).
    // docs/architecture.md §19's "Problem 2" fix - `Snapshot`'s own
    // storage, deliberately not shared with `projection_state` above
    // (see `crate::plugin::Snapshot`'s own doc comment for why). One
    // row per `(snapshot_name, tag_key, tag_value)` - `tag_value` alone
    // isn't unique across different snapshot definitions that happen to
    // share a `tag_key`, hence the three-column key rather than two.
    // `snapshot_version` is checked against `Snapshot::VERSION` before a
    // row is ever trusted - a mismatch is treated as if the row doesn't
    // exist, never read, so there's no `CHECK`/foreign key tying it to
    // anything: an old-version row is inert data until the next catch-up
    // tick overwrites it.
    // `owner` (cross-tenant read fix, docs/architecture.md's own
    // write-up of these passes): this row's own derived owner-tag value,
    // or null when the snapshot declares no `Snapshot::OWNER_TAG_KEY` or
    // no folded event has supplied one yet - `catch_up_snapshots`' own
    // fold loop sets/refreshes it. Read by `get_snapshot_state_and_owner`/
    // `snapshot_query::inspect_snapshot_field`'s own enforcement.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.snapshots (
            snapshot_name TEXT NOT NULL,
            tag_key TEXT NOT NULL,
            tag_value TEXT NOT NULL,
            snapshot_version BIGINT NOT NULL,
            as_of_sequence BIGINT NOT NULL,
            state JSONB NOT NULL,
            owner TEXT,
            updated_at TIMESTAMPTZ NOT NULL,
            PRIMARY KEY (snapshot_name, tag_key, tag_value)
        )"
    )))
    .execute(&mut **tx)
    .await?;
    // The background catch-up task's own position, one row per
    // `snapshot_name` - `Projection`'s `caught_up_to` column plays the
    // identical role, but isn't reused here (see `crate::plugin::Snapshot`'s
    // own doc comment): `MAX(as_of_sequence)` across `snapshots` rows
    // above can't stand in for this, since a rarely-touched tag value's
    // own row can be correctly stale (nothing has happened for it)
    // without the walk itself being behind.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.snapshot_progress (
            snapshot_name TEXT PRIMARY KEY,
            caught_up_to BIGINT NOT NULL
        )"
    )))
    .execute(&mut **tx)
    .await?;
    // issue #25 (docs/architecture.md §52) -
    // `snapshot_partition_progress`, a brand-new table, so
    // `ensure_snapshot_partition_progress_table`'s own `CREATE TABLE IF
    // NOT EXISTS` is the whole story here too - see its own doc
    // comment. No ordering constraint to worry about (unlike
    // `projection_partition_progress`'s own `REFERENCES {schema}.projections`):
    // `snapshots`/`snapshot_progress` have no backing registration table
    // either, so this one doesn't reference anything.
    ensure_snapshot_partition_progress_table(&mut **tx, bounded_context).await?;
    // See `command_encryption_keys` above - the identical join-table
    // treatment, keyed by `sequence` instead of a synthetic id since
    // `events.sequence` is already `Event`'s own natural primary key.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.event_encryption_keys (
            event_sequence BIGINT NOT NULL REFERENCES {schema}.events (sequence),
            encryption_key_id BIGINT NOT NULL REFERENCES {schema}.encryption_keys (id),
            PRIMARY KEY (event_sequence, encryption_key_id)
        )"
    )))
    .execute(&mut **tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.access_tokens (
            id TEXT PRIMARY KEY,
            kind TEXT NOT NULL CHECK (kind IN ('external_event', 'direct_creation', 'event_read', 'command')),
            secret TEXT NOT NULL, -- hash_secret's output, never the plaintext (see AccessToken.secret)
            status TEXT NOT NULL CHECK (status IN ('active', 'revoked')),
            created_at TIMESTAMPTZ NOT NULL,
            revoked_at TIMESTAMPTZ,
            event_type_name TEXT REFERENCES {schema}.event_types (name),
            command_type_name TEXT REFERENCES {schema}.command_types (name),
            -- EventReadToken.scope/ExternalEventToken.scope/
            -- DirectCreationToken.scope/CommandToken.scope - one column
            -- for all four kinds, the cross-tenant read/write fix
            -- (docs/architecture.md's own write-up of these passes).
            -- Null (the default before these fixes existed, and still
            -- the default for a token minted with none) means
            -- unrestricted, for every kind alike.
            scope TEXT,
            -- EventReadToken.start_from/.start_at_sequence/.start_at_time -
            -- meaningful only for the 'event_read' kind (see
            -- ensure_event_read_token_start_from_column's own doc comment
            -- for why a fresh table still declares these with the
            -- identical defaults a retrofitted one gets).
            start_from TEXT NOT NULL DEFAULT 'beginning'
                CHECK (start_from IN ('beginning', 'latest', 'at_sequence', 'at_time')),
            start_at_sequence BIGINT,
            start_at_time TIMESTAMPTZ,
            CHECK (
                (kind = 'command' AND command_type_name IS NOT NULL AND event_type_name IS NULL)
                OR (kind != 'command' AND event_type_name IS NOT NULL AND command_type_name IS NULL)
            )
        )"
    )))
    .execute(&mut **tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE {schema}.read_cursors (
            token_id TEXT PRIMARY KEY REFERENCES {schema}.access_tokens (id),
            ack_mode TEXT NOT NULL CHECK (ack_mode IN ('auto_advance', 'manual_ack')),
            sequence BIGINT NOT NULL,
            updated_at TIMESTAMPTZ NOT NULL,
            checked_out_at TIMESTAMPTZ
        )"
    )))
    .execute(&mut **tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(private_field_grants_table_ddl(&schema)))
        .execute(&mut **tx)
        .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE INDEX private_field_grants_by_grantee ON {schema}.private_field_grants (grantee_role_id, status)"
    )))
    .execute(&mut **tx)
    .await?;
    // issue #98 - the approval policy and proposal tables. Both
    // are brand new, so the same DDL `ensure_command_approval_tables`
    // patches an existing context with works here too.
    sqlx::query(sqlx::AssertSqlSafe(command_approval_policies_table_ddl(
        &schema,
    )))
    .execute(&mut **tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(command_proposals_table_ddl(&schema)))
        .execute(&mut **tx)
        .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE INDEX command_proposals_by_status \
         ON {schema}.command_proposals (status, created_at)"
    )))
    .execute(&mut **tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE UNIQUE INDEX command_proposals_pending_idempotency \
         ON {schema}.command_proposals (command_type_name, metadata_client_id, idempotency_key) \
         WHERE status = 'pending' AND idempotency_key IS NOT NULL"
    )))
    .execute(&mut **tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE INDEX command_proposals_page_order \
         ON {schema}.command_proposals (created_at, id)"
    )))
    .execute(&mut **tx)
    .await?;

    // docs/architecture.md §104 - after every table it touches exists.
    add_registration_version_columns(&mut **tx, bounded_context).await?;
    ensure_registrations_generation(&mut **tx, bounded_context).await?;
    ensure_event_tags_index(&mut **tx, bounded_context).await?;
    ensure_blind_tags_table(&mut **tx, bounded_context).await?;
    Ok(())
}

/// `entity PrivateFieldGrant` - `event_sequence`/`command_id` are this
/// table's own foreign keys into `events`/`commands`, one column each
/// rather than the `AccessToken`-style single discriminated pair, since
/// both may be null at once (a blanket grant) but never both non-null -
/// enforced here, not just by `access_control::grant_private_field_access_for_event`/
/// `_for_command` alone, the same "the invariant is a real constraint,
/// not merely an implication of how callers happen to behave" stance
/// `access_tokens`' own `kind`-vs-`event_type_name`/`command_type_name`
/// CHECK already takes. `command_id` references `commands.id` (the
/// internal `BIGSERIAL`, not `Command.id`/`commands.external_id`) -
/// `origin_command_id` on `events` already sets this precedent.
/// `grantor_role_id`/`grantee_role_id` reference `public.roles (id)`
/// across schemas - Postgres allows this freely, and `roles` is
/// guaranteed to exist by the time any bounded context is provisioned
/// (the global migration set runs first, at `db::migrate()`). Shared
/// between `provision_bounded_context_schema` (a brand-new context) and
/// `ensure_private_field_grants_table` below (an existing one, added
/// after this table existed) - one DDL string, not two copies to keep in
/// sync.
fn private_field_grants_table_ddl(schema: &str) -> String {
    format!(
        "CREATE TABLE IF NOT EXISTS {schema}.private_field_grants (
            id TEXT PRIMARY KEY,
            grantor_role_id TEXT NOT NULL REFERENCES public.roles (id),
            grantee_role_id TEXT NOT NULL REFERENCES public.roles (id),
            event_sequence BIGINT REFERENCES {schema}.events (sequence),
            command_id BIGINT REFERENCES {schema}.commands (id),
            status TEXT NOT NULL CHECK (status IN ('active', 'revoked')),
            created_at TIMESTAMPTZ NOT NULL,
            revoked_at TIMESTAMPTZ,
            CHECK (event_sequence IS NULL OR command_id IS NULL)
        )"
    )
}

/// `ensure_idempotency_keys_table`'s own doc comment's "no general
/// per-bounded-context schema migration mechanism" applies identically
/// here, just for `private_field_grants` instead of `idempotency_keys` -
/// called unconditionally on every `build()`, for a bounded context
/// provisioned before this table existed.
pub async fn ensure_private_field_grants_table(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(private_field_grants_table_ddl(&schema)))
        .execute(pool)
        .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(&schema, "private_field_grants_by_grantee", format!("CREATE INDEX IF NOT EXISTS private_field_grants_by_grantee ON {schema}.private_field_grants (grantee_role_id, status)"))))
    .execute(pool)
    .await?;
    Ok(())
}

// --- Command approvals (issue #98) ---

/// `entity CommandApprovalPolicy` - kept in its own table rather than as
/// columns on `command_types`, so adding it changed no `CommandType`
/// literal anywhere. A row's presence is what makes the type require
/// approval; `approver_role`/`deadline_seconds`/`allow_self_approval` are
/// refinements.
fn command_approval_policies_table_ddl(schema: &str) -> String {
    format!(
        "CREATE TABLE IF NOT EXISTS {schema}.command_approval_policies (
            command_type_name TEXT PRIMARY KEY REFERENCES {schema}.command_types (name),
            approver_role TEXT,
            deadline_seconds BIGINT CHECK (deadline_seconds IS NULL OR deadline_seconds > 0),
            allow_self_approval BOOLEAN NOT NULL DEFAULT false
        )"
    )
}

/// `entity CommandProposal`. `payload` is encrypted at rest exactly as
/// `commands.payload` is; `metadata_*` mirror the `commands` table's own
/// columns so approval can run the ordinary submission pipeline with the
/// original submitter's `client_id`, correlation and causation ids.
/// `status = 'approving'` is the claim an approver takes before running
/// that pipeline; `command_external_id` is `commands.external_id` once
/// approval produced one.
fn command_proposals_table_ddl(schema: &str) -> String {
    format!(
        "CREATE TABLE IF NOT EXISTS {schema}.command_proposals (
            id TEXT PRIMARY KEY,
            command_type_name TEXT NOT NULL REFERENCES {schema}.command_types (name),
            payload TEXT NOT NULL,
            metadata_version BIGINT NOT NULL,
            metadata_client_id TEXT NOT NULL,
            metadata_created_at TIMESTAMPTZ NOT NULL,
            metadata_correlation_id TEXT,
            metadata_causation_id TEXT,
            status TEXT NOT NULL CHECK (status IN \
                ('pending', 'approving', 'approved', 'rejected', 'expired', 'forgotten')),
            idempotency_key TEXT,
            created_at TIMESTAMPTZ NOT NULL,
            expires_at TIMESTAMPTZ,
            decided_at TIMESTAMPTZ,
            decided_by_role_id TEXT REFERENCES public.roles (id),
            rejection_reason TEXT,
            rejection_kind TEXT,
            command_external_id TEXT REFERENCES {schema}.commands (external_id)
        )"
    )
}

pub async fn ensure_command_approval_tables(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    // `command_proposals` references `commands.external_id`, and
    // `command_approval_policies` references `command_types` - both already
    // exist for any context this startup patch runs against. Patched by
    // catalog lookup, not `CREATE ... IF NOT EXISTS`, so an up-to-date
    // context takes no lock at all (docs/architecture.md §158).
    sqlx::query(sqlx::AssertSqlSafe(create_table_patch(
        &schema,
        "command_approval_policies",
        command_approval_policies_table_ddl(&schema),
    )))
    .execute(pool)
    .await?;
    // Added after the table first shipped; `false` keeps an existing policy
    // at the safe default (no self-approval).
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "command_approval_policies",
        &["allow_self_approval"],
        format!(
            "ALTER TABLE {schema}.command_approval_policies \
             ADD COLUMN IF NOT EXISTS allow_self_approval BOOLEAN NOT NULL DEFAULT false"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_table_patch(
        &schema,
        "command_proposals",
        command_proposals_table_ddl(&schema),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(
        &schema,
        "command_proposals_by_status",
        format!(
            "CREATE INDEX command_proposals_by_status \
             ON {schema}.command_proposals (status, created_at)"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(
        &schema,
        "command_proposals_pending_idempotency",
        format!(
            "CREATE UNIQUE INDEX command_proposals_pending_idempotency \
             ON {schema}.command_proposals (command_type_name, metadata_client_id, idempotency_key) \
             WHERE status = 'pending' AND idempotency_key IS NOT NULL"
        ),
    )))
    .execute(pool)
    .await?;
    // `commandProposals`' page order (docs/architecture.md §218).
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(
        &schema,
        "command_proposals_page_order",
        format!(
            "CREATE INDEX command_proposals_page_order \
             ON {schema}.command_proposals (created_at, id)"
        ),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// `ddl` (a bare `CREATE TABLE`) run only when `table` does not exist in
/// `schema`: `CREATE TABLE IF NOT EXISTS` takes a lock before finding it
/// already there, the same startup-cost problem as `create_index_patch`.
fn create_table_patch(schema: &str, table: &str, ddl: String) -> String {
    format!(
        "DO $patch$ BEGIN IF to_regclass({}) IS NULL THEN {ddl}; END IF; END $patch$",
        sql_literal(&format!("{schema}.{table}"))
    )
}

// --- PrivateFieldGrant ---

/// `commands.id` (the internal `BIGSERIAL`) for a given `Command.id`
/// (`commands.external_id`) - the forward half of the translation
/// `insert_private_field_grant` needs; `get_command_by_id` already is the
/// reverse (see its own doc comment, and the note on `PrivateFieldGrant.
/// command_id` in `access_control` for why a grant stores the internal
/// id rather than the external one).
async fn command_internal_id(
    pool: &Pool,
    bounded_context: &str,
    external_id: &str,
) -> crate::error::Result<Option<i64>> {
    let schema = schema_ident(bounded_context);
    let row: Option<(i64,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT id FROM {schema}.commands WHERE external_id = $1"
    )))
    .bind(external_id)
    .fetch_optional(pool)
    .await?;
    Ok(row.map(|(id,)| id))
}

#[derive(sqlx::FromRow)]
struct PrivateFieldGrantRow {
    id: String,
    grantor_role_id: String,
    grantee_role_id: String,
    event_sequence: Option<i64>,
    command_id: Option<i64>,
    status: String,
    created_at: DateTime<Utc>,
    revoked_at: Option<DateTime<Utc>>,
}

impl PrivateFieldGrantRow {
    /// `Ok(None)` - not a panic - when `grantor_role_id`/`grantee_role_id`
    /// names a `Role` that's gone by the time this looks it up, the same
    /// "gone by the time you look" treatment `RoleAccessMappingRow::
    /// into_domain` already gives an analogous race (see that method's
    /// own doc comment, docs/architecture.md's own write-up of that
    /// hardening pass) - `Role` rows are never hard-deleted in this
    /// codebase, so this is a defensive match for a race that shouldn't
    /// occur in practice, not one known to.
    async fn into_domain(
        self,
        pool: &Pool,
        bounded_context: &BoundedContext,
    ) -> crate::error::Result<Option<PrivateFieldGrant>> {
        let Some(grantor) = get_role(pool, &self.grantor_role_id).await? else {
            return Ok(None);
        };
        let Some(grantee) = get_role(pool, &self.grantee_role_id).await? else {
            return Ok(None);
        };
        let command_id = match self.command_id {
            Some(internal_id) => {
                match get_command_by_id(pool, &bounded_context.name, internal_id).await? {
                    Some(command) => Some(command.id),
                    None => return Ok(None),
                }
            }
            None => None,
        };
        Ok(Some(PrivateFieldGrant {
            id: self.id,
            bounded_context: bounded_context.clone(),
            grantor,
            grantee,
            event_sequence: self.event_sequence,
            command_id,
            status: token_status_from_str(&self.status),
            created_at: self.created_at,
            revoked_at: self.revoked_at,
        }))
    }
}

const PRIVATE_FIELD_GRANT_COLUMNS: &str =
    "id, grantor_role_id, grantee_role_id, event_sequence, command_id, status, created_at, revoked_at";

/// Inserts the grant and records nothing: how tests seed one, and a
/// bypass of the access trail (docs/architecture.md §229) for anyone else.
/// Unlike a role mapping, a private-field grant made this way is never
/// baselined, so it has no `PrivateFieldAccessGranted` at all.
/// [`grant_private_field_access_with_trail`] is the write that records it.
#[tracing::instrument(skip_all)]
pub async fn insert_private_field_grant(
    pool: &Pool,
    grant: &PrivateFieldGrant,
) -> crate::error::Result<()> {
    let command_id = private_field_grant_command_id(pool, grant).await?;
    insert_private_field_grant_row(pool, grant, command_id).await
}

/// The internal id of the command a grant names, if it names one.
async fn private_field_grant_command_id(
    pool: &Pool,
    grant: &PrivateFieldGrant,
) -> crate::error::Result<Option<i64>> {
    Ok(match grant.command_id.as_deref() {
        Some(external_id) => Some(
            command_internal_id(pool, &grant.bounded_context.name, external_id)
                .await?
                .expect(
                    "insert_private_field_grant: command_id names a command that doesn't exist",
                ),
        ),
        None => None,
    })
}

async fn insert_private_field_grant_row<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    grant: &PrivateFieldGrant,
    command_id: Option<i64>,
) -> crate::error::Result<()> {
    let schema = schema_ident(&grant.bounded_context.name);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.private_field_grants ({PRIVATE_FIELD_GRANT_COLUMNS}) \
         VALUES ($1,$2,$3,$4,$5,$6,$7,$8)"
    )))
    .bind(&grant.id)
    .bind(&grant.grantor.id)
    .bind(&grant.grantee.id)
    .bind(grant.event_sequence)
    .bind(command_id)
    .bind(token_status_to_str(grant.status))
    .bind(grant.created_at)
    .bind(grant.revoked_at)
    .execute(executor)
    .await?;
    Ok(())
}

/// Every `PrivateFieldGrant` in one bounded context, active or revoked
/// alike - `ListPrivateFieldGrants` itself reads both back (see its own
/// `@guidance`: "what have I shared, and what have I stopped sharing").
/// Also what `render_event`/`render_command`'s own callers pre-load and
/// pass through as `grants` - one shared snapshot, filtered internally
/// by `grantee` (see those functions' own doc comments for why that's
/// enough for every caller in one request, subscribers included).
#[tracing::instrument(skip_all)]
pub async fn list_private_field_grants_for_context(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<Vec<PrivateFieldGrant>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(Vec::new());
    };
    let schema = schema_ident(bounded_context);
    let rows: Vec<PrivateFieldGrantRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {PRIVATE_FIELD_GRANT_COLUMNS} FROM {schema}.private_field_grants"
    )))
    .fetch_all(pool)
    .await?;
    grants_from_rows(pool, &bc, rows).await
}

/// The active grants naming `grantee` in `bounded_context` - all that
/// rendering a record for `grantee` ever consults (`entitled_to_read_private_field`
/// only counts an active grant whose grantee is the reader's own Role).
/// Every event and command read renders with these, a subscription for
/// every event it delivers, so this reads through the
/// `private_field_grants_by_grantee` index rather than the whole table,
/// which is what those reads used to load, a few queries per row
/// (docs/architecture.md §124).
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_active_private_field_grants_for_grantee(
    pool: &Pool,
    bounded_context: &str,
    grantee: &Role,
) -> crate::error::Result<Vec<PrivateFieldGrant>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(Vec::new());
    };
    let schema = schema_ident(bounded_context);
    let rows: Vec<PrivateFieldGrantRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {PRIVATE_FIELD_GRANT_COLUMNS} FROM {schema}.private_field_grants \
         WHERE grantee_role_id = $1 AND status = 'active'"
    )))
    .bind(&grantee.id)
    .fetch_all(pool)
    .await?;
    grants_from_rows(pool, &bc, rows).await
}

/// `PrivateFieldGrantRow::into_domain` for many rows at once: every Role
/// they name in one query, every command they name in one more, instead
/// of two or more queries per row. Rows naming a Role or command that's
/// gone are skipped, as `into_domain` skips them.
async fn grants_from_rows(
    pool: &Pool,
    bc: &BoundedContext,
    rows: Vec<PrivateFieldGrantRow>,
) -> crate::error::Result<Vec<PrivateFieldGrant>> {
    if rows.is_empty() {
        return Ok(Vec::new());
    }
    let mut role_ids: Vec<&str> = rows
        .iter()
        .flat_map(|r| [r.grantor_role_id.as_str(), r.grantee_role_id.as_str()])
        .collect();
    role_ids.sort_unstable();
    role_ids.dedup();
    let roles: std::collections::HashMap<String, Role> =
        sqlx::query_as::<_, RoleRow>(sqlx::AssertSqlSafe(format!(
            "SELECT {ROLE_COLUMNS} FROM roles WHERE id = ANY($1)"
        )))
        .bind(&role_ids)
        .fetch_all(pool)
        .await?
        .into_iter()
        .map(|row| {
            let role = row.into_domain();
            (role.id.clone(), role)
        })
        .collect();

    let mut command_ids: Vec<i64> = rows.iter().filter_map(|r| r.command_id).collect();
    command_ids.sort_unstable();
    command_ids.dedup();
    let command_external_ids: std::collections::HashMap<i64, String> = if command_ids.is_empty() {
        std::collections::HashMap::new()
    } else {
        let schema = schema_ident(&bc.name);
        sqlx::query_as::<_, (i64, String)>(sqlx::AssertSqlSafe(format!(
            "SELECT id, external_id FROM {schema}.commands WHERE id = ANY($1)"
        )))
        .bind(&command_ids)
        .fetch_all(pool)
        .await?
        .into_iter()
        .collect()
    };

    Ok(rows
        .into_iter()
        .filter_map(|row| {
            let command_id = match row.command_id {
                Some(internal_id) => Some(command_external_ids.get(&internal_id)?.clone()),
                None => None,
            };
            Some(PrivateFieldGrant {
                id: row.id,
                bounded_context: bc.clone(),
                grantor: roles.get(&row.grantor_role_id)?.clone(),
                grantee: roles.get(&row.grantee_role_id)?.clone(),
                event_sequence: row.event_sequence,
                command_id,
                status: token_status_from_str(&row.status),
                created_at: row.created_at,
                revoked_at: row.revoked_at,
            })
        })
        .collect())
}

#[tracing::instrument(skip_all)]
pub async fn get_private_field_grant(
    pool: &Pool,
    bounded_context: &str,
    id: &str,
) -> crate::error::Result<Option<PrivateFieldGrant>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(None);
    };
    let schema = schema_ident(bounded_context);
    let row: Option<PrivateFieldGrantRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {PRIVATE_FIELD_GRANT_COLUMNS} FROM {schema}.private_field_grants WHERE id = $1"
    )))
    .bind(id)
    .fetch_optional(pool)
    .await?;
    match row {
        Some(row) => row.into_domain(pool, &bc).await,
        None => Ok(None),
    }
}

/// Persists a `revoke_private_field_access` outcome - a status-only
/// update, the same shape `revoke_active_role_access_mapping` already
/// has, addressed by `id` rather than a composite key since a grant's
/// own `id` is already unambiguous (see `PrivateFieldGrant.id`'s own doc
/// comment).
/// `true` when an active grant was updated, `false` when there was none
/// (already revoked by a concurrent request): the trail records a
/// revocation only on `true`.
/// Records nothing itself, so a bypass of the access trail like
/// [`insert_private_field_grant`]: [`revoke_private_field_access_with_trail`]
/// is the write that records `PrivateFieldAccessRevoked`.
#[tracing::instrument(skip_all)]
pub async fn update_private_field_grant<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    grant: &PrivateFieldGrant,
) -> crate::error::Result<bool> {
    let schema = schema_ident(&grant.bounded_context.name);
    let done = sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.private_field_grants SET status = $1, revoked_at = $2 \
         WHERE id = $3 AND status = 'active'"
    )))
    .bind(token_status_to_str(grant.status))
    .bind(grant.revoked_at)
    .bind(&grant.id)
    .execute(executor)
    .await?;
    Ok(done.rows_affected() == 1)
}

/// `GrantPrivateFieldAccessForEvent`/`ForCommand`'s write: inserts the
/// grant and records `PrivateFieldAccessGranted` in one transaction, so the
/// admin context's log and the grant table cannot disagree (§229). Fails,
/// and grants nothing, when the admin bounded context is missing.
#[tracing::instrument(skip_all)]
pub async fn grant_private_field_access_with_trail(
    pool: &Pool,
    grant: &PrivateFieldGrant,
) -> crate::error::Result<()> {
    let admin = require_admin_bounded_context(pool).await?;
    let command_id = private_field_grant_command_id(pool, grant).await?;
    let mut tx = pool.begin().await?;
    insert_private_field_grant_row(&mut *tx, grant, command_id).await?;
    record_access_event(&mut tx, &admin, AccessChange::private_field_granted(grant)).await?;
    tx.commit().await?;
    Ok(())
}

/// `RevokePrivateFieldAccess`'s write: ends the active grant and records
/// `PrivateFieldAccessRevoked` in one transaction. Nothing is recorded, and
/// `false` is returned, when the grant was no longer active.
#[tracing::instrument(skip_all)]
pub async fn revoke_private_field_access_with_trail(
    pool: &Pool,
    revoked: &PrivateFieldGrant,
) -> crate::error::Result<bool> {
    let admin = require_admin_bounded_context(pool).await?;
    let mut tx = pool.begin().await?;
    if !update_private_field_grant(&mut *tx, revoked).await? {
        return Ok(false);
    }
    record_access_event(
        &mut tx,
        &admin,
        AccessChange::private_field_revoked(revoked),
    )
    .await?;
    tx.commit().await?;
    Ok(true)
}

/// `idempotency_keys` - a caller-supplied idempotency key on command
/// submission (issue #12), one row per `(command_type_name,
/// client_id, idempotency_key)` that has ever produced a real `Accepted`
/// outcome. A duplicate submission bearing the same key from the same
/// caller short-circuits to the stored `triggered_event_sequences`
/// rather than being re-decided - see `submit_command`'s own doc
/// comment for the full design.
///
/// `client_id`-scoped since [docs/architecture.md §37](../../../docs/architecture.md#idempotency-keys-client-id-scoping) - originally
/// `(command_type_name, idempotency_key)` only (issue #12's own
/// deliberate call: "not also per-caller"), which held up fine under
/// that decision's own assumption - a well-randomized caller-chosen key
/// (a UUID, say) never collides with another caller's by accident. Owner-
/// tag multi-tenancy ([§23](../../../docs/architecture.md#cross-tenant-projection-read-fix-owner-tag)/[§25](../../../docs/architecture.md#cross-tenant-read-fix-command-query)/[§30](../../../docs/architecture.md#cross-tenant-write-fix-owner-tag-scoping)), built after issue #12, broke that
/// assumption: many distinct tenants (distinct `CommandToken`s/
/// `RoleAccessMapping`s, disambiguated only by their own `scope`,
/// invisible to this table) routinely submit the *same* `CommandType`,
/// and a business-derived key (an order id, an invoice number - a
/// common, even recommended, idempotency-key convention) from one
/// tenant can plausibly coincide with an unrelated tenant's own, with no
/// attacker needed at all. A collision silently swallowed the second
/// tenant's real submission as a `Deduplicated` hit against the first
/// tenant's own stored sequences - a live bug since issue #12 shipped in
/// 0.0.2, not merely `CrossContextRoute`'s narrower predictable-key
/// variant ([§36](../../../docs/architecture.md#cross-context-route)) of the same root cause. `client_id` (`token.id` for
/// REST, `access_mapping.role.id` for GraphQL, `"cross-context-route"`
/// for that internal caller - `authorise_command_trigger`/
/// `authorise_command_submission`'s own `CommandAuthorised.client_id`)
/// was already threaded through every caller for the resulting event's
/// own metadata; it's simply never scoped the idempotency lookup before
/// now. This structurally closes `CrossContextRoute`'s own issue too,
/// since no external caller's `client_id` is ever caller-suppliable -
/// it's always derived server-side from an authenticated token/role, so
/// no external submission can ever land under `"cross-context-route"`'s
/// own partition regardless of what `idempotency_key` string it uses.
/// `RESERVED_IDEMPOTENCY_KEY_PREFIX`/`reject_reserved_idempotency_key`
/// stay in place as harmless defense-in-depth, no longer load-bearing.
///
/// See `migrate_idempotency_keys_client_id_scoping` for how an
/// already-provisioned bounded context (real ones exist, back to 0.0.2)
/// gets patched onto this shape - this function alone only ever governs
/// a brand-new one.
///
/// `impl PgExecutor`, the same "works on `&Pool` autocommit or inside a
/// caller's own open `Transaction`" treatment `update_role` already
/// gets: `provision_bounded_context_schema` above needs the latter (one
/// more table for a brand-new bounded context, inside its own
/// provisioning transaction); the per-bounded-context startup loop in
/// `skilj/src/lib.rs` needs the former, patching a bounded context
/// provisioned *before* this feature existed. `CREATE TABLE IF NOT
/// EXISTS`, called unconditionally on every `build()`, is the whole
/// migration story for a table that doesn't exist yet at all - there's
/// no general per-bounded-context schema migration mechanism in this
/// codebase (`provision_bounded_context_schema` itself only ever runs
/// once, at creation), and this deliberately isn't one either, just a
/// small, targeted, idempotent patch for this one table's existence.
#[tracing::instrument(skip_all)]
pub async fn ensure_idempotency_keys_table<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    // The `created_at` index serves `delete_expired_idempotency_keys`
    // (docs/architecture.md §87).
    let index = create_index_patch(
        &schema,
        "idempotency_keys_created_at",
        format!(
            "CREATE INDEX IF NOT EXISTS idempotency_keys_created_at \
             ON {schema}.idempotency_keys (created_at)"
        ),
    );
    sqlx::raw_sql(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE IF NOT EXISTS {schema}.idempotency_keys (
            command_type_name TEXT NOT NULL,
            client_id TEXT NOT NULL,
            idempotency_key TEXT NOT NULL,
            triggered_event_sequences BIGINT[] NOT NULL,
            created_at TIMESTAMPTZ NOT NULL,
            PRIMARY KEY (command_type_name, client_id, idempotency_key)
        );
        {index}"
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// Deletes up to `batch` idempotency keys recorded before `cutoff` in
/// `bounded_context`, returning how many went. `SkiljBuilder`'s
/// retention task calls it until a call deletes fewer than `batch`, so
/// no single statement holds locks on an unbounded number of rows
/// (docs/architecture.md §87). A key gone is simply unseen: a later
/// submission bearing it is processed as new.
pub async fn delete_expired_idempotency_keys(
    pool: &Pool,
    bounded_context: &str,
    cutoff: DateTime<Utc>,
    batch: i64,
) -> crate::error::Result<u64> {
    delete_expired_keys(pool, bounded_context, "idempotency_keys", cutoff, batch).await
}

/// [`delete_expired_idempotency_keys`]' twin for `external_message_keys`
/// (docs/architecture.md §175): the same retention, the same batching.
pub async fn delete_expired_external_message_keys(
    pool: &Pool,
    bounded_context: &str,
    cutoff: DateTime<Utc>,
    batch: i64,
) -> crate::error::Result<u64> {
    delete_expired_keys(
        pool,
        bounded_context,
        "external_message_keys",
        cutoff,
        batch,
    )
    .await
}

/// The batched delete both key tables share. `table` is one of the two
/// names above, never caller input.
async fn delete_expired_keys(
    pool: &Pool,
    bounded_context: &str,
    table: &'static str,
    cutoff: DateTime<Utc>,
    batch: i64,
) -> crate::error::Result<u64> {
    let schema = schema_ident(bounded_context);
    let result = sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.{table} WHERE ctid IN ( \
             SELECT ctid FROM {schema}.{table} WHERE created_at < $1 LIMIT $2)"
    )))
    .bind(cutoff)
    .bind(batch)
    .execute(pool)
    .await?;
    Ok(result.rows_affected())
}

/// Deletes up to `batch` deadlines in `bounded_context` resolved (fired,
/// cancelled, parked or forgotten) before `cutoff`, returning how many
/// went - `SkiljBuilder::deadline_retention`'s task (docs/architecture.md
/// §163). A pending or firing deadline is never touched. Safe because a
/// schedule's cursor only moves forward: the deleted row's deterministic
/// id (`schedule:sequence`) is never derived again, so nothing relies on
/// its `ON CONFLICT (id) DO NOTHING` once it's gone.
pub async fn delete_expired_deadlines(
    pool: &Pool,
    bounded_context: &str,
    cutoff: DateTime<Utc>,
    batch: i64,
) -> crate::error::Result<u64> {
    let schema = schema_ident(bounded_context);
    let result = sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.deadlines WHERE ctid IN ( \
             SELECT ctid FROM {schema}.deadlines \
             WHERE status NOT IN ('pending', 'firing') AND resolved_at < $1 LIMIT $2)"
    )))
    .bind(cutoff)
    .bind(batch)
    .execute(pool)
    .await?;
    Ok(result.rows_affected())
}

/// Patches an already-provisioned bounded context's `idempotency_keys`
/// (real ones exist, back to 0.0.2 - see `ensure_idempotency_keys_table`'s
/// own doc comment for the full story) onto the `client_id`-scoped shape
/// a brand-new one gets directly. `ALTER TABLE ... ADD COLUMN IF NOT
/// EXISTS`, this file's own established idempotent-patch idiom
/// (`ensure_projection_state_owner_columns`/`ensure_event_scoping_columns`),
/// isn't enough by itself here - the whole point is this column must be
/// *part of the primary key*, and Postgres has no `ADD CONSTRAINT IF NOT
/// EXISTS`/`ALTER PRIMARY KEY` form to lean on for that half.
///
/// Backfilled `''` (never a real `client_id` - always a server-derived
/// token/role id or `"cross-context-route"`, never empty) rather than
/// deleted, matching this codebase's own explicit "no retention/TTL,
/// nothing is ever deleted" precedent ([§21](../../../docs/architecture.md#optional-idempotency-key-submission)) - but, on the user's own
/// explicit call, deliberately left permanently *unmatchable* by
/// `lookup_idempotency_key` rather than kept as a fallback for whichever
/// caller retries that same string first. Two ways to fail were on the
/// table for a row this migration cannot attribute to its original
/// caller (that information was simply never recorded pre-migration,
/// not recoverable by any cleverer migration): keep it matchable for
/// anyone, which fully closes future double-execution risk but leaves a
/// frozen, non-growing set of already-used key strings still able to
/// collide across unrelated future callers; or retire it, which fully
/// closes *that* risk but means a genuine retry of a request submitted
/// just before this migration ran won't be recognised as a duplicate -
/// `decide()` runs again, possibly inserting a real command's events
/// twice. Chosen: retire it - this fix exists specifically to close the
/// cross-tenant collision class, and leaving any part of it open, even
/// a shrinking one, was judged worse than the narrower, one-time
/// migration-boundary risk. The row stays in the table (never deleted),
/// permanently orphaned rather than reachable.
///
/// Wrapped in one transaction (fine - Postgres DDL is fully
/// transactional, unlike MySQL's) holding a `pg_advisory_xact_lock`
/// keyed by this bounded context's own schema name for its entire
/// duration - not because skipping it would be unsafe (verified
/// directly, not assumed: with the lock removed, several concurrent
/// callers racing the exact same pre-migration table in a real test
/// never errored, because `DROP CONSTRAINT IF EXISTS` before `ADD
/// PRIMARY KEY` means there is never an *existing* primary key for a
/// second `ADD PRIMARY KEY` to collide with, and Postgres's own
/// whole-transaction-duration `ACCESS EXCLUSIVE` table lock from the
/// first `ALTER TABLE` already fully serializes every concurrent
/// instance's 3-statement sequence against this same table). The real,
/// more modest reason to keep it: without it, every *loser* of that
/// natural serialization still repeats the whole `DROP CONSTRAINT`/`ADD
/// PRIMARY KEY` dance once it's their turn (each is a genuine
/// idempotent no-op end state, but a real catalog write nonetheless,
/// once per racer) - the lock lets every loser's own upfront
/// `already_migrated` recheck below see the winner's now-committed
/// change and skip straight to a plain read, so only the first instance
/// through ever does real DDL work, and two skilj instances patching
/// the same shared Postgres at startup (the existing
/// concurrent-bounded-context warm-up loop in `skilj/src/lib.rs`,
/// issue #15, only protects against a race *within* one
/// process - a real fleet runs more than one) don't churn the catalog
/// once each for no reason. `_xact` (transaction-scoped, not
/// session-scoped) releases automatically at this function's own commit
/// or rollback and is guaranteed to run on the same connection as the
/// statements it protects, both being inside the one transaction -
/// unlike a bare `pg_advisory_lock` against a `&Pool`, where the lock
/// and the work it protects could each be handed a different pooled
/// connection entirely, making the lock meaningless.
#[tracing::instrument(skip_all)]
pub async fn migrate_idempotency_keys_client_id_scoping(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    // Mirrors `schema_ident`'s own `"bc_{bounded_context}"` shape, minus
    // the quoting - `information_schema` stores identifiers unquoted
    // (quoting is parse-time syntax, not a stored property), so a query
    // against it needs the raw name, not the `format!`-ready quoted one
    // every DDL string above uses.
    let raw_schema = format!("bc_{bounded_context}");

    let mut tx = pool.begin().await?;

    sqlx::query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)")
        .bind(&raw_schema)
        .execute(&mut *tx)
        .await?;

    // Checked against the primary key specifically, not merely the
    // column's existence - robust even against a hypothetical partially-
    // applied prior attempt (column added, PK swap not yet reached).
    let already_migrated: bool = sqlx::query_scalar(
        "SELECT EXISTS (
            SELECT 1 FROM information_schema.key_column_usage
            WHERE table_schema = $1 AND table_name = 'idempotency_keys'
              AND constraint_name = 'idempotency_keys_pkey'
              AND column_name = 'client_id'
        )",
    )
    .bind(&raw_schema)
    .fetch_one(&mut *tx)
    .await?;

    if already_migrated {
        tx.commit().await?;
        return Ok(());
    }

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "ALTER TABLE {schema}.idempotency_keys \
         ADD COLUMN IF NOT EXISTS client_id TEXT NOT NULL DEFAULT ''"
    )))
    .execute(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "ALTER TABLE {schema}.idempotency_keys DROP CONSTRAINT IF EXISTS idempotency_keys_pkey"
    )))
    .execute(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "ALTER TABLE {schema}.idempotency_keys \
         ADD PRIMARY KEY (command_type_name, client_id, idempotency_key)"
    )))
    .execute(&mut *tx)
    .await?;

    tx.commit().await?;
    Ok(())
}

/// `cross_context_route_cursors` - one row per registered
/// `CrossContextRoute`, in its own `Source`'s bounded-context schema
/// (the same "cursor lives with whoever's reading" register `ReadCursor`
/// already establishes, just for an internal reader rather than an
/// external `EventReadToken` holder). `last_dispatched_sequence` uses
/// the same `-1` "nothing yet" sentinel `sequence`/`caught_up_to`
/// already use throughout this codebase, rather than a nullable column.
/// `ensure_idempotency_keys_table`'s own doc comment's "no general
/// per-bounded-context schema migration mechanism" applies identically
/// here - `CREATE TABLE IF NOT EXISTS`, patched into every bounded
/// context on every `build()`, is the whole migration story.
///
/// `retry_attempt_count`/`retry_first_failed_at`/`retry_next_attempt_at`
/// (issue #21) - the durable backoff state one route's own
/// blocked head-of-line occurrence carries between ticks, applying
/// `skilj_retry::RetryPolicy` to what used to be an unbounded, un-
/// throttled "retry every single tick forever" - see
/// `catch_up_cross_context_route`'s own doc comment for the full
/// mechanism. A single row's worth of state suffices (rather than, say,
/// a row per failing occurrence): only the cursor's own next occurrence
/// can ever be the one currently failing, since the cursor never
/// advances past it - the same invariant that already lets
/// `last_dispatched_sequence` be a single column rather than a set. An
/// already-provisioned bounded context gets these columns patched in
/// separately by `ensure_cross_context_route_retry_columns` (this
/// `CREATE TABLE IF NOT EXISTS` is a no-op against an existing table, so
/// it can't add columns to one - see that function's own doc comment).
#[tracing::instrument(skip_all)]
pub async fn ensure_cross_context_route_cursors_table<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE IF NOT EXISTS {schema}.cross_context_route_cursors (
            route_name TEXT PRIMARY KEY,
            last_dispatched_sequence BIGINT NOT NULL DEFAULT -1,
            updated_at TIMESTAMPTZ NOT NULL,
            retry_attempt_count INT NOT NULL DEFAULT 0,
            retry_first_failed_at TIMESTAMPTZ,
            retry_next_attempt_at TIMESTAMPTZ
        )"
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// Patches an already-provisioned bounded context's
/// `cross_context_route_cursors` (a real table since the cross-context
/// router itself shipped) onto the retry-columns shape a brand-new one
/// gets directly from `ensure_cross_context_route_cursors_table` above.
/// `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`, the same idempotent-patch
/// idiom `ensure_projection_state_owner_columns`/`ensure_event_scoping_columns`
/// already use - simpler than that pair's own PK-migration sibling
/// (`migrate_idempotency_keys_client_id_scoping`) needs, since none of
/// these three columns join a primary key. Called unconditionally on
/// every `build()`, alongside `ensure_cross_context_route_cursors_table`
/// itself - a no-op once a bounded context already has them, migrated or
/// fresh.
pub async fn ensure_cross_context_route_retry_columns(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "cross_context_route_cursors",
        &["retry_attempt_count"],
        format!(
            "ALTER TABLE {schema}.cross_context_route_cursors \
         ADD COLUMN IF NOT EXISTS retry_attempt_count INT NOT NULL DEFAULT 0"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "cross_context_route_cursors",
        &["retry_first_failed_at"],
        format!(
            "ALTER TABLE {schema}.cross_context_route_cursors \
         ADD COLUMN IF NOT EXISTS retry_first_failed_at TIMESTAMPTZ"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "cross_context_route_cursors",
        &["retry_next_attempt_at"],
        format!(
            "ALTER TABLE {schema}.cross_context_route_cursors \
         ADD COLUMN IF NOT EXISTS retry_next_attempt_at TIMESTAMPTZ"
        ),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// issue #20 - the durable cursor table `catch_up_schedule_deadline`/
/// `catch_up_cancel_deadline` share, one row per registered
/// `ScheduleDeadline::NAME`/`CancelDeadline::NAME` (a schedule and its own
/// cancel counterpart advance independently, even though they're paired -
/// see `plugin::CancelDeadline::Deadline`'s own doc comment). Deliberately
/// its own table rather than piggybacked on `cross_context_route_cursors`
/// above - a genuinely different reactor family, even though the cursor
/// shape (`{owner} -> last_dispatched_sequence`) is identical. Same
/// `impl PgExecutor`/`CREATE TABLE IF NOT EXISTS` treatment as every
/// sibling `ensure_*_table` function here - see
/// `ensure_idempotency_keys_table`'s own doc comment for the full
/// "brand-new bounded context vs. patching an already-provisioned one"
/// story.
pub async fn ensure_deadline_cursors_table<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE IF NOT EXISTS {schema}.deadline_cursors (
            cursor_owner TEXT PRIMARY KEY,
            last_dispatched_sequence BIGINT NOT NULL DEFAULT -1,
            updated_at TIMESTAMPTZ NOT NULL
        )"
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// issue #25's investigation (docs/architecture.md §50/§51) -
/// one row per `(projection_name, partition_index)` a partitioned async
/// `Projection` (`Projection::PARTITION_COUNT > 1`) has ever had a
/// `catch_up_partitioned_projection` tick seed or advance. `caught_up_to`
/// here is this one partition's own position, distinct from
/// `projections.caught_up_to` - the latter stays the single external
/// source of truth (`Projection.caughtUpTo` over GraphQL,
/// `wait_until_caught_up`), rolled up as the `MIN(caught_up_to)` across
/// a projection's own partition rows every tick. `DEFAULT -1` matches
/// `projection_state.as_of_sequence`'s own "nothing folded yet"
/// convention. Same `impl PgExecutor`/`CREATE TABLE IF NOT EXISTS`
/// treatment as every sibling `ensure_*_table` function here - see
/// `ensure_idempotency_keys_table`'s own doc comment for the full
/// "brand-new bounded context vs. patching an already-provisioned one"
/// story.
pub async fn ensure_projection_partition_progress_table<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE IF NOT EXISTS {schema}.projection_partition_progress (
            projection_name TEXT NOT NULL REFERENCES {schema}.projections (name),
            partition_index INT NOT NULL,
            caught_up_to BIGINT NOT NULL DEFAULT -1,
            updated_at TIMESTAMPTZ NOT NULL,
            PRIMARY KEY (projection_name, partition_index)
        )"
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// `Snapshot`'s own twin of `ensure_projection_partition_progress_table`
/// just above - one row per `(snapshot_name, partition_index)` a
/// partitioned `Snapshot` (`Snapshot::PARTITION_COUNT > 1`) has ever had
/// a `catch_up_partitioned_snapshot` tick seed or advance
/// (docs/architecture.md §52). `caught_up_to` is this one partition's
/// own position, distinct from `snapshot_progress.caught_up_to` - the
/// latter stays the single external rollup (`MIN(caught_up_to)` across
/// a snapshot's own partition rows every tick), the identical relation
/// `projections.caught_up_to`/`projection_partition_progress` already
/// has. `DEFAULT -1` matches `snapshots.as_of_sequence`'s own "nothing
/// folded yet" convention. No `REFERENCES` clause, unlike the
/// `Projection` twin - `snapshots` has no backing registration table to
/// reference, so there's nothing to foreign-key against and no
/// table-creation-ordering constraint here.
pub async fn ensure_snapshot_partition_progress_table<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE IF NOT EXISTS {schema}.snapshot_partition_progress (
            snapshot_name TEXT NOT NULL,
            partition_index INT NOT NULL,
            caught_up_to BIGINT NOT NULL DEFAULT -1,
            updated_at TIMESTAMPTZ NOT NULL,
            PRIMARY KEY (snapshot_name, partition_index)
        )"
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// issue #20's own row store - one row per deadline a
/// `ScheduleDeadline` has ever scheduled, living in
/// `ScheduleDeadline::Source::BOUNDED_CONTEXT`'s own schema (mirroring
/// `cross_context_route_cursors`' placement choice: the reactor's own
/// *source* side owns the durable state, regardless of where its
/// *target* eventually lands). `id` is deterministic
/// (`"{schedule_name}:{source_event_sequence}"`, see `ScheduleDeadline::NAME`'s
/// own doc comment) so a redelivered catch-up tick's `INSERT ... ON
/// CONFLICT (id) DO NOTHING` is always a safe no-op, never a duplicate
/// row. `tags` backs `catch_up_cancel_deadline`'s own tag-containment
/// lookup, indexed the same GIN way `docs/architecture.md §19 Problem 1`
/// already indexes the `events` table's own `tags` column. `status`
/// starts `'pending'`, and moves to `'cancelled'` (`catch_up_cancel_deadline`,
/// terminal) or `'firing'` then `'fired'` (`db::fire_due_deadlines`'s own
/// atomic claim-then-resolve, closing the fire-vs-cancel race - see
/// [docs/architecture.md §55](../../../docs/architecture.md#55-closing-the-canceldeadline-fire-vs-cancel-race)).
/// `firing_at` records when a row was claimed, purely so a crashed
/// instance's claim can be reclaimed after it goes stale - see
/// `fire_due_deadlines`'s own doc comment for the reclaim window.
///
/// issue #95 - the recurrence columns make one pending row the
/// current head of a chain: `recurrence_schedule` (the 7-field
/// Quartz-dialect cron expression) with `recurrence_policy`
/// (`'skip'`/`'fire_once'`/`'fire_all'`), and the validity window
/// (`recurrence_start_at`/`recurrence_end_at`/`recurrence_valid_until`,
/// all nullable). `recurrence_parent_id` names the chain's first row and
/// `recurrence_sequence` the row's position in it (0 for the first,
/// `NULL` for a one-shot that never recurs), so the next row's
/// deterministic id (`"{parent_id}#r{sequence}"`) is a safe
/// `ON CONFLICT (id) DO NOTHING` no-op on redelivery, the identical
/// property the first row's own `"{schedule_name}:{source_event_sequence}"`
/// id already has. Every column is nullable - a row scheduled before this
/// feature reads as the one-shot it is.
///
/// The DDL itself is shared between `provision_bounded_context_schema`
/// (a brand-new context, run against its own open transaction) and
/// `ensure_deadlines_table` below (an existing one, run against `&Pool`) -
/// one DDL string, not two copies to keep in sync, the identical split
/// `private_field_grants_table_ddl` already uses for the same reason.
fn deadlines_table_ddl(schema: &str) -> String {
    format!(
        "CREATE TABLE IF NOT EXISTS {schema}.deadlines (
            id TEXT PRIMARY KEY,
            schedule_name TEXT NOT NULL,
            fire_at TIMESTAMPTZ NOT NULL,
            expires_at TIMESTAMPTZ,
            tags JSONB NOT NULL,
            correlation_id TEXT,
            target_bounded_context TEXT NOT NULL,
            target_command_type TEXT NOT NULL,
            payload TEXT NOT NULL,
            status TEXT NOT NULL,
            created_at TIMESTAMPTZ NOT NULL,
            resolved_at TIMESTAMPTZ,
            firing_at TIMESTAMPTZ,
            attempt_count INT NOT NULL DEFAULT 0,
            first_failed_at TIMESTAMPTZ,
            next_attempt_at TIMESTAMPTZ,
            last_error TEXT,
            recurrence_schedule TEXT,
            recurrence_policy TEXT CHECK (recurrence_policy IN ('skip', 'fire_once', 'fire_all')),
            recurrence_start_at TIMESTAMPTZ,
            recurrence_end_at TIMESTAMPTZ,
            recurrence_valid_until TIMESTAMPTZ,
            recurrence_parent_id TEXT,
            recurrence_sequence BIGINT
        )"
    )
}

/// `pool: &Pool`, not a generic `impl PgExecutor` - this needs three
/// statements (the table plus two indexes), and unlike every
/// single-statement sibling `ensure_*_table` function here, a generic
/// executor can't be reused across more than one `.execute()` call
/// without already being `Copy` the way `&Pool` is. Same split
/// `ensure_private_field_grants_table` already uses for the identical
/// reason: `provision_bounded_context_schema` below runs the equivalent
/// statements directly against its own `&mut **tx` instead of calling
/// this.
pub async fn ensure_deadlines_table(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(deadlines_table_ddl(&schema)))
        .execute(pool)
        .await?;
    // A bounded context provisioned before the fire-vs-cancel race fix
    // (docs/architecture.md §55) gets `firing_at` patched in here -
    // nullable, no `DEFAULT`, same treatment `ensure_read_cursors_checkout_column`
    // already gives `checked_out_at` for the identical reason: `NULL`
    // already means exactly "not currently claimed."
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "deadlines",
        &["firing_at"],
        format!("ALTER TABLE {schema}.deadlines ADD COLUMN IF NOT EXISTS firing_at TIMESTAMPTZ"),
    )))
    .execute(pool)
    .await?;
    // issue #97 - a deadline's optional expiry, carried to the
    // fired command's `decide_with`. Nullable, no `DEFAULT`, so every row
    // scheduled before this feature reads as "no expiry".
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "deadlines",
        &["expires_at"],
        format!("ALTER TABLE {schema}.deadlines ADD COLUMN IF NOT EXISTS expires_at TIMESTAMPTZ"),
    )))
    .execute(pool)
    .await?;
    // A failed fire's retry state (docs/architecture.md §115). The
    // defaults mean "never failed", which every existing row is.
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "deadlines",
        &[
            "attempt_count",
            "first_failed_at",
            "next_attempt_at",
            "last_error",
        ],
        format!(
            "ALTER TABLE {schema}.deadlines \
            ADD COLUMN IF NOT EXISTS attempt_count INT NOT NULL DEFAULT 0, \
            ADD COLUMN IF NOT EXISTS first_failed_at TIMESTAMPTZ, \
            ADD COLUMN IF NOT EXISTS next_attempt_at TIMESTAMPTZ, \
            ADD COLUMN IF NOT EXISTS last_error TEXT"
        ),
    )))
    .execute(pool)
    .await?;
    // issue #95 - a recurring chain's own state, one pending row
    // the head. Nullable throughout, so every row scheduled before this
    // feature reads as the one-shot it is.
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "deadlines",
        &[
            "recurrence_schedule",
            "recurrence_policy",
            "recurrence_start_at",
            "recurrence_end_at",
            "recurrence_valid_until",
            "recurrence_parent_id",
            "recurrence_sequence",
        ],
        format!(
            "ALTER TABLE {schema}.deadlines \
            ADD COLUMN IF NOT EXISTS recurrence_schedule TEXT, \
            ADD COLUMN IF NOT EXISTS recurrence_policy TEXT \
                CHECK (recurrence_policy IN ('skip', 'fire_once', 'fire_all')), \
            ADD COLUMN IF NOT EXISTS recurrence_start_at TIMESTAMPTZ, \
            ADD COLUMN IF NOT EXISTS recurrence_end_at TIMESTAMPTZ, \
            ADD COLUMN IF NOT EXISTS recurrence_valid_until TIMESTAMPTZ, \
            ADD COLUMN IF NOT EXISTS recurrence_parent_id TEXT, \
            ADD COLUMN IF NOT EXISTS recurrence_sequence BIGINT"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(
        &schema,
        "deadlines_due",
        format!(
            "CREATE INDEX IF NOT EXISTS deadlines_due ON {schema}.deadlines (fire_at) \
         WHERE status = 'pending'"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(
        &schema,
        "deadlines_tags_gin",
        format!(
            "CREATE INDEX IF NOT EXISTS deadlines_tags_gin ON {schema}.deadlines USING GIN (tags)"
        ),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// `external_message_cursors` - the durable state behind
/// `highest_dedupe_sequence(adapter, dedupe_partition_key)` in
/// specs/skilj.allium's own `rule CreateExternalEvent`
/// ([docs/architecture.md §39](../../../docs/architecture.md#external-message-dedup-create-external-event)). One row per `(adapter_id, partition_key)`
/// pair that has ever had an event written under it, storing only the
/// highest `dedupe_sequence` seen so far - a compact watermark, not a row
/// per message the way `idempotency_keys` is: sound only because the
/// caller's own external source (Kafka, Kinesis, Pulsar and their kin)
/// already guarantees strictly increasing delivery order within one
/// partition, which is exactly the property that makes remembering
/// anything below the highest seen unnecessary. See
/// `db::create_and_insert_external_event`'s own doc comment for the full
/// mechanism this table backs.
///
/// `impl PgExecutor`, the same "works on `&Pool` autocommit or inside a
/// caller's own open `Transaction`" treatment `ensure_idempotency_keys_table`
/// already gets, for the identical reason: `provision_bounded_context_schema`
/// above needs the latter (a brand-new bounded context), the
/// per-bounded-context startup loop in `skilj/src/lib.rs` needs the
/// former (patching a bounded context provisioned before this feature
/// existed). `CREATE TABLE IF NOT EXISTS`, called unconditionally on
/// every `build()`, is the whole migration story - a fresh table with no
/// existing rows needs no `ALTER TABLE` dance the way `idempotency_keys`'
/// own `client_id` retrofit did ([docs/architecture.md §37](../../../docs/architecture.md#idempotency-keys-client-id-scoping)).
#[tracing::instrument(skip_all)]
pub async fn ensure_external_message_cursors_table<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE IF NOT EXISTS {schema}.external_message_cursors (
            adapter_id TEXT NOT NULL,
            partition_key TEXT NOT NULL,
            last_sequence BIGINT NOT NULL,
            updated_at TIMESTAMPTZ NOT NULL,
            PRIMARY KEY (adapter_id, partition_key)
        )"
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// `external_message_keys` - the durable state behind
/// `recorded_external_event(adapter, idempotency_key)` in specs/skilj.allium's
/// own `rule CreateExternalEvent` (docs/architecture.md §175): one row per
/// `(adapter_id, message_key)` that created an event, naming that event.
/// The per-message counterpart of `external_message_cursors`, for sources
/// that redeliver out of order. Expires with `idempotency_keys`
/// (`delete_expired_external_message_keys`), hence the `created_at`
/// index. Created on every `build()` and at provisioning, like
/// `ensure_external_message_cursors_table`.
#[tracing::instrument(skip_all)]
pub async fn ensure_external_message_keys_table<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    let index = create_index_patch(
        &schema,
        "external_message_keys_created_at",
        format!(
            "CREATE INDEX IF NOT EXISTS external_message_keys_created_at \
             ON {schema}.external_message_keys (created_at)"
        ),
    );
    sqlx::raw_sql(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE IF NOT EXISTS {schema}.external_message_keys (
            adapter_id TEXT NOT NULL,
            message_key TEXT NOT NULL,
            event_sequence BIGINT NOT NULL,
            created_at TIMESTAMPTZ NOT NULL,
            PRIMARY KEY (adapter_id, message_key)
        );
        {index}"
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// `registrations_generation`: one counter row per bounded context,
/// incremented by triggers whenever an `event_types`/`command_types` row
/// is inserted, deleted or changed. It's what [`events_table_identity`]
/// reads as the [`RegistrationsStamp`], instead of hashing every
/// registration on every cache read (docs/architecture.md §189). An
/// update that only moves `schedule_position`/`last_fired_at` - a
/// scheduled fire - doesn't count, and neither does a re-registration
/// that writes the row back unchanged, as every instance's startup does.
///
/// Created at provisioning and on every `build()`; each step is skipped
/// when already there, since `CREATE TRIGGER` takes a lock that blocks
/// writes to the table (§158), and replacing the function on every start
/// fails when two instances start at once. One multi-statement query, so one
/// transaction: no reader sees the counter before its triggers exist.
///
/// The existence checks and the creates aren't atomic on their own: two
/// instances starting together against a bounded context from before the
/// counter both saw the function missing, and the second `CREATE` failed
/// its `build()` (docs/architecture.md §195). So the query first takes a
/// transaction-scoped advisory lock keyed by the schema; a second instance
/// waits for the first to commit and then finds everything there.
#[tracing::instrument(skip_all)]
pub async fn ensure_registrations_generation<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    let triggers = [
        (
            "event_types",
            "event_types_bump_registrations_generation",
            "AFTER INSERT OR DELETE",
            "",
        ),
        (
            "event_types",
            "event_types_change_bumps_registrations_generation",
            "AFTER UPDATE",
            " WHEN ((to_jsonb(OLD) - 'schedule_position' - 'last_fired_at') \
             IS DISTINCT FROM (to_jsonb(NEW) - 'schedule_position' - 'last_fired_at'))",
        ),
        (
            "command_types",
            "command_types_bump_registrations_generation",
            "AFTER INSERT OR DELETE",
            "",
        ),
        (
            "command_types",
            "command_types_change_bumps_registrations_generation",
            "AFTER UPDATE",
            " WHEN (OLD.* IS DISTINCT FROM NEW.*)",
        ),
    ]
    .map(|(table, name, events, when)| {
        format!(
            "DO $patch$ BEGIN IF NOT EXISTS (SELECT 1 FROM pg_trigger \
             WHERE tgrelid = to_regclass({}) AND tgname = {}) THEN \
             CREATE TRIGGER {name} {events} ON {schema}.{table} FOR EACH ROW{when} \
             EXECUTE FUNCTION {schema}.bump_registrations_generation(); END IF; END $patch$",
            sql_literal(&format!("{schema}.{table}")),
            sql_literal(name)
        )
    })
    .join(";\n");
    sqlx::raw_sql(sqlx::AssertSqlSafe(format!(
        "SELECT pg_advisory_xact_lock(hashtext({lock_key})::bigint);
        CREATE TABLE IF NOT EXISTS {schema}.registrations_generation (
            id BOOLEAN PRIMARY KEY DEFAULT TRUE CHECK (id),
            generation BIGINT NOT NULL
        );
        INSERT INTO {schema}.registrations_generation (generation) VALUES (0)
            ON CONFLICT (id) DO NOTHING;
        DO $patch$ BEGIN IF to_regprocedure({function}) IS NULL THEN
            CREATE FUNCTION {schema}.bump_registrations_generation() RETURNS trigger
                LANGUAGE plpgsql AS $bump$ BEGIN
                    UPDATE {schema}.registrations_generation SET generation = generation + 1;
                    RETURN NULL;
                END $bump$;
        END IF; END $patch$;
        {triggers}",
        function = sql_literal(&format!("{schema}.bump_registrations_generation()")),
        lock_key = sql_literal(&format!("skilj_registrations_generation:{schema}"))
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// `event_tags`: one row per tag of every event, `(tag_key, tag_value,
/// event_type_name, sequence)`, indexed in that order - what a consistency
/// tag read goes through (docs/architecture.md §198, §210). A GIN index on
/// `events.tags` answered "which events carry this tag", but a query for
/// the latest event of a few types carrying a company's tag still walked
/// every event with that tag; through this index it is a probe per type,
/// however many other events the tag has.
///
/// Filled by a statement-level trigger on `events`, not by skilj's insert
/// paths, so no writer can leave it incomplete - including an instance of
/// an older version during a rolling deploy, which knows nothing about it.
///
/// Created at provisioning, and for a bounded context from before it by
/// [`ensure_bounded_context_current`], under the same kind of advisory
/// lock as [`ensure_registrations_generation`]. The first time, it creates
/// the table, fills it from the existing events and creates the trigger in
/// one transaction, holding a `SHARE ROW EXCLUSIVE` lock on `events`
/// throughout: reads go on, but no event commits between the backfill and
/// the trigger, where it would be indexed by neither. Every later call
/// finds it there and locks nothing (docs/architecture.md §158).
#[tracing::instrument(skip_all)]
pub async fn ensure_event_tags_index<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::raw_sql(sqlx::AssertSqlSafe(format!(
        "SELECT pg_advisory_xact_lock(hashtext({lock_key})::bigint);
        DO $patch$ BEGIN IF to_regclass({table}) IS NULL THEN
            LOCK TABLE {schema}.events IN SHARE ROW EXCLUSIVE MODE;
            CREATE TABLE {schema}.event_tags (
                tag_key TEXT NOT NULL,
                tag_value TEXT,
                event_type_name TEXT NOT NULL,
                sequence BIGINT NOT NULL
            );
            INSERT INTO {schema}.event_tags (tag_key, tag_value, event_type_name, sequence)
                SELECT t->>'key', t->>'value', e.event_type_name, e.sequence
                FROM {schema}.events e, jsonb_array_elements(e.tags) t;
            CREATE INDEX event_tags_lookup ON {schema}.event_tags
                (tag_key, tag_value, event_type_name, sequence);
            CREATE FUNCTION {schema}.index_event_tags() RETURNS trigger
                LANGUAGE plpgsql AS $index$ BEGIN
                    INSERT INTO {schema}.event_tags (tag_key, tag_value, event_type_name, sequence)
                        SELECT t->>'key', t->>'value', n.event_type_name, n.sequence
                        FROM new_events n, jsonb_array_elements(n.tags) t;
                    RETURN NULL;
                END $index$;
            CREATE TRIGGER events_index_tags AFTER INSERT ON {schema}.events
                REFERENCING NEW TABLE AS new_events
                FOR EACH STATEMENT EXECUTE FUNCTION {schema}.index_event_tags();
        END IF; END $patch$",
        table = sql_literal(&format!("{schema}.event_tags")),
        lock_key = sql_literal(&format!("skilj_event_tags:{schema}"))
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// Drops `events_by_tags`, the GIN index on `events.tags` (docs/architecture.md
/// §19), from a bounded context provisioned before tag reads moved to
/// `event_tags` (§210): nothing reads through it, and every event paid for
/// it on insert. Checked in the catalog first, so a startup that finds it
/// gone takes no lock (§158); dropped `CONCURRENTLY`, so writes to the
/// events table go on meanwhile - which can't run in a transaction, hence
/// a statement of its own on the pool.
pub async fn drop_events_by_tags_index(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    let index = format!("{schema}.events_by_tags");
    let (present,): (bool,) = sqlx::query_as("SELECT to_regclass($1) IS NOT NULL")
        .bind(&index)
        .fetch_one(pool)
        .await?;
    if present {
        sqlx::raw_sql(sqlx::AssertSqlSafe(format!(
            "DROP INDEX CONCURRENTLY IF EXISTS {index}"
        )))
        .execute(pool)
        .await?;
    }
    Ok(())
}

/// `blind_tags`: the bounded context's blind-index constraints, one row per
/// tag key (docs/architecture.md §205) - what every instance agrees on
/// about each: its normalizer version, its key fingerprint (§208) and what
/// `forgetSubject` does with it. Created at provisioning, and for a bounded context from before it
/// by [`ensure_bounded_context_current`]; a call that finds it there
/// creates and locks nothing (docs/architecture.md §158).
pub async fn ensure_blind_tags_table<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::raw_sql(sqlx::AssertSqlSafe(format!(
        "DO $patch$ BEGIN IF to_regclass({table}) IS NULL THEN
            CREATE TABLE IF NOT EXISTS {schema}.blind_tags (
                tag_key TEXT PRIMARY KEY,
                normalizer_version BIGINT NOT NULL,
                key_fingerprint TEXT,
                key_generation BIGINT NOT NULL DEFAULT 0,
                erasure JSONB NOT NULL,
                registered_at TIMESTAMPTZ NOT NULL
            );
        END IF; END $patch$",
        table = sql_literal(&format!("{schema}.blind_tags")),
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// The index startup's checks, the rewrap and the retirement check read
/// `encryption_keys` through (docs/architecture.md §230): the active rows
/// by provider and master key version, so "is anything still wrapped by
/// another provider, or below this version" is a few index probes.
fn encryption_keys_master_key_index_ddl(schema: &str) -> String {
    format!(
        "CREATE INDEX encryption_keys_master_key ON {schema}.encryption_keys \
         (key_provider, master_key_version, id) WHERE status = 'active'"
    )
}

/// `encryption_keys.key_provider`/`master_key_version`/`unreadable_since`
/// and their index
/// (docs/architecture.md §230), for a bounded context provisioned before
/// them. Rows already there keep `NULL`: wrapped by the legacy raw master
/// key. A call that finds them there takes no table lock (§158).
pub async fn ensure_encryption_key_provider_columns(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "encryption_keys",
        &["key_provider", "master_key_version", "unreadable_since"],
        format!(
            "ALTER TABLE {schema}.encryption_keys \
             ADD COLUMN IF NOT EXISTS key_provider TEXT, \
             ADD COLUMN IF NOT EXISTS master_key_version INTEGER, \
             ADD COLUMN IF NOT EXISTS unreadable_since TIMESTAMPTZ"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(
        &schema,
        "encryption_keys_master_key",
        encryption_keys_master_key_index_ddl(&schema),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// Records `declaration` as one of `bounded_context`'s blind tags
/// (docs/architecture.md §205), or checks it against the stored one: the
/// normalizer version must match, and the key fingerprint too when both
/// sides have one (§208; a missing stored one is recorded); the erasure
/// policy is updated, since it only decides what a later `forgetSubject`
/// does. A new key is refused
/// when a registered type already maps it in the clear. Under an advisory
/// lock, so two instances starting together agree.
pub async fn register_blind_tag(
    pool: &Pool,
    bounded_context: &str,
    declaration: &crate::blind::BlindTagDeclaration,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    let mut tx = pool.begin().await?;
    sqlx::query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)")
        .bind(format!("skilj_blind_tags:{schema}"))
        .execute(&mut *tx)
        .await?;
    let stored: Option<(i64, Option<String>, i64)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT normalizer_version, key_fingerprint, key_generation FROM {schema}.blind_tags \
         WHERE tag_key = $1"
    )))
    .bind(&declaration.tag_key)
    .fetch_optional(&mut *tx)
    .await?;
    // A fingerprint compares only at the generation it was taken at
    // (docs/architecture.md §209); startup checks the stored one.
    let stored = stored.map(|(version, fingerprint, generation)| {
        let comparable = generation == i64::from(declaration.key_generation);
        (version, fingerprint.filter(|_| comparable))
    });
    match stored {
        Some((version, _)) if version != i64::from(declaration.normalizer_version) => {
            return Err(crate::event_store::Error::BlindNormalizerChanged {
                tag_key: declaration.tag_key.clone(),
                stored: version,
                declared: declaration.normalizer_version,
            }
            .into());
        }
        Some((_, Some(stored)))
            if declaration
                .key_fingerprint
                .as_ref()
                .is_some_and(|declared| *declared != stored) =>
        {
            return Err(crate::event_store::Error::BlindIndexKeyChanged {
                bounded_context: bounded_context.to_string(),
                tag_key: declaration.tag_key.clone(),
            }
            .into());
        }
        Some(_) => {
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "UPDATE {schema}.blind_tags SET erasure = $2, \
                 key_fingerprint = coalesce(key_fingerprint, $3) \
                 WHERE tag_key = $1 AND (key_fingerprint IS NOT NULL OR key_generation = $4)"
            )))
            .bind(&declaration.tag_key)
            .bind(Json(&declaration.erasure))
            .bind(&declaration.key_fingerprint)
            .bind(i64::from(declaration.key_generation))
            .execute(&mut *tx)
            .await?;
        }
        None => {
            let (in_use,): (bool,) = sqlx::query_as(sqlx::AssertSqlSafe(format!(
                "SELECT EXISTS (SELECT 1 FROM {schema}.event_types t, \
                    jsonb_array_elements(t.tag_mappings) m \
                    WHERE m->>'key' = $1 AND NOT coalesce((m->>'blind')::boolean, false)) \
                 OR EXISTS (SELECT 1 FROM {schema}.command_types t, \
                    jsonb_array_elements(t.tag_mappings) m \
                    WHERE m->>'key' = $1 AND NOT coalesce((m->>'blind')::boolean, false))"
            )))
            .bind(&declaration.tag_key)
            .fetch_one(&mut *tx)
            .await?;
            if in_use {
                return Err(crate::event_store::Error::BlindTagKeyInUse(
                    declaration.tag_key.clone(),
                )
                .into());
            }
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "INSERT INTO {schema}.blind_tags \
                 (tag_key, normalizer_version, key_fingerprint, key_generation, erasure, \
                  registered_at) VALUES ($1, $2, $3, $4, $5, $6)"
            )))
            .bind(&declaration.tag_key)
            .bind(i64::from(declaration.normalizer_version))
            .bind(&declaration.key_fingerprint)
            .bind(i64::from(declaration.key_generation))
            .bind(Json(&declaration.erasure))
            .bind(now)
            .execute(&mut *tx)
            .await?;
        }
    }
    tx.commit().await?;
    Ok(())
}

/// `blind_tags`' columns, as `list_blind_tags` reads them.
type BlindTagRow = (
    String,
    i64,
    Option<String>,
    i64,
    Json<crate::blind::Erasure>,
);

/// Every blind tag stored for `bounded_context`.
pub async fn list_blind_tags(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<Vec<crate::blind::BlindTagDeclaration>> {
    let schema = schema_ident(bounded_context);
    let rows: Vec<BlindTagRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT tag_key, normalizer_version, key_fingerprint, key_generation, erasure \
             FROM {schema}.blind_tags ORDER BY tag_key"
    )))
    .fetch_all(pool)
    .await?;
    Ok(rows
        .into_iter()
        .map(|(tag_key, version, key_fingerprint, generation, erasure)| {
            crate::blind::BlindTagDeclaration {
                tag_key,
                normalizer_version: u32::try_from(version).unwrap_or(u32::MAX),
                erasure: erasure.0,
                key_fingerprint,
                key_generation: u32::try_from(generation).unwrap_or(u32::MAX),
            }
        })
        .collect())
}

/// Brings this process's view of `bounded_context`'s blind-tag
/// generations up to date, under the bounded context's sequence lock
/// (docs/architecture.md §209) - which a rotation holds while it
/// rewrites, so what's read here can't change until the caller commits.
/// Whether any differed from what this process hashed with: a command
/// whose tags were derived before the lock then has to be derived again.
/// No query at all for a bounded context this process declares no blind
/// tag for.
pub(crate) async fn refresh_blind_generations(
    conn: &mut sqlx::PgConnection,
    bounded_context: &str,
    blind: &crate::blind::BlindIndex,
) -> crate::error::Result<bool> {
    if !blind.declares_any(bounded_context) {
        return Ok(false);
    }
    let schema = schema_ident(bounded_context);
    let rows: Vec<(String, i64)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT tag_key, key_generation FROM {schema}.blind_tags"
    )))
    .fetch_all(&mut *conn)
    .await?;
    let mut changed = false;
    for (tag_key, generation) in rows {
        let generation = u32::try_from(generation).unwrap_or(u32::MAX);
        changed |= blind.observe_generation(bounded_context, &tag_key, generation);
    }
    Ok(changed)
}

/// Rewraps every stored tag of `bounded_context`'s blind tag `tag_key`
/// from generation `from` to `from + 1` (docs/architecture.md §209): in
/// `events.tags`, `event_tags`, the commands' `consistency_tags` and query
/// items, and snapshot rows keyed by it - each value through `wrap`, which
/// needs only the stored tag - and stores the new generation with
/// `fingerprint`, the key chain's up to it. One transaction under the
/// bounded context's sequence lock, so no write lands half-way and a
/// crash leaves the old generation whole; every write to the bounded
/// context waits meanwhile. `false`, changing nothing, when the stored
/// generation isn't `from` - another instance rotated it.
pub async fn rotate_blind_tag(
    pool: &Pool,
    bounded_context: &str,
    tag_key: &str,
    from: u32,
    wrap: &(dyn Fn(&str) -> crate::error::Result<String> + Sync),
    fingerprint: &str,
) -> crate::error::Result<bool> {
    ensure_registrations_generation(pool, bounded_context).await?;
    let schema = schema_ident(bounded_context);
    let mut tx = pool.begin().await?;
    lock_bounded_context_sequence(&mut tx, bounded_context).await?;
    let stored: Option<(i64,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT key_generation FROM {schema}.blind_tags WHERE tag_key = $1 FOR UPDATE"
    )))
    .bind(tag_key)
    .fetch_optional(&mut *tx)
    .await?;
    if stored != Some((i64::from(from),)) {
        return Ok(false);
    }

    let keyed = serde_json::json!([{ "key": tag_key }]);
    let in_query = serde_json::json!([{ "tags": [{ "key": tag_key }] }]);
    let old: Vec<(String,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT tag_value FROM {schema}.event_tags \
            WHERE tag_key = $1 AND tag_value IS NOT NULL \
         UNION SELECT t->>'value' FROM {schema}.commands c, \
            jsonb_array_elements(c.consistency_tags) t \
            WHERE c.consistency_tags @> $2 AND t->>'key' = $1 AND t->>'value' IS NOT NULL \
         UNION SELECT t->>'value' FROM {schema}.commands c, \
            jsonb_array_elements(c.consistency_query) item, \
            jsonb_array_elements(coalesce(item->'tags', '[]'::jsonb)) t \
            WHERE c.consistency_query @> $3 AND t->>'key' = $1 AND t->>'value' IS NOT NULL \
         UNION SELECT tag_value FROM {schema}.snapshots WHERE tag_key = $1"
    )))
    .bind(tag_key)
    .bind(Json(&keyed))
    .bind(Json(&in_query))
    .fetch_all(&mut *tx)
    .await?;
    let old: Vec<String> = old.into_iter().map(|(v,)| v).collect();
    let new = old
        .iter()
        .map(|v| wrap(v))
        .collect::<crate::error::Result<Vec<String>>>()?;

    sqlx::query(
        "CREATE TEMP TABLE skilj_blind_rotation (old TEXT PRIMARY KEY, new TEXT NOT NULL) \
         ON COMMIT DROP",
    )
    .execute(&mut *tx)
    .await?;
    sqlx::query(
        "INSERT INTO skilj_blind_rotation (old, new) SELECT * FROM unnest($1::text[], $2::text[])",
    )
    .bind(&old)
    .bind(&new)
    .execute(&mut *tx)
    .await?;
    // A tag array with each of the key's values replaced, in order.
    let rewrap = |column: &str| {
        format!(
            "(SELECT coalesce(jsonb_agg(CASE WHEN t->>'key' = $1 AND t->>'value' IS NOT NULL \
                THEN jsonb_set(t, '{{value}}', to_jsonb((\
                    SELECT r.new FROM skilj_blind_rotation r WHERE r.old = t->>'value'))) \
                ELSE t END ORDER BY x.ord), '[]'::jsonb) \
              FROM jsonb_array_elements({column}) WITH ORDINALITY AS x(t, ord))"
        )
    };
    sqlx::query(sqlx::AssertSqlSafe(format!(
        // A filter, not an index probe: a rotation rewrites every event the
        // key is on, so reading the table through is what it costs anyway
        // (docs/architecture.md §210).
        "UPDATE {schema}.events e SET tags = {} WHERE e.tags @> $2",
        rewrap("e.tags")
    )))
    .bind(tag_key)
    .bind(Json(&keyed))
    .execute(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.event_tags et SET tag_value = r.new FROM skilj_blind_rotation r \
         WHERE et.tag_key = $1 AND et.tag_value = r.old"
    )))
    .bind(tag_key)
    .execute(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.commands c SET \
            consistency_tags = {}, \
            consistency_query = (SELECT coalesce(jsonb_agg(CASE WHEN q.item ? 'tags' \
                THEN jsonb_set(q.item, '{{tags}}', {}) ELSE q.item END ORDER BY q.ord), \
                '[]'::jsonb) \
              FROM jsonb_array_elements(c.consistency_query) WITH ORDINALITY AS q(item, ord)) \
         WHERE c.consistency_tags @> $2 OR c.consistency_query @> $3",
        rewrap("c.consistency_tags"),
        rewrap("q.item->'tags'"),
    )))
    .bind(tag_key)
    .bind(Json(&keyed))
    .bind(Json(&in_query))
    .execute(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.snapshots s SET tag_value = r.new FROM skilj_blind_rotation r \
         WHERE s.tag_key = $1 AND s.tag_value = r.old"
    )))
    .bind(tag_key)
    .execute(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.blind_tags SET key_generation = $2, key_fingerprint = $3 \
         WHERE tag_key = $1"
    )))
    .bind(tag_key)
    .bind(i64::from(from) + 1)
    .bind(fingerprint)
    .execute(&mut *tx)
    .await?;
    // Every instance's event cache holds the old tags (docs/architecture.md
    // §205's erasure does the same).
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.registrations_generation SET generation = generation + 1"
    )))
    .execute(&mut *tx)
    .await?;
    tx.commit().await?;
    Ok(true)
}

/// Records `key_fingerprint` for `bounded_context`'s blind tag `tag_key`
/// when none is stored yet (docs/architecture.md §208): a tenant created
/// by an instance that couldn't compute it. A no-op when one is stored.
pub async fn record_blind_tag_fingerprint(
    pool: &Pool,
    bounded_context: &str,
    tag_key: &str,
    key_fingerprint: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.blind_tags SET key_fingerprint = $2 \
         WHERE tag_key = $1 AND key_fingerprint IS NULL"
    )))
    .bind(tag_key)
    .bind(key_fingerprint)
    .execute(pool)
    .await?;
    Ok(())
}

/// Refuses `tag_mappings` unless each is blind exactly when the bounded
/// context stores a blind tag for its key (docs/architecture.md §205):
/// a key is one constraint for every type that maps it, so a type can't
/// store in the clear what another hashes, nor hash a key no `BlindTag`
/// declares. Checked by the type upserts, whichever surface registers.
async fn check_blind_tag_mappings(
    pool: &Pool,
    bounded_context: &str,
    tag_mappings: &[TagMapping],
) -> crate::error::Result<()> {
    if tag_mappings.is_empty() {
        return Ok(());
    }
    // A bounded context an older instance added has no table yet.
    ensure_blind_tags_table(pool, bounded_context).await?;
    let schema = schema_ident(bounded_context);
    let keys: Vec<&str> = tag_mappings.iter().map(|m| m.key.as_str()).collect();
    let blind_keys: Vec<(String,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT tag_key FROM {schema}.blind_tags WHERE tag_key = ANY($1)"
    )))
    .bind(&keys)
    .fetch_all(pool)
    .await?;
    let consistent = tag_mappings
        .iter()
        .all(|m| m.blind == blind_keys.iter().any(|(k,)| *k == m.key));
    if !consistent {
        return Err(crate::event_store::Error::BlindTagMismatch.into());
    }
    Ok(())
}

/// `commands.consistency_query`, the query a command was decided with
/// (docs/architecture.md §198), for a bounded context from before it. Its
/// own statement, never in the transaction of
/// [`ensure_event_tags_index`]'s backfill: adding the column locks
/// `commands` against reads too, and held through the backfill it stopped
/// every command read, and every read of a command's events, for as long
/// as that took (docs/architecture.md §200).
#[tracing::instrument(skip_all)]
pub async fn ensure_consistency_query_column<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::raw_sql(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "commands",
        &["consistency_query"],
        format!(
            "ALTER TABLE {schema}.commands ADD COLUMN IF NOT EXISTS consistency_query \
             JSONB NOT NULL DEFAULT '[]'"
        ),
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// Bounded contexts, by name and creation time, this process has run
/// [`ensure_bounded_context_current`] for.
type CurrentBoundedContexts = std::sync::Mutex<std::collections::HashSet<(String, DateTime<Utc>)>>;

fn current_bounded_contexts() -> &'static CurrentBoundedContexts {
    static CURRENT: std::sync::OnceLock<CurrentBoundedContexts> = std::sync::OnceLock::new();
    CURRENT.get_or_init(Default::default)
}

/// Brings a bounded context's schema up to what this version reads and
/// writes - [`ensure_consistency_query_column`], then
/// [`ensure_event_tags_index`], each its own transaction - once per
/// process. `build()` runs it for every bounded context there is; the
/// command path and the background catch-up run it for each they touch,
/// so a bounded context an older instance adds during a rolling deploy,
/// without either, is brought up to date by the first newer instance to
/// meet it rather than failing there until one restarts
/// (docs/architecture.md §200). Keyed by creation time too: a bounded
/// context deleted and added again under the same name is a new schema.
pub async fn ensure_bounded_context_current(
    pool: &Pool,
    bounded_context: &BoundedContext,
) -> crate::error::Result<()> {
    let key = (bounded_context.name.clone(), bounded_context.created_at);
    if current_bounded_contexts()
        .lock()
        .unwrap_or_else(|e| e.into_inner())
        .contains(&key)
    {
        return Ok(());
    }
    make_bounded_context_current(pool, bounded_context).await
}

/// [`ensure_bounded_context_current`] without its once-per-process
/// shortcut: the patches always run, each a catalog lookup when nothing is
/// missing (docs/architecture.md §158). `build()` calls this, so startup
/// brings every bounded context up to date even when something earlier in
/// the process - another instance's background tick - already marked it
/// current and its schema has changed since.
pub async fn make_bounded_context_current(
    pool: &Pool,
    bounded_context: &BoundedContext,
) -> crate::error::Result<()> {
    ensure_consistency_query_column(pool, &bounded_context.name).await?;
    ensure_event_tags_index(pool, &bounded_context.name).await?;
    ensure_blind_tags_table(pool, &bounded_context.name).await?;
    ensure_encryption_key_provider_columns(pool, &bounded_context.name).await?;
    drop_events_by_tags_index(pool, &bounded_context.name).await?;
    current_bounded_contexts()
        .lock()
        .unwrap_or_else(|e| e.into_inner())
        .insert((bounded_context.name.clone(), bounded_context.created_at));
    Ok(())
}

/// Which registration table [`registration_version`]/
/// [`set_registration_version`] address (docs/architecture.md §104).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum RegistrationTable {
    EventTypes,
    CommandTypes,
    Projections,
}

impl RegistrationTable {
    fn table(self) -> &'static str {
        match self {
            RegistrationTable::EventTypes => "event_types",
            RegistrationTable::CommandTypes => "command_types",
            RegistrationTable::Projections => "projections",
        }
    }
}

async fn add_registration_version_columns<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::raw_sql(sqlx::AssertSqlSafe(format!(
        "ALTER TABLE {schema}.event_types ADD COLUMN IF NOT EXISTS registered_by_version BIGINT;
         ALTER TABLE {schema}.command_types ADD COLUMN IF NOT EXISTS registered_by_version BIGINT;
         ALTER TABLE {schema}.projections ADD COLUMN IF NOT EXISTS registered_by_version BIGINT"
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// The `registered_by_version` column on a bounded context's
/// `event_types`/`command_types`/`projections` - the application version
/// that last registered each row at startup (`SkiljBuilder::
/// application_version`, docs/architecture.md §104). Reconciliation metadata
/// only, never part of the domain types, so nothing but reconciliation
/// reads or writes it. Checked in `information_schema` first so a startup
/// that finds it already there takes no table lock; `provision_bounded_context_schema`
/// adds it for a new bounded context.
pub async fn ensure_registration_version_columns(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let (present,): (i64,) = sqlx::query_as(
        "SELECT count(*) FROM information_schema.columns \
         WHERE table_schema = $1 AND column_name = 'registered_by_version' \
         AND table_name IN ('event_types', 'command_types', 'projections')",
    )
    .bind(format!("bc_{bounded_context}"))
    .fetch_one(pool)
    .await?;
    if present < 3 {
        add_registration_version_columns(pool, bounded_context).await?;
    }
    Ok(())
}

/// See [`ensure_registration_version_columns`]. `None` for a row no
/// versioned process has registered (or no such row).
pub async fn registration_version(
    pool: &Pool,
    bounded_context: &str,
    table: RegistrationTable,
    name: &str,
) -> crate::error::Result<Option<i64>> {
    let schema = schema_ident(bounded_context);
    let row: Option<(Option<i64>,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT registered_by_version FROM {schema}.{} WHERE name = $1",
        table.table()
    )))
    .bind(name)
    .fetch_optional(pool)
    .await?;
    Ok(row.and_then(|(version,)| version))
}

/// See [`ensure_registration_version_columns`].
pub async fn set_registration_version(
    pool: &Pool,
    bounded_context: &str,
    table: RegistrationTable,
    name: &str,
    version: i64,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.{} SET registered_by_version = $1 WHERE name = $2",
        table.table()
    )))
    .bind(version)
    .bind(name)
    .execute(pool)
    .await?;
    Ok(())
}

/// `projection_state.owner`/`projection_rebuild_state.owner` (cross-tenant
/// projection read fix, docs/architecture.md's own write-up of this
/// pass) - `ensure_idempotency_keys_table`'s own doc comment's "no
/// general per-bounded-context schema migration mechanism" applies
/// identically here, just for an added column rather than an added
/// table: `ALTER TABLE ... ADD COLUMN IF NOT EXISTS`, called
/// unconditionally on every `build()`, is the whole migration story.
/// Unlike `ensure_idempotency_keys_table`, `provision_bounded_context_schema`
/// itself never needs this - a brand-new context's `CREATE TABLE`
/// already declares `owner` from the start - so this only ever runs
/// against an already-open `pool`, never inside that function's own
/// provisioning transaction, and takes `&Pool` directly rather than a
/// generic executor.
#[tracing::instrument(skip_all)]
pub async fn ensure_projection_state_owner_columns(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "projection_state",
        &["owner"],
        format!("ALTER TABLE {schema}.projection_state ADD COLUMN IF NOT EXISTS owner TEXT"),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "projection_rebuild_state",
        &["owner"],
        format!(
            "ALTER TABLE {schema}.projection_rebuild_state ADD COLUMN IF NOT EXISTS owner TEXT"
        ),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// `projection_state.as_of_sequence`/`projection_rebuild_state.as_of_sequence`
/// - the real fix behind issue #25's investigation, following
/// `ensure_projection_state_owner_columns`'s own pattern exactly (see its
/// own doc comment): a bounded context provisioned before this column
/// existed gets it patched in here, `DEFAULT -1` matching a brand-new
/// row's own starting value.
///
/// A blanket `-1` backfill is safe even for a row with real accumulated
/// `state` from before this migration, and deliberately doesn't try to
/// derive each row's true historical position: `catch_up_bounded_context`/
/// `insert_event_and_update_sync_projections_in_tx` never re-fetch an
/// event once the *projection-level* `projections.caught_up_to` (an
/// existing column, untouched by this migration) has passed it - that
/// coarser gate is what actually decides which events a tick ever looks
/// at again, not this row's own `as_of_sequence`. So every event this
/// row's freshly-`-1` `as_of_sequence` will ever be compared against is
/// one `caught_up_to` hadn't reached yet at migration time, i.e. one this
/// row genuinely has never folded - the exact case `-1` is supposed to
/// mean.
#[tracing::instrument(skip_all)]
pub async fn ensure_projection_state_as_of_sequence_columns(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "projection_state",
        &["as_of_sequence"],
        format!(
            "ALTER TABLE {schema}.projection_state \
         ADD COLUMN IF NOT EXISTS as_of_sequence BIGINT NOT NULL DEFAULT -1"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "projection_rebuild_state",
        &["as_of_sequence"],
        format!(
            "ALTER TABLE {schema}.projection_rebuild_state \
         ADD COLUMN IF NOT EXISTS as_of_sequence BIGINT NOT NULL DEFAULT -1"
        ),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// `read_cursors.checked_out_at` - the real fix behind issue
/// #25's investigation of the Kafka/AMQP/NATS outbound bridges
/// (docs/architecture.md §53): a bounded context provisioned before this
/// column existed gets it patched in here, following
/// `ensure_projection_state_owner_columns`'s own established pattern -
/// nullable, no `DEFAULT`, since `NULL` already means exactly "not
/// checked out" (`ReadCursor.checked_out_at`'s own spec doc comment),
/// the same value a brand-new row starts at.
pub async fn ensure_read_cursors_checkout_column(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "read_cursors",
        &["checked_out_at"],
        format!(
            "ALTER TABLE {schema}.read_cursors ADD COLUMN IF NOT EXISTS checked_out_at TIMESTAMPTZ"
        ),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// `event_types.owner_tag_key`/`access_tokens.scope`/
/// `command_types.owner_tag_key`/`snapshots.owner` - the raw-event,
/// command and snapshot halves of the cross-tenant read fix
/// (docs/architecture.md's own write-up of these passes), following
/// `ensure_projection_state_owner_columns`'s own pattern and reasoning
/// exactly (see its own doc comment): a targeted, idempotent `ALTER
/// TABLE ... ADD COLUMN IF NOT EXISTS` patch, called unconditionally on
/// every `build()`, for a bounded context provisioned before these
/// fields existed.
#[tracing::instrument(skip_all)]
pub async fn ensure_event_scoping_columns(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "event_types",
        &["owner_tag_key"],
        format!("ALTER TABLE {schema}.event_types ADD COLUMN IF NOT EXISTS owner_tag_key TEXT"),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "access_tokens",
        &["scope"],
        format!("ALTER TABLE {schema}.access_tokens ADD COLUMN IF NOT EXISTS scope TEXT"),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "command_types",
        &["owner_tag_key"],
        format!("ALTER TABLE {schema}.command_types ADD COLUMN IF NOT EXISTS owner_tag_key TEXT"),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "snapshots",
        &["owner"],
        format!("ALTER TABLE {schema}.snapshots ADD COLUMN IF NOT EXISTS owner TEXT"),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// `event_types.private_fields`/`command_types.private_fields` - the
/// private-field mechanism (docs/architecture.md's own write-up of this
/// pass), following `ensure_event_scoping_columns`'s own pattern and
/// reasoning exactly for a bounded context provisioned before these
/// columns existed.
pub async fn ensure_private_field_columns(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "event_types",
        &["private_fields"],
        format!("ALTER TABLE {schema}.event_types ADD COLUMN IF NOT EXISTS private_fields JSONB NOT NULL DEFAULT '[]'"),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "command_types",
        &["private_fields"],
        format!("ALTER TABLE {schema}.command_types ADD COLUMN IF NOT EXISTS private_fields JSONB NOT NULL DEFAULT '[]'"),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// `projections.requires_capability` (docs/architecture.md §228,
/// `Projection.requires_capability` in the spec), following
/// `ensure_private_field_columns`'s own pattern for a bounded context
/// provisioned before this column existed. Null for every projection
/// registered before it: nothing was required, and the next
/// registration writes what the compiled projection declares.
pub async fn ensure_projection_requires_capability_column(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "projections",
        &["requires_capability"],
        format!(
            "ALTER TABLE {schema}.projections ADD COLUMN IF NOT EXISTS requires_capability TEXT"
        ),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// Set a registered projection's `requires_capability` on its own, for a
/// re-registration that staged a rebuild: who may read applies at once,
/// while the rest of the new definition waits for the rebuild.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn set_projection_requires_capability(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
    requires_capability: Option<&str>,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.projections SET requires_capability = $1 WHERE name = $2"
    )))
    .bind(requires_capability)
    .bind(name)
    .execute(pool)
    .await?;
    Ok(())
}

/// `commands.metadata_correlation_id`/`metadata_causation_id`,
/// `events.metadata_correlation_id`/`metadata_causation_id` (
/// issue #18), following `ensure_event_scoping_columns`'s own pattern
/// and reasoning exactly for a bounded context provisioned before these
/// columns existed. The two partial indexes mirror
/// `provision_bounded_context_schema`'s own fresh-provision ones
/// (`events_by_correlation_id`/`commands_by_correlation_id`) - `CREATE
/// INDEX IF NOT EXISTS` rather than plain `CREATE INDEX`, since unlike
/// the columns themselves this runs unconditionally on every `build()`,
/// not only once.
#[tracing::instrument(skip_all)]
pub async fn ensure_correlation_causation_columns(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "events",
        &["metadata_correlation_id"],
        format!(
            "ALTER TABLE {schema}.events ADD COLUMN IF NOT EXISTS metadata_correlation_id TEXT"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "events",
        &["metadata_causation_id"],
        format!("ALTER TABLE {schema}.events ADD COLUMN IF NOT EXISTS metadata_causation_id TEXT"),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "commands",
        &["metadata_correlation_id"],
        format!(
            "ALTER TABLE {schema}.commands ADD COLUMN IF NOT EXISTS metadata_correlation_id TEXT"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "commands",
        &["metadata_causation_id"],
        format!(
            "ALTER TABLE {schema}.commands ADD COLUMN IF NOT EXISTS metadata_causation_id TEXT"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(
        &schema,
        "events_by_correlation_id",
        format!(
            "CREATE INDEX IF NOT EXISTS events_by_correlation_id ON {schema}.events \
         (metadata_correlation_id) WHERE metadata_correlation_id IS NOT NULL"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(
        &schema,
        "commands_by_correlation_id",
        format!(
            "CREATE INDEX IF NOT EXISTS commands_by_correlation_id ON {schema}.commands \
         (metadata_correlation_id) WHERE metadata_correlation_id IS NOT NULL"
        ),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// `access_tokens.start_from`/`.start_at_sequence`/`.start_at_time` -
/// `EventReadToken.start_from`/`.start_at_sequence`/`.start_at_time`
/// (docs/architecture.md's own write-up of these two passes), meaningful
/// only for the `event_read` kind but columns on the shared
/// `access_tokens` table exactly as `scope` already is
/// (`EventReadToken.scope`'s own doc comment on why one column serves
/// all four kinds). Following `ensure_event_scoping_columns`'s own
/// pattern exactly: targeted, idempotent `ALTER TABLE ... ADD COLUMN IF
/// NOT EXISTS`, called unconditionally on every `build()`, for a bounded
/// context provisioned before these columns existed - `start_at_sequence`/
/// `start_at_time` folded into this same function rather than a fourth
/// one, since they were added in the identical follow-up pass that
/// needs nothing about `start_from`'s own retrofit changed.
///
/// `start_from` is `NOT NULL DEFAULT 'beginning'` rather than nullable -
/// every row this backfills is a token minted before `start_from`
/// existed, and `EventReadStartPosition::Beginning` is exactly what such
/// a token already behaves as (`consume_events`' own `-1` fallback), so
/// the column's own default and the domain default agree;
/// `get_event_read_token` never has to handle an absent value. No such
/// domain default exists for `start_at_sequence`/`start_at_time` - a
/// `beginning` token never had one to fall back to - so both stay
/// nullable, exactly the shape `EventReadToken`'s own fields already
/// have.
pub async fn ensure_event_read_token_start_from_column(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "access_tokens",
        &["start_from"],
        format!(
            "ALTER TABLE {schema}.access_tokens \
         ADD COLUMN IF NOT EXISTS start_from TEXT NOT NULL DEFAULT 'beginning'"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "access_tokens",
        &["start_at_sequence"],
        format!(
            "ALTER TABLE {schema}.access_tokens ADD COLUMN IF NOT EXISTS start_at_sequence BIGINT"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(add_columns_patch(
        &schema,
        "access_tokens",
        &["start_at_time"],
        format!(
            "ALTER TABLE {schema}.access_tokens ADD COLUMN IF NOT EXISTS start_at_time TIMESTAMPTZ"
        ),
    )))
    .execute(pool)
    .await?;
    // The check a freshly provisioned `start_from` has, under the name
    // Postgres gives it there. Added on its own, not with the column: a
    // bounded context that got the column from an earlier version of
    // this patch lacks it too (docs/architecture.md §159).
    sqlx::query(sqlx::AssertSqlSafe(add_constraint_patch(
        &schema,
        "access_tokens",
        "access_tokens_start_from_check",
        format!(
            "ALTER TABLE {schema}.access_tokens ADD CONSTRAINT access_tokens_start_from_check \
             CHECK (start_from IN ('beginning', 'latest', 'at_sequence', 'at_time'))"
        ),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

/// Physically, permanently removes a bounded context and everything
/// scoped to it - `DeleteBoundedContext` in specs/skilj.allium. Writes
/// nothing to the access trail, so its grants stay `held` in
/// `capabilityHistory`: production code calls
/// [`hard_delete_bounded_context_with_trail`], and this is for tests and
/// for a caller that records the end itself. One
/// transaction: `DROP SCHEMA ... CASCADE` (every per-context table this
/// module owns, gone in a single statement), then the `bounded_contexts`
/// registry row itself, whose own `ON DELETE CASCADE` cleans up
/// `role_access_mappings`/`access_token_index` automatically. The pure
/// `bootstrap::delete_bounded_context` check (superadmin, `archived`,
/// not `admin`) is the caller's job to run first - this function trusts
/// it already has.
#[tracing::instrument(skip_all, fields(name = %name))]
pub async fn hard_delete_bounded_context(pool: &Pool, name: &str) -> crate::error::Result<()> {
    let schema = schema_ident(name);
    let mut tx = pool.begin().await?;
    sqlx::query(sqlx::AssertSqlSafe(format!("DROP SCHEMA {schema} CASCADE")))
        .execute(&mut *tx)
        .await?;
    sqlx::query("DELETE FROM bounded_contexts WHERE name = $1")
        .bind(name)
        .execute(&mut *tx)
        .await?;
    tx.commit().await?;
    notify_registration_changed(pool).await;
    Ok(())
}

/// [`hard_delete_bounded_context`] that also ends the context's grants in
/// the access trail (docs/architecture.md §229): an `AccessRevoked`
/// (reason `bounded_context_deleted`) for every active mapping and a
/// `PrivateFieldAccessRevoked` for every active private-field grant, with
/// `actor_role_id` as the actor, committed with the deletion. Without them
/// `capabilityHistory` would keep saying a deleted context's grants are
/// held. A context nobody was granted anything in records nothing.
///
/// Locks, in the writers' order (a mapping row, then the admin sequence):
/// the `bounded_contexts` row first, which also holds off a new mapping
/// (its foreign key needs that row), then the active mapping rows, then
/// the private-field grants table, so what is read here is everything
/// there is and nothing can be added before the drop. The schema is
/// dropped before the events are recorded, so the admin sequence lock is
/// held only for those inserts and the commit, not across a large drop.
#[tracing::instrument(skip_all, fields(name = %name))]
pub async fn hard_delete_bounded_context_with_trail(
    pool: &Pool,
    name: &str,
    actor_role_id: &str,
) -> crate::error::Result<()> {
    let admin = require_admin_bounded_context(pool).await?;
    let schema = schema_ident(name);
    let mut tx = pool.begin().await?;
    sqlx::query("SELECT name FROM bounded_contexts WHERE name = $1 FOR UPDATE")
        .bind(name)
        .fetch_optional(&mut *tx)
        .await?;
    let mapped: Vec<(String,)> = sqlx::query_as(
        "SELECT role_id FROM role_access_mappings \
         WHERE bounded_context = $1 AND status = 'active' ORDER BY role_id FOR UPDATE",
    )
    .bind(name)
    .fetch_all(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "LOCK TABLE {schema}.private_field_grants IN SHARE ROW EXCLUSIVE MODE"
    )))
    .execute(&mut *tx)
    .await?;
    let private: Vec<(String, String)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT id, grantee_role_id FROM {schema}.private_field_grants \
         WHERE status = 'active' ORDER BY id"
    )))
    .fetch_all(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!("DROP SCHEMA {schema} CASCADE")))
        .execute(&mut *tx)
        .await?;
    sqlx::query("DELETE FROM bounded_contexts WHERE name = $1")
        .bind(name)
        .execute(&mut *tx)
        .await?;
    for (role_id,) in &mapped {
        record_access_event(
            &mut tx,
            &admin,
            AccessChange::context_ended(role_id, name, actor_role_id),
        )
        .await?;
    }
    for (grant_id, grantee_id) in &private {
        record_access_event(
            &mut tx,
            &admin,
            AccessChange::private_field_ended(grant_id, grantee_id, name, actor_role_id),
        )
        .await?;
    }
    tx.commit().await?;
    notify_registration_changed(pool).await;
    Ok(())
}

// --- Role ---

#[derive(sqlx::FromRow)]
struct RoleRow {
    id: String,
    external_subject: String,
    name: String,
    superadmin: bool,
    status: String,
    created_at: DateTime<Utc>,
    revoked_at: Option<DateTime<Utc>>,
}

impl RoleRow {
    fn into_domain(self) -> Role {
        Role {
            id: self.id,
            external_subject: self.external_subject,
            name: self.name,
            superadmin: self.superadmin,
            status: role_status_from_str(&self.status),
            created_at: self.created_at,
            revoked_at: self.revoked_at,
        }
    }
}

const ROLE_COLUMNS: &str = "id, external_subject, name, superadmin, status, created_at, revoked_at";

#[tracing::instrument(skip_all)]
pub async fn insert_role(pool: &Pool, role: &Role) -> crate::error::Result<()> {
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO roles ({ROLE_COLUMNS}) VALUES ($1,$2,$3,$4,$5,$6,$7)"
    )))
    .bind(&role.id)
    .bind(&role.external_subject)
    .bind(&role.name)
    .bind(role.superadmin)
    .bind(role_status_to_str(role.status))
    .bind(role.created_at)
    .bind(role.revoked_at)
    .execute(pool)
    .await?;
    Ok(())
}

/// `rule CreateSuperadmin`'s `requires: not exists Role{superadmin: true,
/// status: active}` and its `ensures`, as one atomic step
/// (docs/architecture.md §109): under a transaction-scoped advisory lock,
/// re-checks that no active superadmin exists and only then inserts
/// `role`. Returns `false`, inserting nothing, when one does - including one
/// a concurrent claim (another instance, with its own bootstrap secret)
/// committed after the caller's own check. Without the lock and re-check,
/// two concurrent claims both passed and both became superadmins.
pub async fn insert_superadmin_if_none_active(
    pool: &Pool,
    role: &Role,
) -> crate::error::Result<bool> {
    let mut tx = pool.begin().await?;
    sqlx::query("SELECT pg_advisory_xact_lock(hashtext('skilj_create_superadmin')::bigint)")
        .execute(&mut *tx)
        .await?;
    let (exists,): (bool,) = sqlx::query_as(
        "SELECT EXISTS (SELECT 1 FROM roles WHERE superadmin AND status = 'active')",
    )
    .fetch_one(&mut *tx)
    .await?;
    if exists {
        return Ok(false);
    }
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO roles ({ROLE_COLUMNS}) VALUES ($1,$2,$3,$4,$5,$6,$7)"
    )))
    .bind(&role.id)
    .bind(&role.external_subject)
    .bind(&role.name)
    .bind(role.superadmin)
    .bind(role_status_to_str(role.status))
    .bind(role.created_at)
    .bind(role.revoked_at)
    .execute(&mut *tx)
    .await?;
    tx.commit().await?;
    Ok(true)
}

#[tracing::instrument(skip_all)]
pub async fn get_role(pool: &Pool, id: &str) -> crate::error::Result<Option<Role>> {
    let row: Option<RoleRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {ROLE_COLUMNS} FROM roles WHERE id = $1"
    )))
    .bind(id)
    .fetch_optional(pool)
    .await?;
    Ok(row.map(RoleRow::into_domain))
}

/// Every `Role` this engine currently knows of - the full-snapshot
/// parameter `create_role`/`resolve_role_by_external_subject` each
/// expect as their own `existing_roles` (see their doc comments). An
/// unscoped list, since a `Role` isn't scoped to a bounded context - but
/// not for per-request paths: every user a deployment registers is a
/// row, so authentication uses `active_roles_by_external_subject`
/// instead (docs/architecture.md §110).
#[tracing::instrument(skip_all)]
pub async fn list_roles(pool: &Pool) -> crate::error::Result<Vec<Role>> {
    let rows: Vec<RoleRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {ROLE_COLUMNS} FROM roles"
    )))
    .fetch_all(pool)
    .await?;
    Ok(rows.into_iter().map(RoleRow::into_domain).collect())
}

/// The active `Role` claiming `external_subject`, as the one-element
/// `existing_roles` slice `resolve_role_by_external_subject` takes - what
/// authenticating a request needs, instead of `list_roles`' whole table.
/// At most one row: `roles_unique_active_external_subject` is a unique
/// index on exactly this predicate, and serves the lookup
/// (docs/architecture.md §110).
#[tracing::instrument(skip_all)]
pub async fn active_roles_by_external_subject(
    pool: &Pool,
    external_subject: &str,
) -> crate::error::Result<Vec<Role>> {
    let rows: Vec<RoleRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {ROLE_COLUMNS} FROM roles WHERE external_subject = $1 AND status = 'active'"
    )))
    .bind(external_subject)
    .fetch_all(pool)
    .await?;
    Ok(rows.into_iter().map(RoleRow::into_domain).collect())
}

/// Persists whatever `revoke_role`/`create_superadmin` (or any future
/// rule) produced - a full-row overwrite by `id`, not an upsert; the row
/// must already exist (`insert_role` already ran). `impl PgExecutor`,
/// the same "works on `&Pool` autocommit or inside a caller's own open
/// `Transaction`" treatment `next_sequence` already gets - `revoke_role_and_mappings`
/// below is what needs the latter.
#[tracing::instrument(skip_all)]
pub async fn update_role<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    role: &Role,
) -> crate::error::Result<()> {
    sqlx::query(
        "UPDATE roles SET external_subject = $1, name = $2, superadmin = $3, status = $4, \
         created_at = $5, revoked_at = $6 WHERE id = $7",
    )
    .bind(&role.external_subject)
    .bind(&role.name)
    .bind(role.superadmin)
    .bind(role_status_to_str(role.status))
    .bind(role.created_at)
    .bind(role.revoked_at)
    .bind(&role.id)
    .execute(executor)
    .await?;
    Ok(())
}

// --- BoundedContext ---

#[derive(sqlx::FromRow)]
struct BoundedContextRow {
    name: String,
    status: String,
    created_at: DateTime<Utc>,
    created_by_kind: String,
    created_by_role_id: Option<String>,
    /// issue #13 - just the referenced row's own name; hydrated
    /// into a full `BoundedContext` by `get_bounded_context`/
    /// `list_bounded_contexts`, matching how `created_by_role_id` is
    /// hydrated into a full `Role` below.
    template: Option<String>,
}

const BOUNDED_CONTEXT_COLUMNS: &str =
    "name, status, created_at, created_by_kind, created_by_role_id, template";

/// Provisions the new context's own `bc_<name>` schema (see
/// `provision_bounded_context_schema`) and inserts its `bounded_contexts`
/// registry row in one transaction - a failure partway through either
/// half rolls back the other, so there's never an orphaned schema with
/// no registry row or vice versa. Callers (test fixtures included) don't
/// need to know any of this happens; the signature is unchanged from
/// before schema-per-context existed.
#[tracing::instrument(skip_all)]
pub async fn insert_bounded_context(pool: &Pool, bc: &BoundedContext) -> crate::error::Result<()> {
    let (kind, role_id) = match &bc.created_by {
        ContextCreator::SystemCreator => ("system", None),
        ContextCreator::SuperadminCreator { role } => ("superadmin", Some(role.id.clone())),
    };

    let mut tx = pool.begin().await?;
    provision_bounded_context_schema(&mut tx, &bc.name).await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO bounded_contexts ({BOUNDED_CONTEXT_COLUMNS}) VALUES ($1,$2,$3,$4,$5,$6)"
    )))
    .bind(&bc.name)
    .bind(bounded_context_status_to_str(bc.status))
    .bind(bc.created_at)
    .bind(kind)
    .bind(role_id)
    .bind(bc.template.as_ref().map(|t| t.name.clone()))
    .execute(&mut *tx)
    .await?;
    tx.commit().await?;
    notify_registration_changed(pool).await;
    Ok(())
}

/// Persists an `archive_bounded_context` outcome - a status-only update,
/// the only field any rule in this crate ever changes on an existing
/// `bounded_contexts` row (`name`/`created_at`/`created_by` are fixed at
/// creation - `rule AddBoundedContext`'s own "chosen once, at the moment
/// of creation" framing, and there is no rename). Distinct from
/// `insert_bounded_context`, which provisions a brand new schema - this
/// touches only the registry row of one that already exists.
#[tracing::instrument(skip_all, fields(name = %name))]
pub async fn update_bounded_context_status(
    pool: &Pool,
    name: &str,
    status: BoundedContextStatus,
) -> crate::error::Result<()> {
    sqlx::query("UPDATE bounded_contexts SET status = $1 WHERE name = $2")
        .bind(bounded_context_status_to_str(status))
        .bind(name)
        .execute(pool)
        .await?;
    notify_registration_changed(pool).await;
    Ok(())
}

/// Unlike most `into_domain`-style conversions in this module,
/// `ContextCreator::SuperadminCreator` needs a second query (the
/// referenced `roles` row - see the migration's own note on why
/// `bounded_contexts` normalises onto `roles` rather than denormalising
/// its fields directly), so this is a free function taking the row plus
/// an already-resolved `Option<Role>`, not a method on the row type.
fn bounded_context_from_row(
    row: BoundedContextRow,
    role: Option<Role>,
    template: Option<Box<BoundedContext>>,
) -> BoundedContext {
    let created_by = match row.created_by_kind.as_str() {
        "system" => ContextCreator::SystemCreator,
        _ => ContextCreator::SuperadminCreator {
            role: role.expect(
                "bounded_contexts row has created_by_kind = 'superadmin' but its \
                 created_by_role_id doesn't resolve to a roles row - the FK should make \
                 this unreachable",
            ),
        },
    };
    BoundedContext {
        name: row.name,
        status: bounded_context_status_from_str(&row.status),
        created_at: row.created_at,
        created_by,
        template,
    }
}

/// Like `get_bounded_context`, for callers that already hold a name they
/// expect to exist. A missing row still comes back as an ordinary
/// `sqlx::Error::RowNotFound` rather than a panic: the caller's own access
/// check can pass just before a concurrent `hard_delete_bounded_context`
/// lands, and that race must surface as an error response, not take the
/// request task down.
async fn require_bounded_context(pool: &Pool, name: &str) -> crate::error::Result<BoundedContext> {
    get_bounded_context(pool, name)
        .await?
        .ok_or_else(crate::error::Error::row_not_found)
}

/// Like [`require_bounded_context`], for an `EventType` a caller already
/// has a stored reference to (an `events`/`access_tokens` row's own
/// `event_type_name`) - the identical `hard_delete_bounded_context` race
/// applies: the whole schema, `event_types` included, can vanish between
/// an earlier query in the same function and this one.
async fn require_event_type(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
) -> crate::error::Result<EventType> {
    get_event_type(pool, bounded_context, name)
        .await?
        .ok_or_else(crate::error::Error::row_not_found)
}

/// [`require_event_type`]'s `CommandType` sibling.
async fn require_command_type(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
) -> crate::error::Result<CommandType> {
    get_command_type(pool, bounded_context, name)
        .await?
        .ok_or_else(crate::error::Error::row_not_found)
}

/// [`require_event_type`]'s `Command` sibling, for an `events` row's own
/// `origin_command_id`.
async fn require_command(
    pool: &Pool,
    bounded_context: &str,
    id: i64,
) -> crate::error::Result<Command> {
    get_command_by_id(pool, bounded_context, id)
        .await?
        .ok_or_else(crate::error::Error::row_not_found)
}

/// The columns that read a `bounded_contexts` row hydrated in one
/// statement (docs/architecture.md §199), from
/// [`HYDRATED_BOUNDED_CONTEXT_FROM`]: the row as `bc_*`, its creating role
/// as `r_*`, its template as `t_*` and the template's creating role as
/// `tr_*`. A template is never itself templated
/// (`TemplateIsNeverItselfTemplated`), so that is the whole
/// `BoundedContext`. Read back with [`hydrated_bounded_context`].
fn hydrated_bounded_context_columns() -> String {
    let aliased = |columns: &str, alias: &str| {
        columns
            .split(", ")
            .map(|column| format!("{alias}.{column} AS {alias}_{column}"))
            .collect::<Vec<_>>()
            .join(", ")
    };
    [
        aliased(BOUNDED_CONTEXT_COLUMNS, "bc"),
        aliased(ROLE_COLUMNS, "r"),
        aliased(BOUNDED_CONTEXT_COLUMNS, "t"),
        aliased(ROLE_COLUMNS, "tr"),
    ]
    .join(", ")
}

/// The joins [`hydrated_bounded_context_columns`] reads from; `bc` is the
/// bounded context itself.
const HYDRATED_BOUNDED_CONTEXT_FROM: &str = "bounded_contexts bc \
     LEFT JOIN roles r ON r.id = bc.created_by_role_id \
     LEFT JOIN bounded_contexts t ON t.name = bc.template \
     LEFT JOIN roles tr ON tr.id = t.created_by_role_id";

/// The [`BoundedContext`] a [`hydrated_bounded_context_columns`] row holds.
fn hydrated_bounded_context(row: &sqlx::postgres::PgRow) -> crate::error::Result<BoundedContext> {
    use sqlx::Row;
    let bounded_context = |alias: &str| -> Result<Option<BoundedContextRow>, sqlx::Error> {
        let Some(name) = row.try_get::<Option<String>, _>(format!("{alias}_name").as_str())? else {
            return Ok(None);
        };
        Ok(Some(BoundedContextRow {
            name,
            status: row.try_get(format!("{alias}_status").as_str())?,
            created_at: row.try_get(format!("{alias}_created_at").as_str())?,
            created_by_kind: row.try_get(format!("{alias}_created_by_kind").as_str())?,
            created_by_role_id: row.try_get(format!("{alias}_created_by_role_id").as_str())?,
            template: row.try_get(format!("{alias}_template").as_str())?,
        }))
    };
    let role = |alias: &str| -> Result<Option<Role>, sqlx::Error> {
        let Some(id) = row.try_get::<Option<String>, _>(format!("{alias}_id").as_str())? else {
            return Ok(None);
        };
        Ok(Some(
            RoleRow {
                id,
                external_subject: row.try_get(format!("{alias}_external_subject").as_str())?,
                name: row.try_get(format!("{alias}_name").as_str())?,
                superadmin: row.try_get(format!("{alias}_superadmin").as_str())?,
                status: row.try_get(format!("{alias}_status").as_str())?,
                created_at: row.try_get(format!("{alias}_created_at").as_str())?,
                revoked_at: row.try_get(format!("{alias}_revoked_at").as_str())?,
            }
            .into_domain(),
        ))
    };
    let template_role = role("tr")?;
    let template = bounded_context("t")?
        .map(|template| Box::new(bounded_context_from_row(template, template_role, None)));
    let own = bounded_context("bc")?.expect("a hydrated row always has its own bounded context");
    Ok(bounded_context_from_row(own, role("r")?, template))
}

#[tracing::instrument(skip_all, fields(name = %name))]
pub async fn get_bounded_context(
    pool: &Pool,
    name: &str,
) -> crate::error::Result<Option<BoundedContext>> {
    // Its role and template in the same statement (docs/architecture.md
    // §199): read one after another they were up to four round trips, on
    // nearly every request.
    let row = sqlx::query(sqlx::AssertSqlSafe(format!(
        "SELECT {} FROM {HYDRATED_BOUNDED_CONTEXT_FROM} WHERE bc.name = $1",
        hydrated_bounded_context_columns()
    )))
    .bind(name)
    .fetch_optional(pool)
    .await?;
    row.as_ref().map(hydrated_bounded_context).transpose()
}

/// Every `BoundedContext` this engine currently knows of - the
/// `bounded_contexts` parameter `bootstrap::list_bounded_contexts`
/// expects (see its own doc comment: unrestricted, same full-snapshot
/// treatment `list_roles`/`list_role_access_mappings` get). Backs the
/// `BoundedContextDirectory` surface's `boundedContexts` query - and,
/// issue #15, `SkiljBuilder::build()`'s startup warm-up loop
/// plus all three background pollers, which is why this used to be a
/// real N+1 (one `get_role` query per row) worth fixing: `list_roles`
/// already fetches every `Role` in one query, so one full-table fetch
/// plus an in-memory lookup replaces what was one query per row.
#[tracing::instrument(skip_all)]
pub async fn list_bounded_contexts(pool: &Pool) -> crate::error::Result<Vec<BoundedContext>> {
    let rows: Vec<BoundedContextRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {BOUNDED_CONTEXT_COLUMNS} FROM bounded_contexts"
    )))
    .fetch_all(pool)
    .await?;

    let roles_by_id: std::collections::HashMap<String, Role> = list_roles(pool)
        .await?
        .into_iter()
        .map(|role| (role.id.clone(), role))
        .collect();

    // issue #13: a template is always some other row already in
    // this same full-table fetch (invariant TemplateIsNeverItselfTemplated
    // rules out a template needing a template of its own), so resolving
    // `template` here is a map lookup, not an extra query per row - the
    // same N+1 avoidance this function's own doc comment already commits
    // to for `created_by_role_id`/`Role`. Build every context with
    // `template: None` first, keyed by name, then fill in the box on a
    // second pass.
    let mut contexts_by_name = std::collections::HashMap::with_capacity(rows.len());
    let mut template_names = Vec::with_capacity(rows.len());
    for row in rows {
        let role = row.created_by_role_id.as_ref().map(|role_id| {
            roles_by_id.get(role_id).cloned().expect(
                "bounded_contexts.created_by_role_id references a roles row that no longer \
                 exists",
            )
        });
        let name = row.name.clone();
        let template_name = row.template.clone();
        contexts_by_name.insert(name.clone(), bounded_context_from_row(row, role, None));
        template_names.push((name, template_name));
    }
    for (name, template_name) in template_names {
        let Some(template_name) = template_name else {
            continue;
        };
        let template = contexts_by_name.get(&template_name).cloned().expect(
            "bounded_contexts.template references a bounded_contexts row that no longer exists",
        );
        contexts_by_name.get_mut(&name).unwrap().template = Some(Box::new(template));
    }

    // Name order, deliberately, and the reason is a caller-visible
    // decision rather than tidiness: `skilj-graphql`'s schema build walks
    // these contexts in order and resolves generated type-name collisions
    // first-wins, so which of two colliding projections is served is
    // whatever order it walks them in. `HashMap::into_values()` is
    // `RandomState` order - per-thread, and re-seeded per process - so the
    // winner could change between two schema builds in one run, and a
    // caller could be served one projection and then, after an unrelated
    // registration change, be served the other. Observed in CI as
    // `colliding_projection_type_names_serve_one_and_refuse_the_other`
    // failing with *both* colliding projections served
    // (skilj/tests/projection_query.rs:1760), which is what a mid-test
    // rebuild that re-decided the collision looks like.
    //
    // So this order is now part of the function's contract, unlike
    // `list_roles`/`list_role_access_mappings`'s unordered `Vec` return.
    let mut contexts: Vec<BoundedContext> = contexts_by_name.into_values().collect();
    contexts.sort_by(|a, b| a.name.cmp(&b.name));
    Ok(contexts)
}

/// Ultra-review bug_005's own fix - see migration `0003_add_bounded_
/// context_dispatch_template.sql`'s own doc comment for the full
/// reasoning. `createBoundedContextFromTemplate` calls this once,
/// immediately after `insert_bounded_context` succeeds, to set the
/// permanent, never-cleared record `TemplateCache`'s dispatch resolution
/// reads from (`list_dispatch_template_mappings` below) - deliberately
/// not part of `insert_bounded_context`'s own signature, since every
/// other caller of that function (bootstrap, ordinary `AddBoundedContext`,
/// every test fixture) has no dispatch template to set and shouldn't
/// need to pass one.
#[tracing::instrument(skip_all, fields(name = %name))]
pub async fn set_dispatch_template(
    pool: &Pool,
    name: &str,
    dispatch_template: &str,
) -> crate::error::Result<()> {
    sqlx::query("UPDATE bounded_contexts SET dispatch_template = $1 WHERE name = $2")
        .bind(dispatch_template)
        .bind(name)
        .execute(pool)
        .await?;
    Ok(())
}

/// `TemplateCache::refresh`'s own data source - every `BoundedContext`'s
/// own `name` paired with its `dispatch_template` (`None` for the
/// ordinary, untemplated case), read directly rather than through
/// `list_bounded_contexts`'s full `BoundedContext` hydration: dispatch
/// resolution needs nothing else about a context, and this stays a
/// single flat query with no recursive template lookup, no `Role`
/// join - a smaller, cheaper, single-purpose read for a call this
/// crate's own cross-instance listener makes on every registration
/// change.
#[tracing::instrument(skip_all)]
pub async fn list_dispatch_template_mappings(
    pool: &Pool,
) -> crate::error::Result<Vec<(String, Option<String>)>> {
    let rows: Vec<(String, Option<String>)> =
        sqlx::query_as("SELECT name, dispatch_template FROM bounded_contexts")
            .fetch_all(pool)
            .await?;
    Ok(rows)
}

// --- EventType ---

fn missed_occurrence_policy_to_str(policy: MissedOccurrencePolicy) -> &'static str {
    match policy {
        MissedOccurrencePolicy::Skip => "skip",
        MissedOccurrencePolicy::FireOnce => "fire_once",
        MissedOccurrencePolicy::ReplayBacklog => "replay_backlog",
    }
}

fn missed_occurrence_policy_from_str(s: &str) -> MissedOccurrencePolicy {
    match s {
        "fire_once" => MissedOccurrencePolicy::FireOnce,
        "replay_backlog" => MissedOccurrencePolicy::ReplayBacklog,
        _ => MissedOccurrencePolicy::Skip,
    }
}

/// issue #95 - a recurring chain's own policy, as stored.
fn recurrence_policy_to_str(policy: crate::plugin::MissedRunPolicy) -> &'static str {
    match policy {
        crate::plugin::MissedRunPolicy::Skip => "skip",
        crate::plugin::MissedRunPolicy::FireOnce => "fire_once",
        crate::plugin::MissedRunPolicy::FireAll => "fire_all",
    }
}

/// The inverse of `recurrence_policy_to_str` - `None` for a `NULL`
/// column (a one-shot) or for a value no writer this codebase knows
/// could have stored (defensive; the `CHECK` constraint already refuses
/// those at the door).
fn recurrence_policy_from_str(s: Option<&str>) -> Option<crate::plugin::MissedRunPolicy> {
    match s {
        Some("skip") => Some(crate::plugin::MissedRunPolicy::Skip),
        Some("fire_once") => Some(crate::plugin::MissedRunPolicy::FireOnce),
        Some("fire_all") => Some(crate::plugin::MissedRunPolicy::FireAll),
        _ => None,
    }
}

#[derive(sqlx::FromRow)]
struct EventTypeRow {
    name: String,
    schema: String,
    schema_version: i64,
    tag_mappings: Json<Vec<TagMapping>>,
    owner_tag_key: Option<String>,
    sensitive_fields: Json<Vec<SensitiveField>>,
    external_creation_allowed: bool,
    direct_creation_allowed: bool,
    system_triggered_allowed: bool,
    system_triggered_schedule: Option<String>,
    missed_occurrence_policy: Option<String>,
    schedule_position: Option<DateTime<Utc>>,
    last_fired_at: Option<DateTime<Utc>>,
    event_read_allowed: bool,
    private_fields: Json<Vec<PrivateField>>,
}

impl EventTypeRow {
    fn into_domain(self, bounded_context: BoundedContext) -> EventType {
        EventType {
            bounded_context,
            name: self.name,
            schema: self.schema,
            schema_version: self.schema_version,
            tag_mappings: self.tag_mappings.0,
            owner_tag_key: self.owner_tag_key,
            sensitive_fields: self.sensitive_fields.0,
            private_fields: self.private_fields.0,
            external_creation_allowed: self.external_creation_allowed,
            direct_creation_allowed: self.direct_creation_allowed,
            system_triggered_allowed: self.system_triggered_allowed,
            system_triggered_schedule: self.system_triggered_schedule,
            missed_occurrence_policy: self
                .missed_occurrence_policy
                .as_deref()
                .map(missed_occurrence_policy_from_str),
            schedule_position: self.schedule_position,
            last_fired_at: self.last_fired_at,
            event_read_allowed: self.event_read_allowed,
        }
    }
}

const EVENT_TYPE_COLUMNS: &str =
    "name, schema, schema_version, tag_mappings, owner_tag_key, sensitive_fields, \
    external_creation_allowed, direct_creation_allowed, system_triggered_allowed, \
    system_triggered_schedule, missed_occurrence_policy, schedule_position, last_fired_at, \
    event_read_allowed, private_fields";

/// Upsert, not insert-only - `RegisterEventType`'s own create-or-update
/// shape (see `event_store::register_event_type`), though no surface
/// calls this yet this pass; used directly by tests/seeding until
/// `RegisterEventType` itself has a GraphQL route in front of it.
#[tracing::instrument(skip_all)]
/// Registration's write. `schedule_position` and `last_fired_at` belong to
/// the scheduler once a row exists - it advances them under `FOR UPDATE`
/// while registration reads them unlocked - so on conflict they come from
/// the row as it is now, not from `et` (a possibly stale read):
/// `last_fired_at` is never overwritten, and `schedule_position` only at
/// the opt-in moment, scheduling being newly enabled against the current
/// row (docs/architecture.md §76). Writing `et`'s copies back used to
/// rewind a position the scheduler had just advanced, re-firing the
/// occurrence - every instance re-registers every type at startup.
pub async fn upsert_event_type(pool: &Pool, et: &EventType) -> crate::error::Result<()> {
    check_blind_tag_mappings(pool, &et.bounded_context.name, &et.tag_mappings).await?;
    let schema = schema_ident(&et.bounded_context.name);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.event_types ({EVENT_TYPE_COLUMNS}) \
         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15) \
         ON CONFLICT (name) DO UPDATE SET \
            schema = EXCLUDED.schema, schema_version = EXCLUDED.schema_version, \
            tag_mappings = EXCLUDED.tag_mappings, owner_tag_key = EXCLUDED.owner_tag_key, \
            sensitive_fields = EXCLUDED.sensitive_fields, \
            external_creation_allowed = EXCLUDED.external_creation_allowed, \
            direct_creation_allowed = EXCLUDED.direct_creation_allowed, \
            system_triggered_allowed = EXCLUDED.system_triggered_allowed, \
            system_triggered_schedule = EXCLUDED.system_triggered_schedule, \
            missed_occurrence_policy = EXCLUDED.missed_occurrence_policy, \
            schedule_position = CASE \
                WHEN EXCLUDED.system_triggered_allowed \
                    AND NOT {schema}.event_types.system_triggered_allowed \
                THEN EXCLUDED.schedule_position \
                ELSE {schema}.event_types.schedule_position END, \
            event_read_allowed = EXCLUDED.event_read_allowed, \
            private_fields = EXCLUDED.private_fields"
    )))
    .bind(&et.name)
    .bind(&et.schema)
    .bind(et.schema_version)
    .bind(Json(&et.tag_mappings))
    .bind(&et.owner_tag_key)
    .bind(Json(&et.sensitive_fields))
    .bind(et.external_creation_allowed)
    .bind(et.direct_creation_allowed)
    .bind(et.system_triggered_allowed)
    .bind(&et.system_triggered_schedule)
    .bind(
        et.missed_occurrence_policy
            .map(missed_occurrence_policy_to_str),
    )
    .bind(et.schedule_position)
    .bind(et.last_fired_at)
    .bind(et.event_read_allowed)
    .bind(Json(&et.private_fields))
    .execute(pool)
    .await?;
    notify_registration_changed(pool).await;
    Ok(())
}

#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_event_type(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
) -> crate::error::Result<Option<EventType>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(None);
    };
    get_event_type_with_bc(pool, &bc, name).await
}

/// [`get_event_type`]'s own `bc`-in-hand sibling (issue #32,
/// round four - same precedent §60 already set for
/// `list_events_for_bounded_context_matching_tags_with_bc`): skips the
/// `get_bounded_context` call entirely for a caller who already has the
/// row - `list_events_for_bounded_context_matching_tags_with_bc`'s own
/// row-processing loop, one call per distinct event type in a delta
/// result, is exactly the caller this was added for - measured (a real
/// load test, not just reading the code) spending the majority of its
/// own wall-clock time re-fetching a `BoundedContext` (plus, transitively,
/// its own `created_by_role_id`'s `Role`) it never needed to ask for
/// again.
async fn get_event_type_with_bc(
    executor: impl sqlx::PgExecutor<'_>,
    bc: &BoundedContext,
    name: &str,
) -> crate::error::Result<Option<EventType>> {
    let schema = schema_ident(&bc.name);
    let row: Option<EventTypeRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {EVENT_TYPE_COLUMNS} FROM {schema}.event_types WHERE name = $1"
    )))
    .bind(name)
    .fetch_optional(executor)
    .await?;
    Ok(row.map(|r| r.into_domain(bc.clone())))
}

/// `get_event_type_with_bc`'s batched sibling - `get_command_types_by_names_with_bc`'s
/// own precedent, one `WHERE name = ANY($1)` round trip for a whole set
/// of names. `names` empty returns an empty map without touching
/// Postgres.
async fn get_event_types_by_names_with_bc(
    executor: impl sqlx::PgExecutor<'_>,
    bc: &BoundedContext,
    names: &[&str],
) -> crate::error::Result<std::collections::HashMap<String, EventType>> {
    if names.is_empty() {
        return Ok(std::collections::HashMap::new());
    }
    let schema = schema_ident(&bc.name);
    let rows: Vec<EventTypeRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {EVENT_TYPE_COLUMNS} FROM {schema}.event_types WHERE name = ANY($1)"
    )))
    .bind(names)
    .fetch_all(executor)
    .await?;
    Ok(rows
        .into_iter()
        .map(|row| (row.name.clone(), row.into_domain(bc.clone())))
        .collect())
}

/// Every `EventType` in `bounded_context` currently opted into
/// scheduling (`system_triggered_allowed = true`) - the background
/// scheduler's own discovery query each tick, and `TypeRegistration`'s
/// `scheduledEventTypes` GraphQL query (`@guarantee ScheduleStateIsShared`'s
/// own admin visibility) both read from this. Ordered by `name` for
/// stable output. `[]`, not an error, for an unknown `bounded_context` -
/// the same "nothing to show" treatment `list_projections_for_bounded_context`
/// gives it.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_scheduled_event_types(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<Vec<EventType>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(Vec::new());
    };
    let schema = schema_ident(bounded_context);
    let rows: Vec<EventTypeRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {EVENT_TYPE_COLUMNS} FROM {schema}.event_types \
         WHERE system_triggered_allowed = true ORDER BY name"
    )))
    .fetch_all(pool)
    .await?;
    Ok(rows
        .into_iter()
        .map(|r| r.into_domain(bc.clone()))
        .collect())
}

/// Every `EventType` registered in `bounded_context`, unfiltered -
/// `TypeRegistration`'s own `eventTypes` GraphQL query (issue
/// #6's "5a": the self-describing surface `skilj-tui`'s Commands/Query
/// Events tabs need to offer a real type picker instead of a name typed
/// by hand). Same shape as `list_scheduled_event_types` immediately
/// above, minus its `WHERE system_triggered_allowed = true` filter -
/// every type, not just the scheduled subset. Ordered by `name`, `[]`
/// for an unknown `bounded_context`, same reasoning as its sibling.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_event_types_for_bounded_context(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<Vec<EventType>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(Vec::new());
    };
    let schema = schema_ident(bounded_context);
    let rows: Vec<EventTypeRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {EVENT_TYPE_COLUMNS} FROM {schema}.event_types ORDER BY name"
    )))
    .fetch_all(pool)
    .await?;
    Ok(rows
        .into_iter()
        .map(|r| r.into_domain(bc.clone()))
        .collect())
}

/// `CommandType`'s own equivalent of `list_event_types_for_bounded_context`
/// immediately above - identical reasoning, `TypeRegistration`'s
/// `commandTypes` GraphQL query.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_command_types_for_bounded_context(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<Vec<CommandType>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(Vec::new());
    };
    let schema = schema_ident(bounded_context);
    let rows: Vec<CommandTypeRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {COMMAND_TYPE_COLUMNS} FROM {schema}.command_types ORDER BY name"
    )))
    .fetch_all(pool)
    .await?;
    Ok(rows
        .into_iter()
        .map(|r| r.into_domain(bc.clone()))
        .collect())
}

/// `rule CreateSystemEvent`'s own atomic whole, and `SequenceIsGaplessPerBoundedContext`'s
/// enforcement for a fired occurrence - locks `event_type_name`'s own
/// `event_types` row (`SELECT ... FOR UPDATE`), re-derives eligibility
/// against the now-locked, up-to-date `schedule_position`/`last_fired_at`
/// (another instance may have already advanced them since the caller's
/// own `list_scheduled_event_types` read - see `@guarantee
/// ScheduleStateIsShared`), and only then allocates a sequence number and
/// inserts - the same "peek, lock, re-check, single commit" shape
/// `submit_command` uses for `bounded_context.sequence`, adapted to one
/// `event_types` row instead. `event_dispatcher.scheduled_payload` is
/// resolved *before* the lock, deliberately: it's arbitrary caller code
/// (unlike `decide()`/`project()`, §1.1 never promised it's cheap or
/// I/O-free), so it must never run while this row's lock is held - that
/// would block every other writer to this event type for however long it
/// takes. `Ok(None)` when there is nothing to fire: the occurrence turned
/// out to be ineligible once the lock confirmed the fresh position (not
/// an error - exactly the race this locking exists to make harmless), or
/// this process's own `EventDispatcher` has no `scheduled_payload`
/// producer registered for the type at all (a genuine misconfiguration,
/// tolerated the same way `catch_up_bounded_context` tolerates an
/// unregistered projection dispatcher - logged and skipped by the
/// caller, not propagated as an `Err`).
#[allow(clippy::too_many_arguments)]
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn fire_system_event(
    pool: &Pool,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    event_dispatcher: &dyn crate::plugin::EventDispatcher,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    event_type_name: &str,
    occurrence_at: DateTime<Utc>,
    now: DateTime<Utc>,
    key_service: Option<&KeyService>,
) -> crate::error::Result<Option<Event>> {
    let Some(unlocked_event_type) = get_event_type(pool, bounded_context, event_type_name).await?
    else {
        return Ok(None);
    };
    let Some(payload) = event_dispatcher.scheduled_payload(bounded_context, event_type_name) else {
        return Ok(None);
    };

    let mut resolved = std::collections::HashMap::new();
    resolve_encryption_keys(
        pool,
        bounded_context,
        &unlocked_event_type.sensitive_fields,
        &payload,
        key_service,
        &mut resolved,
    )
    .await?;

    let schema = schema_ident(bounded_context);
    let mut tx = pool.begin().await?;
    let row: Option<EventTypeRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {EVENT_TYPE_COLUMNS} FROM {schema}.event_types WHERE name = $1 FOR UPDATE"
    )))
    .bind(event_type_name)
    .fetch_optional(&mut *tx)
    .await?;
    let Some(row) = row else {
        return Ok(None);
    };
    let event_type = row.into_domain(unlocked_event_type.bounded_context);

    // Allocated inside `tx`, after the lock above - if `create_system_event`
    // below rejects the occurrence, `tx` is dropped without committing
    // (the early `return Ok(None)`), rolling this allocation back too, so
    // no sequence number is ever burned on an occurrence that didn't
    // actually fire.
    let next_seq = next_sequence(&mut *tx, bounded_context).await?;
    let Some((event, new_position)) = crate::event_store::create_system_event(
        &event_type,
        occurrence_at,
        now,
        next_seq,
        || payload,
        |subject_key, subject_value| {
            let (key, _, data_key) = resolved
                .get(&(subject_key.to_string(), subject_value.to_string()))
                .expect(
                    "resolve_encryption_keys pre-resolved every subject sensitive_field_subjects \
                     named",
                );
            (key.clone(), data_key.clone())
        },
    ) else {
        return Ok(None);
    };

    let encryption_key_ids = encryption_key_ids(&event.encryption_keys, &resolved);
    // Fetched only now - after `next_sequence` above already took this
    // bounded context's own lock - see `insert_event_and_update_sync_projections_in_tx`'s
    // own doc comment on why that ordering, not "as early as possible", is
    // what keeps this read race-free against `promote_projection_rebuild`.
    let sync_projections = sync_projection_names(&mut tx, bounded_context).await?;
    insert_event_and_update_sync_projections_in_tx(
        &mut tx,
        &event,
        None,
        projection_dispatcher,
        &encryption_key_ids,
        &sync_projections,
    )
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.event_types SET schedule_position = $1, last_fired_at = $2 WHERE name = $3"
    )))
    .bind(new_position)
    .bind(new_position)
    .bind(event_type_name)
    .execute(&mut *tx)
    .await?;

    tx.commit().await?;
    broadcaster.publish(&event);
    record_event_appended(&event);
    notify_event_appended(pool, &event, broadcaster.instance_id()).await;
    event_cache.append(&event).await;

    Ok(Some(event))
}

/// `rule SkipMissedOccurrences`'s own atomic whole - locks the same
/// `event_types` row `fire_system_event` does, re-derives eligibility
/// against the locked, up-to-date `schedule_position` (a second instance
/// resuming alongside the first is exactly the harmless race this lock
/// makes a no-op - see `event_store::skip_missed_occurrences`'s own doc
/// comment), and persists the advanced position alone: unlike
/// `fire_system_event`, no event is produced and `last_fired_at` never
/// moves (`FiredOccurrenceIsAccountedFor` only ever relates it to
/// occurrences that actually fired). `Ok(None)` when the resume turns out
/// to be a no-op once the lock is held.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn skip_missed_occurrences_for_event_type(
    pool: &Pool,
    bounded_context: &str,
    event_type_name: &str,
    now: DateTime<Utc>,
) -> crate::error::Result<Option<DateTime<Utc>>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(None);
    };
    let schema = schema_ident(bounded_context);
    let mut tx = pool.begin().await?;
    let row: Option<EventTypeRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {EVENT_TYPE_COLUMNS} FROM {schema}.event_types WHERE name = $1 FOR UPDATE"
    )))
    .bind(event_type_name)
    .fetch_optional(&mut *tx)
    .await?;
    let Some(row) = row else {
        return Ok(None);
    };
    let event_type = row.into_domain(bc);

    let Some(new_position) = crate::event_store::skip_missed_occurrences(&event_type, now) else {
        return Ok(None);
    };

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.event_types SET schedule_position = $1 WHERE name = $2"
    )))
    .bind(new_position)
    .bind(event_type_name)
    .execute(&mut *tx)
    .await?;
    tx.commit().await?;

    Ok(Some(new_position))
}

// --- CommandType ---

#[derive(sqlx::FromRow)]
struct CommandTypeRow {
    name: String,
    schema: String,
    schema_version: i64,
    tag_mappings: Json<Vec<TagMapping>>,
    owner_tag_key: Option<String>,
    sensitive_fields: Json<Vec<SensitiveField>>,
    rest_trigger_allowed: bool,
    private_fields: Json<Vec<PrivateField>>,
}

impl CommandTypeRow {
    fn into_domain(self, bounded_context: BoundedContext) -> CommandType {
        CommandType {
            bounded_context,
            name: self.name,
            schema: self.schema,
            schema_version: self.schema_version,
            tag_mappings: self.tag_mappings.0,
            owner_tag_key: self.owner_tag_key,
            sensitive_fields: self.sensitive_fields.0,
            private_fields: self.private_fields.0,
            rest_trigger_allowed: self.rest_trigger_allowed,
        }
    }
}

const COMMAND_TYPE_COLUMNS: &str = "name, schema, schema_version, tag_mappings, owner_tag_key, \
    sensitive_fields, rest_trigger_allowed, private_fields";

/// See `upsert_event_type` above - same shape and reasoning.
#[tracing::instrument(skip_all)]
pub async fn upsert_command_type(pool: &Pool, ct: &CommandType) -> crate::error::Result<()> {
    check_blind_tag_mappings(pool, &ct.bounded_context.name, &ct.tag_mappings).await?;
    let schema = schema_ident(&ct.bounded_context.name);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.command_types ({COMMAND_TYPE_COLUMNS}) \
         VALUES ($1,$2,$3,$4,$5,$6,$7,$8) \
         ON CONFLICT (name) DO UPDATE SET \
            schema = EXCLUDED.schema, schema_version = EXCLUDED.schema_version, \
            tag_mappings = EXCLUDED.tag_mappings, owner_tag_key = EXCLUDED.owner_tag_key, \
            sensitive_fields = EXCLUDED.sensitive_fields, \
            rest_trigger_allowed = EXCLUDED.rest_trigger_allowed, \
            private_fields = EXCLUDED.private_fields"
    )))
    .bind(&ct.name)
    .bind(&ct.schema)
    .bind(ct.schema_version)
    .bind(Json(&ct.tag_mappings))
    .bind(&ct.owner_tag_key)
    .bind(Json(&ct.sensitive_fields))
    .bind(ct.rest_trigger_allowed)
    .bind(Json(&ct.private_fields))
    .execute(pool)
    .await?;
    notify_registration_changed(pool).await;
    Ok(())
}

// --- Command approvals (issue #98) ---

#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_command_approval_policy(
    pool: &Pool,
    bounded_context: &str,
    command_type_name: &str,
) -> crate::error::Result<Option<CommandApprovalPolicy>> {
    let schema = schema_ident(bounded_context);
    let row: Option<(Option<String>, Option<i64>, bool)> =
        sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "SELECT approver_role, deadline_seconds, allow_self_approval \
             FROM {schema}.command_approval_policies WHERE command_type_name = $1"
        )))
        .bind(command_type_name)
        .fetch_optional(pool)
        .await?;
    Ok(
        row.map(|(approver_role, deadline_seconds, allow_self_approval)| {
            CommandApprovalPolicy::new(approver_role, deadline_seconds)
                .allowing_self_approval(allow_self_approval)
        }),
    )
}

/// Writes `policy` for `command_type_name`. `None` removes the row, so the
/// type no longer requires approval - an explicit admin decision
/// (`registerCommandType` with `requiresApproval: false`), not something
/// startup reconciliation does: a deploy that stops declaring
/// `requires_approval()` leaves the stored policy in place, the same
/// "startup never removes a protection" stance as §102.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn set_command_approval_policy(
    pool: &Pool,
    bounded_context: &str,
    command_type_name: &str,
    policy: Option<&CommandApprovalPolicy>,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    match policy {
        Some(policy) => {
            if policy.deadline_seconds.is_some_and(|seconds| seconds <= 0) {
                return Err(crate::approvals::Error::InvalidApprovalPolicy.into());
            }
            if crate::db::get_command_type(pool, bounded_context, command_type_name)
                .await?
                .is_none()
            {
                return Err(crate::error::Error::row_not_found());
            }
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "INSERT INTO {schema}.command_approval_policies \
                 (command_type_name, approver_role, deadline_seconds, allow_self_approval) \
                 VALUES ($1, $2, $3, $4) \
                 ON CONFLICT (command_type_name) DO UPDATE SET \
                    approver_role = EXCLUDED.approver_role, \
                    deadline_seconds = EXCLUDED.deadline_seconds, \
                    allow_self_approval = EXCLUDED.allow_self_approval"
            )))
            .bind(command_type_name)
            .bind(policy.approver_role.as_deref())
            .bind(policy.deadline_seconds)
            .bind(policy.allow_self_approval)
            .execute(pool)
            .await?;
        }
        None => {
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "DELETE FROM {schema}.command_approval_policies WHERE command_type_name = $1"
            )))
            .bind(command_type_name)
            .execute(pool)
            .await?;
        }
    }
    Ok(())
}

/// Inserts a proposal for an already-authorised submission. The payload is
/// encrypted at rest with the command type's own sensitive fields, exactly
/// as a real command's is. With an idempotency key, a repeated pending
/// submission for the same `(command type, client, key)` returns the
/// original proposal rather than creating a second one.
#[allow(clippy::too_many_arguments)]
#[tracing::instrument(skip_all, fields(bounded_context = %command_type.bounded_context.name))]
pub async fn propose_command(
    pool: &Pool,
    command_type: &CommandType,
    authorised: &crate::event_store::CommandAuthorised,
    policy: &CommandApprovalPolicy,
    idempotency_key: Option<&str>,
    key_service: Option<&KeyService>,
    now: DateTime<Utc>,
) -> crate::error::Result<CommandProposal> {
    let bounded_context_name = &command_type.bounded_context.name;
    let schema = schema_ident(bounded_context_name);

    let mut resolved = std::collections::HashMap::new();
    resolve_encryption_keys(
        pool,
        bounded_context_name,
        &command_type.sensitive_fields,
        &authorised.payload,
        key_service,
        &mut resolved,
    )
    .await?;
    let protected = crate::event_store::protect_sensitive_fields(
        &command_type.sensitive_fields,
        &authorised.payload,
        |subject_key, subject_value| {
            let (_, _, data_key) = resolved
                .get(&(subject_key.to_string(), subject_value.to_string()))
                .expect("every subject protect_sensitive_fields asks for was resolved just above");
            (
                resolved
                    .get(&(subject_key.to_string(), subject_value.to_string()))
                    .expect("resolved just above")
                    .0
                    .clone(),
                data_key.clone(),
            )
        },
    );

    let id = crate::shared::generate_token_id();
    let expires_at = policy
        .deadline_seconds
        .map(|seconds| now + chrono::Duration::seconds(seconds));
    let inserted: Option<(String,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.command_proposals \
         (id, command_type_name, payload, metadata_version, metadata_client_id, \
          metadata_created_at, metadata_correlation_id, metadata_causation_id, status, \
          idempotency_key, created_at, expires_at) \
         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,'pending',$9,$6,$10) \
         ON CONFLICT (command_type_name, metadata_client_id, idempotency_key) \
             WHERE status = 'pending' AND idempotency_key IS NOT NULL \
         DO NOTHING \
         RETURNING id"
    )))
    .bind(&id)
    .bind(&command_type.name)
    .bind(&protected.payload)
    .bind(1_i64)
    .bind(&authorised.client_id)
    .bind(now)
    .bind(&authorised.correlation_id)
    .bind(&authorised.causation_id)
    .bind(idempotency_key)
    .bind(expires_at)
    .fetch_optional(pool)
    .await?;

    let proposal_id = match inserted {
        Some((id,)) => id,
        None => {
            let key = idempotency_key
                .ok_or_else(|| crate::error::Error::Database(sqlx::Error::RowNotFound))?;
            let (id,): (String,) = sqlx::query_as(sqlx::AssertSqlSafe(format!(
                "SELECT id FROM {schema}.command_proposals \
                 WHERE command_type_name = $1 AND metadata_client_id = $2 \
                   AND idempotency_key = $3 AND status = 'pending'"
            )))
            .bind(&command_type.name)
            .bind(&authorised.client_id)
            .bind(key)
            .fetch_one(pool)
            .await?;
            id
        }
    };
    get_command_proposal(pool, bounded_context_name, &proposal_id)
        .await?
        .ok_or_else(|| crate::approvals::Error::ProposalNotFound { id: proposal_id }.into())
}

/// Marks pending proposals whose deadline has passed as expired, then
/// returns the ones matching `status`/`command_type_name`. The lazy update
/// keeps listing and approving consistent without a background sweeper.
pub async fn expire_command_proposals(
    pool: &Pool,
    bounded_context: &str,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.command_proposals SET status = 'expired' \
         WHERE status = 'pending' AND expires_at IS NOT NULL AND expires_at <= $1"
    )))
    .bind(now)
    .execute(pool)
    .await?;
    Ok(())
}

/// `scope` is the reading admin's own `RoleAccessMapping.scope`: a
/// proposal outside it is left out, as `fetch_commands` leaves out a
/// command (`approvals::proposal_owner_scope_satisfied`).
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_command_proposals(
    pool: &Pool,
    bounded_context: &str,
    status: Option<CommandProposalStatus>,
    command_type_name: Option<&str>,
    scope: Option<&str>,
    now: DateTime<Utc>,
) -> crate::error::Result<Vec<CommandProposal>> {
    expire_command_proposals(pool, bounded_context, now).await?;
    let schema = schema_ident(bounded_context);
    let rows: Vec<ProposalRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {PROPOSAL_COLUMNS} FROM {schema}.command_proposals \
         WHERE ($1::text IS NULL OR status = $1) \
           AND ($2::text IS NULL OR command_type_name = $2) \
         ORDER BY created_at, id"
    )))
    .bind(status.map(CommandProposalStatus::as_str))
    .bind(command_type_name)
    .fetch_all(pool)
    .await?;
    let bc = require_bounded_context(pool, bounded_context).await?;
    let mut scope_filter = ProposalScopeFilter::default();
    let mut visible = Vec::new();
    for proposal in rows.into_iter().map(|row| row.into_domain(bc.clone())) {
        if scope_filter
            .in_scope(pool, bounded_context, &proposal, scope)
            .await?
        {
            visible.push(proposal);
        }
    }
    Ok(visible)
}

/// `commandProposals(boundedContext:, after:)`'s own read: at most `limit`
/// proposals in [`list_command_proposals`]'s order (oldest first, the
/// order an approval queue is worked in), strictly after `after`. Like
/// `parkedDeliveries` (docs/architecture.md §86), proposals outside
/// `scope` are skipped and the page is filled from as many stored pages
/// as that takes, so a page shorter than `limit` means the end.
#[allow(clippy::too_many_arguments)]
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_command_proposals_page(
    pool: &Pool,
    bounded_context: &str,
    status: Option<CommandProposalStatus>,
    command_type_name: Option<&str>,
    scope: Option<&str>,
    after: Option<&CommandProposalCursor>,
    limit: i64,
    now: DateTime<Utc>,
) -> crate::error::Result<Vec<CommandProposal>> {
    expire_command_proposals(pool, bounded_context, now).await?;
    let schema = schema_ident(bounded_context);
    let bc = require_bounded_context(pool, bounded_context).await?;
    let mut scope_filter = ProposalScopeFilter::default();
    let mut visible = Vec::new();
    let mut after = after.cloned();
    loop {
        let rows: Vec<ProposalRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "SELECT {PROPOSAL_COLUMNS} FROM {schema}.command_proposals \
             WHERE ($1::text IS NULL OR status = $1) \
               AND ($2::text IS NULL OR command_type_name = $2) \
               AND ($3::timestamptz IS NULL OR (created_at, id) > ($3, $4)) \
             ORDER BY created_at, id LIMIT $5"
        )))
        .bind(status.map(CommandProposalStatus::as_str))
        .bind(command_type_name)
        .bind(after.as_ref().map(|c| c.created_at))
        .bind(after.as_ref().map(|c| c.id.clone()))
        .bind(limit)
        .fetch_all(pool)
        .await?;
        let exhausted = (rows.len() as i64) < limit;
        for proposal in rows.into_iter().map(|row| row.into_domain(bc.clone())) {
            after = Some(CommandProposalCursor::of(&proposal));
            if scope_filter
                .in_scope(pool, bounded_context, &proposal, scope)
                .await?
            {
                visible.push(proposal);
                if visible.len() as i64 == limit {
                    return Ok(visible);
                }
            }
        }
        if exhausted {
            return Ok(visible);
        }
    }
}

/// A position in [`list_command_proposals_page`]'s order. Like
/// [`ParkedDeliveryCursor`] it carries the position rather than naming a
/// row, so approving or rejecting the last proposal of a page - and with
/// a `status` filter, that moves it out of the listing - doesn't
/// invalidate the next page.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CommandProposalCursor {
    pub created_at: DateTime<Utc>,
    pub id: String,
}

impl CommandProposalCursor {
    pub fn of(proposal: &CommandProposal) -> Self {
        Self {
            created_at: proposal.created_at,
            id: proposal.id.clone(),
        }
    }

    /// `{microseconds since the epoch}:{id}` - opaque to clients.
    pub fn encode(&self) -> String {
        format!("{}:{}", self.created_at.timestamp_micros(), self.id)
    }

    pub fn decode(cursor: &str) -> Option<Self> {
        let (micros, id) = cursor.split_once(':')?;
        Some(Self {
            created_at: DateTime::from_timestamp_micros(micros.parse().ok()?)?,
            id: id.to_string(),
        })
    }
}

/// Whether a proposal is inside an admin's owner scope, looking each
/// command type up once per listing.
#[derive(Default)]
struct ProposalScopeFilter {
    command_types: std::collections::HashMap<String, Option<CommandType>>,
}

impl ProposalScopeFilter {
    async fn in_scope(
        &mut self,
        pool: &Pool,
        bounded_context: &str,
        proposal: &CommandProposal,
        scope: Option<&str>,
    ) -> crate::error::Result<bool> {
        if scope.is_none() {
            return Ok(true);
        }
        if !self.command_types.contains_key(&proposal.command_type_name) {
            let command_type =
                get_command_type(pool, bounded_context, &proposal.command_type_name).await?;
            self.command_types
                .insert(proposal.command_type_name.clone(), command_type);
        }
        // A type that no longer exists has no owner dimension left to
        // prove the proposal in scope: left out, failing closed.
        Ok(self.command_types[&proposal.command_type_name]
            .as_ref()
            .is_some_and(|command_type| {
                crate::approvals::proposal_owner_scope_satisfied(command_type, proposal, scope)
            }))
    }
}

const PROPOSAL_COLUMNS: &str = "id, command_type_name, payload, metadata_version, \
    metadata_client_id, metadata_created_at, metadata_correlation_id, metadata_causation_id, \
    status, idempotency_key, created_at, expires_at, decided_at, decided_by_role_id, \
    rejection_reason, rejection_kind, command_external_id";

#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_command_proposal(
    pool: &Pool,
    bounded_context: &str,
    id: &str,
) -> crate::error::Result<Option<CommandProposal>> {
    let schema = schema_ident(bounded_context);
    let row: Option<ProposalRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT id, command_type_name, payload, metadata_version, metadata_client_id, \
                metadata_created_at, metadata_correlation_id, metadata_causation_id, status, \
                idempotency_key, created_at, expires_at, decided_at, decided_by_role_id, \
                rejection_reason, rejection_kind, command_external_id \
         FROM {schema}.command_proposals WHERE id = $1"
    )))
    .bind(id)
    .fetch_optional(pool)
    .await?;
    let Some(row) = row else {
        return Ok(None);
    };
    let bc = require_bounded_context(pool, bounded_context).await?;
    Ok(Some(row.into_domain(bc)))
}

#[derive(sqlx::FromRow)]
struct ProposalRow {
    id: String,
    command_type_name: String,
    payload: String,
    metadata_version: i64,
    metadata_client_id: String,
    metadata_created_at: DateTime<Utc>,
    metadata_correlation_id: Option<String>,
    metadata_causation_id: Option<String>,
    status: String,
    idempotency_key: Option<String>,
    created_at: DateTime<Utc>,
    expires_at: Option<DateTime<Utc>>,
    decided_at: Option<DateTime<Utc>>,
    decided_by_role_id: Option<String>,
    rejection_reason: Option<String>,
    rejection_kind: Option<String>,
    command_external_id: Option<String>,
}

impl ProposalRow {
    fn into_domain(self, bounded_context: BoundedContext) -> CommandProposal {
        CommandProposal {
            id: self.id,
            bounded_context,
            command_type_name: self.command_type_name,
            payload: self.payload,
            metadata: Metadata {
                r#type: "Command".to_string(),
                version: self.metadata_version,
                client_id: self.metadata_client_id,
                created_at: self.metadata_created_at,
                correlation_id: self.metadata_correlation_id,
                causation_id: self.metadata_causation_id,
            },
            status: CommandProposalStatus::from_db(&self.status)
                .expect("command_proposals.status has a CHECK constraint"),
            idempotency_key: self.idempotency_key,
            created_at: self.created_at,
            expires_at: self.expires_at,
            decided_at: self.decided_at,
            decided_by_role_id: self.decided_by_role_id,
            rejection_reason: self.rejection_reason,
            rejection_kind: self.rejection_kind,
            command_id: self.command_external_id,
        }
    }
}

/// How long an `approving` claim may sit before another approver may take
/// it over. A claim normally lives for one `decide_and_submit_command`
/// call; one older than this was left behind by a crash, or by a failure
/// to record the outcome after the command committed. Taking it over is
/// safe even if the original approval is somehow still running: both run
/// under the same idempotency key ([`approval_idempotency_key`]), so the
/// second one is deduplicated under the bounded context's lock.
pub const APPROVAL_CLAIM_STALE_AFTER: chrono::Duration = chrono::Duration::minutes(10);

/// The idempotency key an approval submits under: the proposer's own key,
/// or a reserved one derived from the proposal id.
pub fn approval_idempotency_key(proposal: &CommandProposal) -> String {
    proposal.idempotency_key.clone().unwrap_or_else(|| {
        format!(
            "{}{}",
            crate::event_store::RESERVED_APPROVAL_IDEMPOTENCY_KEY_PREFIX,
            proposal.id
        )
    })
}

/// Claims a proposal for `approver`: a `pending` one that has not expired,
/// or an `approving` one whose claim is older than
/// [`APPROVAL_CLAIM_STALE_AFTER`] (see there). The conditional `UPDATE` is
/// the lock: exactly one concurrent approver wins the claim.
///
/// If the proposal's command type no longer has an approval policy (it was
/// removed after the proposal was made), the proposal is still decidable by
/// any active admin of the bounded context, rather than stranded `pending`
/// with nobody able to approve or reject it.
pub async fn claim_command_proposal(
    pool: &Pool,
    bounded_context: &str,
    id: &str,
    approver: &RoleAccessMapping,
    decision: crate::approvals::ProposalDecision,
    now: DateTime<Utc>,
) -> crate::error::Result<CommandProposal> {
    if approver.bounded_context.name != bounded_context {
        return Err(crate::access_control::Error::GrantBoundedContextMismatch.into());
    }
    expire_command_proposals(pool, bounded_context, now).await?;
    let not_found = || crate::approvals::Error::ProposalNotFound { id: id.to_string() };
    let proposal = get_command_proposal(pool, bounded_context, id)
        .await?
        .ok_or_else(not_found)?;
    // Outside the approver's owner scope reads as not found, the same
    // answer a missing id gets, so the scope is no existence oracle.
    let in_scope = approver.scope.is_none()
        || get_command_type(pool, bounded_context, &proposal.command_type_name)
            .await?
            .is_some_and(|command_type| {
                crate::approvals::proposal_owner_scope_satisfied(
                    &command_type,
                    &proposal,
                    approver.scope.as_deref(),
                )
            });
    if !in_scope {
        return Err(not_found().into());
    }
    let policy = get_command_approval_policy(pool, bounded_context, &proposal.command_type_name)
        .await?
        .unwrap_or_else(|| CommandApprovalPolicy::new(None, None));
    crate::approvals::check_approver(&policy, approver)?;
    if decision == crate::approvals::ProposalDecision::Approve {
        // Resolve the proposer to a Role, if it is one: a GraphQL
        // submission stamps `access_mapping.role.id`, while a REST token
        // or an internal path (deadline, route) stamps an id no Role
        // carries - `None`, so any admin may approve those. Matching on
        // `external_subject` (the human) rather than the Role id closes
        // the two-Roles-one-human gap; a proposer Role since revoked
        // still carries its subject, so it still refuses.
        let proposer_role = get_role(pool, &proposal.metadata.client_id).await?;
        crate::approvals::check_self_approval(&policy, proposer_role.as_ref(), approver)?;
    }
    let stale_cutoff = now - APPROVAL_CLAIM_STALE_AFTER;
    match proposal.status {
        CommandProposalStatus::Pending if proposal.is_expired_at(now) => {
            return Err(crate::approvals::Error::ProposalExpired.into())
        }
        CommandProposalStatus::Pending => {}
        CommandProposalStatus::Approving
            if proposal
                .decided_at
                .is_some_and(|claimed_at| claimed_at <= stale_cutoff) =>
        {
            tracing::warn!(
                bounded_context,
                proposal_id = id,
                "taking over a stale approval claim - a previous approval crashed or \
                 failed to record its outcome"
            );
        }
        CommandProposalStatus::Expired => {
            return Err(crate::approvals::Error::ProposalExpired.into())
        }
        status => {
            return Err(crate::approvals::Error::ProposalNotPending {
                status: status.as_str(),
            }
            .into())
        }
    }

    let schema = schema_ident(bounded_context);
    let claimed: Option<(String,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.command_proposals \
         SET status = 'approving', decided_at = $2, decided_by_role_id = $3 \
         WHERE id = $1 AND ( \
             (status = 'pending' AND (expires_at IS NULL OR expires_at > $2)) \
             OR (status = 'approving' AND decided_at <= $4)) \
         RETURNING id"
    )))
    .bind(id)
    .bind(now)
    .bind(&approver.role.id)
    .bind(stale_cutoff)
    .fetch_optional(pool)
    .await?;
    if claimed.is_none() {
        return Err(crate::approvals::Error::ProposalNotPending { status: "claimed" }.into());
    }
    get_command_proposal(pool, bounded_context, id)
        .await?
        .ok_or_else(|| crate::approvals::Error::ProposalNotFound { id: id.to_string() }.into())
}

/// After [`claim_command_proposal`] took over a stale claim, settles what
/// the earlier approval already did, before anything new is decided:
/// - its command committed (the approval's idempotency key is recorded):
///   the proposal is finished `Approved`, and `Ok(true)` is returned;
/// - it did not, but the proposal's deadline has since passed: the
///   proposal is finished `Expired`, and `ProposalExpired` is returned;
/// - otherwise `Ok(false)`: nothing happened yet, decide as normal.
///
/// For a fresh `pending` claim this is always `Ok(false)`: no command can
/// exist under the key yet, and an expired proposal cannot be claimed.
async fn settle_reclaimed_proposal(
    pool: &Pool,
    bounded_context: &str,
    proposal: &CommandProposal,
    now: DateTime<Utc>,
) -> crate::error::Result<bool> {
    if idempotency_key_already_used(
        pool,
        bounded_context,
        &proposal.command_type_name,
        &proposal.metadata.client_id,
        &approval_idempotency_key(proposal),
    )
    .await?
    {
        finish_command_proposal(
            pool,
            bounded_context,
            &proposal.id,
            CommandProposalStatus::Approved,
            None,
            None,
            None,
            now,
        )
        .await?;
        return Ok(true);
    }
    if proposal.is_expired_at(now) {
        finish_command_proposal(
            pool,
            bounded_context,
            &proposal.id,
            CommandProposalStatus::Expired,
            None,
            None,
            None,
            now,
        )
        .await?;
        return Err(crate::approvals::Error::ProposalExpired.into());
    }
    Ok(false)
}

/// The payload approval hands `decide()`: the stored ciphertext revealed.
pub async fn reveal_command_proposal_payload(
    pool: &Pool,
    command_type: &CommandType,
    proposal: &CommandProposal,
    key_service: Option<&KeyService>,
) -> crate::error::Result<String> {
    let subjects = crate::event_store::sensitive_field_subjects(
        &command_type.sensitive_fields,
        &proposal.payload,
    );
    if subjects.is_empty() {
        return Ok(proposal.payload.clone());
    }
    let key_service = key_service.ok_or(encryption::Error::MasterKeyNotConfigured)?;
    let mut keys: std::collections::HashMap<(String, String), Option<DataKey>> =
        std::collections::HashMap::new();
    for (subject_key, subject_value) in subjects {
        let key = get_active_data_key(
            pool,
            &proposal.bounded_context.name,
            &subject_key,
            &subject_value,
            key_service,
        )
        .await?;
        keys.insert((subject_key, subject_value), key);
    }
    crate::event_store::reveal_sensitive_fields(
        &command_type.sensitive_fields,
        &proposal.payload,
        |subject_key, subject_value| {
            keys.get(&(subject_key.to_string(), subject_value.to_string()))
                .cloned()
                .flatten()
        },
    )
}

#[allow(clippy::too_many_arguments)]
pub async fn finish_command_proposal(
    pool: &Pool,
    bounded_context: &str,
    id: &str,
    status: CommandProposalStatus,
    rejection_reason: Option<&str>,
    rejection_kind: Option<&str>,
    command_external_id: Option<&str>,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.command_proposals SET status = $2, decided_at = $3, \
            rejection_reason = $4, rejection_kind = $5, command_external_id = $6 \
         WHERE id = $1 AND status = 'approving'"
    )))
    .bind(id)
    .bind(status.as_str())
    .bind(now)
    .bind(rejection_reason)
    .bind(rejection_kind)
    .bind(command_external_id)
    .execute(pool)
    .await?;
    Ok(())
}

pub async fn release_command_proposal(
    pool: &Pool,
    bounded_context: &str,
    id: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.command_proposals \
         SET status = 'pending', decided_at = NULL, decided_by_role_id = NULL \
         WHERE id = $1 AND status = 'approving'"
    )))
    .bind(id)
    .execute(pool)
    .await?;
    Ok(())
}

/// Whether a subject `proposal`'s sensitive fields are encrypted for had
/// a key destroyed at or after the proposal was made. Making it provisioned
/// (or reused) that subject's active key, and a subject has at most one
/// active key, so any destruction since means the key the payload was
/// encrypted under is gone - even if a later submission has provisioned a
/// fresh one (docs/architecture.md §221).
async fn proposal_subject_forgotten(
    pool: &Pool,
    command_type: &CommandType,
    proposal: &CommandProposal,
) -> crate::error::Result<bool> {
    let schema = schema_ident(&proposal.bounded_context.name);
    for (subject_key, subject_value) in crate::event_store::sensitive_field_subjects(
        &command_type.sensitive_fields,
        &proposal.payload,
    ) {
        let destroyed: bool = sqlx::query_scalar(sqlx::AssertSqlSafe(format!(
            "SELECT EXISTS (SELECT 1 FROM {schema}.encryption_keys \
             WHERE subject_key = $1 AND subject_value = $2 \
               AND status = 'destroyed' AND destroyed_at >= $3)"
        )))
        .bind(&subject_key)
        .bind(&subject_value)
        .bind(proposal.created_at)
        .fetch_one(pool)
        .await?;
        if destroyed {
            return Ok(true);
        }
    }
    Ok(false)
}

/// `forgetSubject`'s proposal half (docs/architecture.md §221): every
/// `pending` proposal in `bounded_context` whose sensitive fields are
/// encrypted for the subject is finished as `forgotten`. Once the key is
/// destroyed its payload can never be revealed, so it could never be
/// approved; left alone it would sit in the queue until someone rejected
/// it, or failed to approve it. Called before the key goes, like
/// [`forget_subject_in_deadlines`]. A proposal names the subject when its
/// payload does through its command type's sensitive fields
/// (`sensitive_field_subjects`) - the subject field itself is stored in
/// the clear - or, should that type be gone, when the subject value
/// appears anywhere in it. The payload is kept, encrypted as a command's
/// is, so the proposal renders as a command of a forgotten subject does.
/// An `approving` claim is past stopping and left alone, as a `firing`
/// deadline is: if it already revealed the payload, its submission
/// provisions a fresh key. Returns how many proposals were forgotten.
pub async fn forget_subject_in_command_proposals(
    pool: &Pool,
    bounded_context: &str,
    subject_key: &str,
    subject_value: &str,
    now: DateTime<Utc>,
) -> crate::error::Result<u64> {
    const PAGE: i64 = 1000;
    let schema = schema_ident(bounded_context);
    let mut sensitive_fields: std::collections::HashMap<String, Option<Vec<SensitiveField>>> =
        std::collections::HashMap::new();
    let mut forgotten = 0;
    let mut after = String::new();
    loop {
        let rows: Vec<(String, String, String)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "SELECT id, command_type_name, payload FROM {schema}.command_proposals \
             WHERE status = 'pending' AND id > $1 ORDER BY id LIMIT $2"
        )))
        .bind(&after)
        .bind(PAGE)
        .fetch_all(pool)
        .await?;
        let Some((last_id, _, _)) = rows.last() else {
            break;
        };
        after = last_id.clone();
        for (id, command_type, payload) in &rows {
            if !sensitive_fields.contains_key(command_type) {
                let fields = get_command_type(pool, bounded_context, command_type)
                    .await?
                    .map(|ct| ct.sensitive_fields);
                sensitive_fields.insert(command_type.clone(), fields);
            }
            let parsed = serde_json::from_str::<serde_json::Value>(payload).ok();
            let names_subject = match (&sensitive_fields[command_type], &parsed) {
                (Some(fields), Some(_)) => {
                    crate::event_store::sensitive_field_subjects(fields, payload)
                        .iter()
                        .any(|(key, value)| key == subject_key && value == subject_value)
                }
                (_, Some(json)) => json_mentions(json, subject_value),
                (_, None) => payload.contains(subject_value),
            };
            if names_subject {
                forgotten += sqlx::query(sqlx::AssertSqlSafe(format!(
                    "UPDATE {schema}.command_proposals SET status = 'forgotten', decided_at = $1 \
                     WHERE id = $2 AND status = 'pending'"
                )))
                .bind(now)
                .bind(id)
                .execute(pool)
                .await?
                .rows_affected();
            }
        }
        if (rows.len() as i64) < PAGE {
            break;
        }
    }
    Ok(forgotten)
}

pub async fn reject_command_proposal(
    pool: &Pool,
    bounded_context: &str,
    id: &str,
    approver: &RoleAccessMapping,
    reason: Option<&str>,
    now: DateTime<Utc>,
) -> crate::error::Result<CommandProposal> {
    let proposal = claim_command_proposal(
        pool,
        bounded_context,
        id,
        approver,
        crate::approvals::ProposalDecision::Reject,
        now,
    )
    .await?;
    // A taken-over stale claim whose command already committed is approved,
    // not rejectable - rejecting it would contradict the command that exists.
    if settle_reclaimed_proposal(pool, bounded_context, &proposal, now).await? {
        return Err(crate::approvals::Error::ProposalNotPending { status: "approved" }.into());
    }
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.command_proposals SET status = 'rejected', rejection_reason = $2, \
            decided_at = $3 WHERE id = $1 AND status = 'approving'"
    )))
    .bind(id)
    .bind(reason)
    .bind(now)
    .execute(pool)
    .await?;
    get_command_proposal(pool, bounded_context, id)
        .await?
        .ok_or_else(|| crate::approvals::Error::ProposalNotFound { id: id.to_string() }.into())
}

/// The approval gate for skilj's own internal submissions - a fired
/// deadline (`fire_due_deadlines`) and a cross-context route
/// (`catch_up_cross_context_route_locked`). Both call
/// `decide_and_submit_command` directly rather than going through REST or
/// GraphQL, so without this an agent able to cause the *source* event could
/// get an approval-required command executed with no approver at all.
///
/// Returns `true` when `command_type` requires approval, and the occurrence
/// is then handled by this call: a proposal is created under the internal
/// caller's own `client_id` and reserved `idempotency_key` (or, after a
/// crash between a prior call and the caller's cursor/resolution update,
/// the existing pending proposal is found again by that key; or, if that
/// proposal was already approved, nothing is proposed twice). Returns
/// `false` when the type has no approval policy, and the caller submits as
/// before.
///
/// A deadline's `DeadlineContext` is not carried onto the proposal: the
/// approved command runs at approval time, so its `decide_with` sees no
/// deadline - an approver deciding late is the approver's call.
#[allow(clippy::too_many_arguments)]
pub async fn propose_if_approval_required(
    pool: &Pool,
    command_type: &CommandType,
    payload: &str,
    client_id: &str,
    correlation_id: Option<&str>,
    causation_id: Option<&str>,
    idempotency_key: &str,
    key_service: Option<&KeyService>,
    now: DateTime<Utc>,
) -> crate::error::Result<bool> {
    let bounded_context = &command_type.bounded_context.name;
    let Some(policy) =
        get_command_approval_policy(pool, bounded_context, &command_type.name).await?
    else {
        return Ok(false);
    };
    if idempotency_key_already_used(
        pool,
        bounded_context,
        &command_type.name,
        client_id,
        idempotency_key,
    )
    .await?
    {
        return Ok(true);
    }
    let authorised = crate::event_store::CommandAuthorised {
        command_type: command_type.clone(),
        payload: payload.to_string(),
        client_id: client_id.to_string(),
        correlation_id: correlation_id.map(str::to_string),
        causation_id: causation_id.map(str::to_string),
    };
    let proposal = propose_command(
        pool,
        command_type,
        &authorised,
        &policy,
        Some(idempotency_key),
        key_service,
        now,
    )
    .await?;
    tracing::info!(
        bounded_context = %bounded_context,
        command_type = %command_type.name,
        client_id,
        proposal_id = %proposal.id,
        "internal submission of an approval-required command became a proposal"
    );
    Ok(true)
}

/// What approving a proposal did: the proposal after its final update,
/// and the ordinary submission outcome (`Accepted`, `Rejected` by
/// `decide()`, or `Deduplicated` on a retry after a crash).
pub struct CommandApprovalOutcome {
    pub proposal: CommandProposal,
    pub outcome: SubmitCommandOutcome,
}

/// Runs the ordinary submission pipeline for a claimed proposal, with the
/// original submitter's own `client_id` and correlation/causation ids.
/// On an `Err` the claim is released back to `pending`, so a transient
/// failure is retryable; on a business rejection the proposal is recorded
/// rejected with `decide()`'s own reason.
#[allow(clippy::too_many_arguments)]
pub async fn approve_command_proposal(
    pool: &Pool,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    snapshot_dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    id: &str,
    approver: &RoleAccessMapping,
    key_service: Option<&KeyService>,
    now: DateTime<Utc>,
) -> crate::error::Result<CommandApprovalOutcome> {
    let proposal = claim_command_proposal(
        pool,
        bounded_context,
        id,
        approver,
        crate::approvals::ProposalDecision::Approve,
        now,
    )
    .await?;
    // A taken-over stale claim may already have produced its command; if so
    // it is marked approved here and the submission below deduplicates.
    settle_reclaimed_proposal(pool, bounded_context, &proposal, now).await?;
    let command_type =
        match get_command_type(pool, bounded_context, &proposal.command_type_name).await? {
            Some(command_type) => command_type,
            None => {
                release_command_proposal(pool, bounded_context, id).await?;
                return Err(crate::error::Error::row_not_found());
            }
        };
    let payload = match reveal_command_proposal_payload(pool, &command_type, &proposal, key_service)
        .await
    {
        Ok(payload) => payload,
        Err(e) => {
            // docs/architecture.md §221: a subject forgotten without
            // `forget_subject_in_command_proposals` (an older instance, or a
            // direct `destroy_encryption_key`) - the payload is gone for
            // good, so the proposal is finished rather than released to
            // fail again. Anything else, the check failing included,
            // releases the claim, so the approval stays retryable.
            match proposal_subject_forgotten(pool, &command_type, &proposal).await {
                Ok(true) => {
                    tracing::info!(
                        bounded_context,
                        proposal_id = id,
                        error = %e,
                        "a subject this proposal names was forgotten - recording it as forgotten"
                    );
                    finish_command_proposal(
                        pool,
                        bounded_context,
                        id,
                        CommandProposalStatus::Forgotten,
                        None,
                        None,
                        None,
                        now,
                    )
                    .await?;
                    return Err(crate::approvals::Error::ProposalSubjectForgotten.into());
                }
                Ok(false) => {}
                Err(check) => tracing::warn!(
                    bounded_context,
                    proposal_id = id,
                    error = %check,
                    "could not check whether a subject this proposal names was forgotten"
                ),
            }
            release_command_proposal(pool, bounded_context, id).await?;
            return Err(e);
        }
    };

    let idempotency_key = approval_idempotency_key(&proposal);
    let outcome = decide_and_submit_command(
        pool,
        dispatcher,
        projection_dispatcher,
        snapshot_dispatcher,
        broadcaster,
        event_cache,
        &command_type,
        &payload,
        &proposal.metadata.client_id,
        proposal.metadata.correlation_id.as_deref(),
        proposal.metadata.causation_id.as_deref(),
        key_service,
        now,
        Some(&idempotency_key),
        None,
    )
    .await;

    let outcome = match outcome {
        Ok(outcome) => outcome,
        Err(e) => {
            release_command_proposal(pool, bounded_context, id).await?;
            return Err(e);
        }
    };

    match &outcome {
        SubmitCommandOutcome::Accepted { command, .. } => {
            finish_command_proposal(
                pool,
                bounded_context,
                id,
                CommandProposalStatus::Approved,
                None,
                None,
                Some(command.id.as_str()),
                now,
            )
            .await?;
        }
        SubmitCommandOutcome::Rejected { reason, kind, .. } => {
            finish_command_proposal(
                pool,
                bounded_context,
                id,
                CommandProposalStatus::Rejected,
                Some(reason),
                Some(kind),
                None,
                now,
            )
            .await?;
        }
        SubmitCommandOutcome::Deduplicated { .. } => {
            finish_command_proposal(
                pool,
                bounded_context,
                id,
                CommandProposalStatus::Approved,
                None,
                None,
                None,
                now,
            )
            .await?;
        }
    }

    Ok(CommandApprovalOutcome {
        proposal: get_command_proposal(pool, bounded_context, id)
            .await?
            .ok_or_else(|| crate::approvals::Error::ProposalNotFound { id: id.to_string() })?,
        outcome,
    })
}

#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_command_type(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
) -> crate::error::Result<Option<CommandType>> {
    use sqlx::FromRow;
    // The command type with its bounded context, hydrated, in one
    // statement (docs/architecture.md §196, §199): every command resolves
    // its type this way before the lock.
    let schema = schema_ident(bounded_context);
    let row = sqlx::query(sqlx::AssertSqlSafe(format!(
        "SELECT {}, {} FROM {HYDRATED_BOUNDED_CONTEXT_FROM} \
         JOIN {schema}.command_types ct ON ct.name = $2 WHERE bc.name = $1",
        hydrated_bounded_context_columns(),
        COMMAND_TYPE_COLUMNS
            .split(", ")
            .map(|column| format!("ct.{}", column.trim()))
            .collect::<Vec<_>>()
            .join(", ")
    )))
    .bind(bounded_context)
    .bind(name)
    .fetch_optional(pool)
    .await;
    let row = match row {
        Ok(Some(row)) => row,
        Ok(None) => return Ok(None),
        // The schema is gone with a hard-deleted bounded context, which
        // reads as no such command type, as it did when the bounded
        // context's row was read first.
        Err(sqlx::Error::Database(e)) if e.code().as_deref() == Some("42P01") => return Ok(None),
        Err(e) => return Err(e.into()),
    };
    let bc = hydrated_bounded_context(&row)?;
    Ok(Some(CommandTypeRow::from_row(&row)?.into_domain(bc)))
}

// --- EncryptionKey ---

fn encryption_key_status_from_str(s: &str) -> EncryptionKeyStatus {
    match s {
        "destroyed" => EncryptionKeyStatus::Destroyed,
        _ => EncryptionKeyStatus::Active,
    }
}

#[derive(sqlx::FromRow)]
struct EncryptionKeyRow {
    id: i64,
    subject_key: String,
    subject_value: String,
    status: String,
    created_at: DateTime<Utc>,
    destroyed_at: Option<DateTime<Utc>>,
    wrapped_key: Option<Vec<u8>>,
    wrap_nonce: Option<Vec<u8>>,
    /// The key provider that wrapped it (docs/architecture.md §230),
    /// `NULL` for one wrapped by the legacy raw master key.
    key_provider: Option<String>,
    /// The master key version it is wrapped under, `NULL` for a legacy one.
    master_key_version: Option<i32>,
    /// When a rewrap found no configured key unwraps it.
    unreadable_since: Option<DateTime<Utc>>,
}

impl EncryptionKeyRow {
    fn to_domain(&self, bounded_context: BoundedContext) -> EncryptionKey {
        EncryptionKey {
            bounded_context,
            subject_key: self.subject_key.clone(),
            subject_value: self.subject_value.clone(),
            status: encryption_key_status_from_str(&self.status),
            created_at: self.created_at,
            destroyed_at: self.destroyed_at,
        }
    }
}

const ENCRYPTION_KEY_COLUMNS: &str = "id, subject_key, subject_value, status, created_at, \
     destroyed_at, wrapped_key, wrap_nonce, key_provider, master_key_version, unreadable_since";

/// `event_store::protect_sensitive_fields`'s own get-or-create - "each key
/// provisioned exactly once... idempotent... repeat calls find the key
/// already provisioned rather than creating another one" (the note above
/// `rule CreateExternalEvent`). Not literally inside the same transaction
/// as the event/command write it protects - reuses the same "pre-resolve,
/// then inject as a plain closure" shape `next_sequence`'s own callers
/// already use for the identical "pure core needs a value only I/O can
/// produce" problem (see docs/architecture.md's write-up of this pass).
/// `ON CONFLICT ... DO NOTHING RETURNING` first, falling back to a plain
/// `SELECT` on the race-lost case - the standard upsert-or-fetch idiom,
/// safe under `encryption_keys_unique_active`'s own partial unique index.
///
/// Returns the row's own synthetic `id` alongside the domain entity (which
/// has none, matching `entity EncryptionKey` itself) and the unwrapped
/// `DataKey` - the same "domain struct has no id, caller gets one back
/// anyway for FK purposes" treatment `insert_command`'s own return value
/// already has. The caller needs `id` to link `event_encryption_keys`/
/// `command_encryption_keys` join rows once the event/command itself is
/// inserted.
///
/// Refuses the secrets namespace (`secrets::is_reserved_subject_key`): an
/// application's declared `SensitiveField` cannot provision or share a
/// secret version's key. A secret version's own key is provisioned by
/// `put_secret_value` through the private `get_or_create_encryption_key_on`.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_or_create_encryption_key(
    pool: &Pool,
    bounded_context: &str,
    subject_key: &str,
    subject_value: &str,
    key_service: &KeyService,
) -> crate::error::Result<(EncryptionKey, i64, DataKey)> {
    if secrets::is_reserved_subject_key(subject_key) {
        return Err(secrets::Error::ReservedSubjectKey.into());
    }
    let bc = require_bounded_context(pool, bounded_context).await?;
    provision_encryption_key(Db::Pool(pool), bc, subject_key, subject_value, key_service).await
}

/// [`get_or_create_encryption_key`] on a connection the caller holds,
/// with the bounded context already in hand. A command's own post-lock
/// provisioning runs it on the transaction holding the bounded context's
/// `sequence` lock, so it never needs a second pooled connection while
/// holding that lock (docs/architecture.md §117). A key created there
/// becomes durable with the command that needed it, or not at all.
async fn get_or_create_encryption_key_on(
    conn: &mut sqlx::PgConnection,
    bc: BoundedContext,
    subject_key: &str,
    subject_value: &str,
    key_service: &KeyService,
) -> crate::error::Result<(EncryptionKey, i64, DataKey)> {
    provision_encryption_key(Db::Conn(conn), bc, subject_key, subject_value, key_service).await
}

/// [`get_or_create_encryption_key_on`] on either a held connection or the
/// pool (see [`Db`]).
async fn provision_encryption_key(
    mut db: Db<'_>,
    bc: BoundedContext,
    subject_key: &str,
    subject_value: &str,
    key_service: &KeyService,
) -> crate::error::Result<(EncryptionKey, i64, DataKey)> {
    let bounded_context = bc.name.clone();
    let bounded_context = bounded_context.as_str();
    let schema = schema_ident(bounded_context);

    // docs/architecture.md §107: normally one pass. Another pass only when
    // the insert lost to a concurrent provisioner *and* that key was
    // destroyed (a concurrent `forgetSubject`) before this re-read it -
    // no active key at all, so provisioning again is the right outcome
    // (new data about a subject after its erasure gets a new key). This
    // used to `expect` and panic. Bounded, so a pathological churn is an
    // error, not a hang.
    const ATTEMPTS: usize = 5;
    for _ in 0..ATTEMPTS {
        let existing = get_active_encryption_key_row(
            &mut *db.conn().await?,
            bounded_context,
            subject_key,
            subject_value,
        )
        .await?;
        if let Some(row) = existing {
            let data_key = unwrap_row(&mut db, bounded_context, key_service, &row).await?;
            return Ok((row.to_domain(bc), row.id, data_key));
        }

        // The bounded context's own key, or the default one
        // (docs/architecture.md §230) - read every time, so a key assigned
        // on another instance is used from then on.
        let (key, recorded) = {
            let mut conn = db.conn().await?;
            let key = master_key::bounded_context_key(&mut *conn, bounded_context).await?;
            let recorded = match &key {
                Some(key) => {
                    let name = key_service.provider_for(Some(key))?.name().to_string();
                    master_key::key_recorded(&mut *conn, &name).await?
                }
                None => true,
            };
            (key, recorded)
        };
        let provider = key_service.provider_for(key.as_deref())?;
        // A bounded context's own key that is gone - the context was given
        // another key and this one deleted since the assignment was read -
        // isn't asked to wrap anything (Vault may even create a missing key
        // on encrypt): the next pass reads the assignment again.
        if !recorded {
            continue;
        }
        let (data_key, wrapped) = match key_service.generate_with(provider.as_ref()).await {
            Ok(generated) => generated,
            // The same, found by the provider: try again only when the
            // assignment did change meanwhile.
            Err(err)
                if key.is_some()
                    && master_key::bounded_context_key(&mut *db.conn().await?, bounded_context)
                        .await?
                        != key =>
            {
                tracing::info!(error = %err, "bounded context's key changed while wrapping; again");
                continue;
            }
            Err(err) => return Err(err.into()),
        };
        let now = Utc::now();
        // A bounded context's own key is stored only while its state row
        // is there, taken `FOR SHARE` in the same statement: a deletion of
        // the key waits for this, and one that came first leaves nothing to
        // take, so nothing is inserted and the next pass reads the bounded
        // context's key again (docs/architecture.md §230). The default key
        // is never deleted.
        let guard = if key.is_some() {
            "SELECT 1 FROM encryption_master_keys WHERE provider = $5 FOR SHARE"
        } else {
            "SELECT 1"
        };
        let inserted: Option<EncryptionKeyRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "WITH kept AS ({guard}) \
             INSERT INTO {schema}.encryption_keys \
             (subject_key, subject_value, status, created_at, wrapped_key, key_provider, \
             master_key_version) \
             SELECT $1, $2, 'active', $3, $4, $5, $6 FROM kept \
             ON CONFLICT (subject_key, subject_value) WHERE status = 'active' DO NOTHING \
             RETURNING {ENCRYPTION_KEY_COLUMNS}"
        )))
        .bind(subject_key)
        .bind(subject_value)
        .bind(now)
        .bind(&wrapped.ciphertext)
        .bind(provider.name())
        .bind(version_column(wrapped.version)?)
        .fetch_optional(&mut *db.conn().await?)
        .await?;

        if let Some(row) = inserted {
            return Ok((row.to_domain(bc), row.id, data_key));
        }
        // Lost the race to a concurrent provisioner - the next pass reads
        // the row it created (never the key just generated here, which
        // was never persisted and would silently disagree with it).
    }
    Err(crate::error::Error::row_not_found())
}

/// Where a provisioning or a read runs its SQL (docs/architecture.md §230):
/// on a connection the caller holds - a command's transaction under the
/// bounded context's `sequence` lock - or on the pool, a connection taken
/// for each statement and given back before any key provider is called, so
/// a slow provider doesn't hold pool connections while it answers.
enum Db<'c> {
    Conn(&'c mut sqlx::PgConnection),
    Pool(&'c Pool),
}

/// A connection for one statement: the caller's, or one from the pool.
enum Held<'a> {
    Borrowed(&'a mut sqlx::PgConnection),
    Owned(sqlx::pool::PoolConnection<Postgres>),
}

impl std::ops::Deref for Held<'_> {
    type Target = sqlx::PgConnection;
    fn deref(&self) -> &Self::Target {
        match self {
            Held::Borrowed(conn) => conn,
            Held::Owned(conn) => conn,
        }
    }
}

impl std::ops::DerefMut for Held<'_> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        match self {
            Held::Borrowed(conn) => conn,
            Held::Owned(conn) => conn,
        }
    }
}

impl Db<'_> {
    async fn conn(&mut self) -> crate::error::Result<Held<'_>> {
        Ok(match self {
            Db::Conn(conn) => Held::Borrowed(conn),
            Db::Pool(pool) => Held::Owned(pool.acquire().await?),
        })
    }
}

/// A master key version as the `master_key_version` column stores it.
fn version_column(version: u32) -> crate::error::Result<i32> {
    i32::try_from(version).map_err(|_| {
        encryption::Error::ProviderRefused {
            provider: "?".into(),
            message: format!("master key version {version} is out of range"),
        }
        .into()
    })
}

/// The data key an active row holds, through the key service
/// (docs/architecture.md §230): the key that wrapped it, or the legacy
/// master key for a row from before providers. A key this process hasn't
/// used yet - one another instance gave a bounded context - is looked up
/// once among the keys skilj records, on `executor`, and tried again.
///
/// A row marked unreadable that unwraps after all - its key was put right -
/// has its mark cleared, so it counts again for the rewrap, the retirement
/// and the key's deletion.
async fn unwrap_row(
    db: &mut Db<'_>,
    bounded_context: &str,
    key_service: &KeyService,
    row: &EncryptionKeyRow,
) -> crate::error::Result<DataKey> {
    let wrapped = row
        .wrapped_key
        .as_deref()
        .expect("an active encryption_keys row always still has its wrapped key");
    let stored = encryption::StoredWrap {
        provider: row.key_provider.as_deref(),
        version: row.master_key_version.and_then(|v| u32::try_from(v).ok()),
        ciphertext: wrapped,
        nonce: row.wrap_nonce.as_deref(),
    };
    let data_key = match key_service.unwrap(stored).await {
        Err(encryption::Error::ProviderChanged { .. }) => {
            master_key::register_known_keys(&mut *db.conn().await?, key_service).await?;
            key_service.unwrap(stored).await?
        }
        other => other?,
    };
    if row.unreadable_since.is_some() {
        let schema = schema_ident(bounded_context);
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "UPDATE {schema}.encryption_keys SET unreadable_since = NULL \
             WHERE id = $1 AND wrapped_key = $2"
        )))
        .bind(row.id)
        .bind(wrapped)
        .execute(&mut *db.conn().await?)
        .await?;
    }
    Ok(data_key)
}

/// The pre-resolution step every `event_store::protect_sensitive_fields`
/// caller needs before it can call that pure function at all - see
/// `docs/architecture.md`'s write-up of this pass and
/// `event_store::sensitive_field_subjects`'s own doc comment. Resolves
/// (get-or-creates) every `EncryptionKey` `payload` will need, merging
/// into `resolved` rather than returning a fresh map - a caller
/// protecting more than one payload against the same subject (a command
/// and the events it produces, in `process_command`'s case) calls this
/// once per payload, accumulating into the same map, so a shared subject
/// resolves to the identical `EncryptionKey` everywhere, exactly as the
/// spec requires. A no-op, no `key_service` needed, when `sensitive_fields`
/// is empty or names no subjects actually present in `payload` - the
/// identical "empty is a no-op" register `protect_sensitive_fields`
/// itself is in. `key_service: None` with something to resolve is a real,
/// actionable configuration error, not a silent skip.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn resolve_encryption_keys(
    pool: &Pool,
    bounded_context: &str,
    sensitive_fields: &[SensitiveField],
    payload: &str,
    key_service: Option<&KeyService>,
    resolved: &mut std::collections::HashMap<(String, String), (EncryptionKey, i64, DataKey)>,
) -> crate::error::Result<()> {
    let subjects = crate::event_store::sensitive_field_subjects(sensitive_fields, payload);
    if subjects.is_empty() {
        return Ok(());
    }
    let key_service = key_service.ok_or(encryption::Error::MasterKeyNotConfigured)?;
    for (subject_key, subject_value) in subjects {
        if resolved.contains_key(&(subject_key.clone(), subject_value.clone())) {
            continue;
        }
        let provisioned = get_or_create_encryption_key(
            pool,
            bounded_context,
            &subject_key,
            &subject_value,
            key_service,
        )
        .await?;
        resolved.insert((subject_key, subject_value), provisioned);
    }
    Ok(())
}

/// The read-side twin of `resolve_encryption_keys` above - the
/// pre-resolution step `event_store::render_event`/`render_command`'s own
/// caller needs before it can call either pure function at all. Same
/// accumulator-across-a-batch shape (a subject shared across many
/// events/commands in one query resolves once, not once per row) -
/// `resolvers::event_query`/`command_query`/`event_subscription` each
/// call this once per event/command in the batch being rendered,
/// accumulating into the same map.
///
/// Unlike the write side, this **filters by
/// `event_store::sensitive_field_is_granted` first** - only a subject
/// this caller is actually granted decrypt access to is ever looked up,
/// so an unauthorised caller's query needs no `key_service` at all, no
/// matter how many sensitive fields the payload declares. `key_service:
/// None` with at least one *granted* subject to resolve is a real,
/// actionable configuration error (confirmed via `AskUserQuestion` before
/// building - mirrors `resolve_encryption_keys`'s own identical
/// precedent) - a caller who *is* entitled to see a decrypted value
/// deserves to know the server can't produce one, not silent ciphertext
/// indistinguishable from "you're not authorised." A subject that *is*
/// granted but has no active key (destroyed by `ForgetSubject`, or never
/// provisioned) is recorded in `resolved` as `None` - `render_event`/
/// `render_command`'s own `resolve_data_key` closure sees `None` for it,
/// the correct crypto-shredding outcome, not an error. Recording the
/// miss, rather than leaving the subject out, is what stops a forgotten
/// subject shared across a page of events from being looked up again
/// for every one of them.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn resolve_data_keys_for_reading(
    pool: &Pool,
    bounded_context: &str,
    sensitive_fields: &[SensitiveField],
    payload: &str,
    access_mapping: &crate::access_control::RoleAccessMapping,
    key_service: Option<&KeyService>,
    resolved: &mut std::collections::HashMap<(String, String), Option<DataKey>>,
) -> crate::error::Result<()> {
    let granted_subjects: Vec<(String, String)> =
        crate::event_store::sensitive_field_subjects(sensitive_fields, payload)
            .into_iter()
            .filter(|(_, subject_value)| {
                crate::event_store::sensitive_field_is_granted(access_mapping, subject_value)
            })
            .collect();
    if granted_subjects.is_empty() {
        return Ok(());
    }
    let key_service = key_service.ok_or(encryption::Error::MasterKeyNotConfigured)?;
    for (subject_key, subject_value) in granted_subjects {
        if resolved.contains_key(&(subject_key.clone(), subject_value.clone())) {
            continue;
        }
        let data_key = get_active_data_key(
            pool,
            bounded_context,
            &subject_key,
            &subject_value,
            key_service,
        )
        .await?;
        resolved.insert((subject_key, subject_value), data_key);
    }
    Ok(())
}

/// The `id`s `insert_event_and_update_sync_projections`/`insert_command`
/// need for their own join-row writes, for exactly the `EncryptionKey`s a
/// `protect_sensitive_fields` call actually returned as used (`Event`/
/// `Command.encryption_keys`) - re-keyed back into `resolved` by
/// `(subject_key, subject_value)`, the only identity `EncryptionKey`
/// itself carries.
#[tracing::instrument(skip_all)]
pub fn encryption_key_ids(
    used: &[EncryptionKey],
    resolved: &std::collections::HashMap<(String, String), (EncryptionKey, i64, DataKey)>,
) -> Vec<i64> {
    used.iter()
        .map(|k| {
            resolved
                .get(&(k.subject_key.clone(), k.subject_value.clone()))
                .expect("every key protect_sensitive_fields used came from resolve_encryption_keys' own resolve_key closure, so it must still be in the map that built it")
                .1
        })
        .collect()
}

async fn get_active_encryption_key_row(
    executor: impl sqlx::PgExecutor<'_>,
    bounded_context: &str,
    subject_key: &str,
    subject_value: &str,
) -> crate::error::Result<Option<EncryptionKeyRow>> {
    let schema = schema_ident(bounded_context);
    let row: Option<EncryptionKeyRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {ENCRYPTION_KEY_COLUMNS} FROM {schema}.encryption_keys \
         WHERE subject_key = $1 AND subject_value = $2 AND status = 'active'"
    )))
    .bind(subject_key)
    .bind(subject_value)
    .fetch_optional(executor)
    .await?;
    Ok(row)
}

/// The active `EncryptionKey` for one subject, if any - `resolvers::
/// subject_erasure`'s own lookup before calling the pure `forget_subject`
/// (§SubjectErasure's `context key: EncryptionKey where ... status =
/// active`). No key material - `get_or_create_encryption_key` is the only
/// function that ever needs (and returns) that.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_active_encryption_key(
    pool: &Pool,
    bounded_context: &str,
    subject_key: &str,
    subject_value: &str,
) -> crate::error::Result<Option<EncryptionKey>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(None);
    };
    Ok(
        get_active_encryption_key_row(pool, bounded_context, subject_key, subject_value)
            .await?
            .map(|row| row.to_domain(bc)),
    )
}

/// The real decrypt-on-read pass's own lookup - the active subject's
/// `DataKey`, unwrapped and ready to decrypt with, if any. Composes
/// `get_active_encryption_key_row` (already used by `get_or_create_encryption_key`)
/// with the identical `unwrap_row` that function already calls - no new
/// SQL. `None` covers both "never provisioned" and "destroyed by
/// `ForgetSubject`" identically, matching `resolve_data_keys_for_reading`'s
/// own doc comment for why that's correct crypto-shredding behaviour, not
/// a gap.
///
/// Refuses the secrets namespace (`secrets::is_reserved_subject_key`): a
/// secret version's key is only ever unwrapped by `fetch_secret_value`,
/// which goes through the private `get_active_data_key_on`. An
/// application's declared `SensitiveField` cannot read a secret's key.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_active_data_key(
    pool: &Pool,
    bounded_context: &str,
    subject_key: &str,
    subject_value: &str,
    key_service: &KeyService,
) -> crate::error::Result<Option<DataKey>> {
    if secrets::is_reserved_subject_key(subject_key) {
        return Err(secrets::Error::ReservedSubjectKey.into());
    }
    get_active_data_key_on(
        pool,
        bounded_context,
        subject_key,
        subject_value,
        key_service,
    )
    .await
}

/// [`get_active_data_key`] without the reserved-namespace guard - the shared
/// body, used by `fetch_secret_value` (which is *how* the reserved
/// namespace is meant to be reached) and by the public wrapper above.
async fn get_active_data_key_on(
    pool: &Pool,
    bounded_context: &str,
    subject_key: &str,
    subject_value: &str,
    key_service: &KeyService,
) -> crate::error::Result<Option<DataKey>> {
    match get_active_encryption_key_row(pool, bounded_context, subject_key, subject_value).await? {
        Some(row) => Ok(Some(
            unwrap_row(&mut Db::Pool(pool), bounded_context, key_service, &row).await?,
        )),
        None => Ok(None),
    }
}

/// `projections::read_projection`'s own pre-resolution step - every active
/// `EncryptionKey`'s own `DataKey`, for `subject_value` alone, across
/// *every* `subject_key` namespace - unlike `get_active_data_key` above,
/// which needs the exact `subject_key` a declared `SensitiveField` names,
/// this is the automatic, undeclared case: a projection's own instance
/// `key` is a subject value with no known-in-advance namespace, so every
/// namespace with an active key for it is a real candidate (see
/// `encryption::decrypt_ciphertext_leaves`'s own doc comment for why
/// trying more than one candidate is safe, not a heuristic). Empty when
/// nothing matches - no `key_service` needed at all in that case, the
/// identical "nothing to resolve, no key required" property
/// `resolve_data_keys_for_reading` already has. A **non-empty** match
/// with `key_service: None` is the identical hard, actionable
/// configuration error `resolve_encryption_keys`/`resolve_data_keys_for_reading`
/// already raise for the same underlying reason - confirmed with the
/// user before building real decrypt-on-read at all.
///
/// Excludes the secrets namespace (`secrets::SUBJECT_KEY`): a projection
/// never holds a secret version's ciphertext, and a secret's key is only
/// ever unwrapped by `fetch_secret_value`, so a subject value that
/// happens to match a secret version must not hand its `DataKey` out here.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_active_data_keys_for_subject_value(
    pool: &Pool,
    bounded_context: &str,
    subject_value: &str,
    key_service: Option<&KeyService>,
) -> crate::error::Result<Vec<DataKey>> {
    let schema = schema_ident(bounded_context);
    let rows: Vec<EncryptionKeyRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {ENCRYPTION_KEY_COLUMNS} FROM {schema}.encryption_keys \
         WHERE subject_value = $1 AND status = 'active' AND subject_key <> $2"
    )))
    .bind(subject_value)
    .bind(secrets::SUBJECT_KEY)
    .fetch_all(pool)
    .await?;
    if rows.is_empty() {
        return Ok(Vec::new());
    }
    let key_service = key_service.ok_or(encryption::Error::MasterKeyNotConfigured)?;
    let mut data_keys = Vec::with_capacity(rows.len());
    let mut db = Db::Pool(pool);
    for row in &rows {
        data_keys.push(unwrap_row(&mut db, bounded_context, key_service, row).await?);
    }
    Ok(data_keys)
}

/// Persists `forget_subject`'s outcome - real crypto-shredding, not just
/// the status flip: `wrapped_key`/`wrap_nonce` are set to `NULL` in the
/// same statement, so even the master key can no longer recover this
/// subject's `DataKey` afterwards (see `forget_subject`'s own doc comment:
/// "this function's own caller enacts \[it\] by destroying the key row").
/// Scoped to `status = 'active'` in the `WHERE` clause purely
/// defensively, since the pure rule already rejects an inactive key
/// before this is ever called.
///
/// Refuses the secrets namespace (`secrets::is_reserved_subject_key`): a
/// secret version's key is only ever shredded by `put_secret_value`/
/// `revoke_secret`, which retire the version row in the same transaction.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn destroy_encryption_key(
    pool: &Pool,
    bounded_context: &str,
    subject_key: &str,
    subject_value: &str,
    destroyed_at: DateTime<Utc>,
) -> crate::error::Result<()> {
    if secrets::is_reserved_subject_key(subject_key) {
        return Err(secrets::Error::ReservedSubjectKey.into());
    }
    let schema = schema_ident(bounded_context);
    destroy_encryption_key_on(pool, &schema, subject_key, subject_value, destroyed_at).await
}

/// [`destroy_encryption_key`] on any executor, with the schema already in
/// hand - so a secret rotation (`put_secret_value`) or revocation
/// (`revoke_secret`) can shred the superseded version's key in the *same*
/// transaction that retires it, never a second pooled connection and never
/// a window where the version is gone but its key is not.
async fn destroy_encryption_key_on(
    executor: impl sqlx::PgExecutor<'_>,
    schema: &str,
    subject_key: &str,
    subject_value: &str,
    destroyed_at: DateTime<Utc>,
) -> crate::error::Result<()> {
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.encryption_keys SET status = 'destroyed', destroyed_at = $1, \
         wrapped_key = NULL, wrap_nonce = NULL \
         WHERE subject_key = $2 AND subject_value = $3 AND status = 'active'"
    )))
    .bind(destroyed_at)
    .bind(subject_key)
    .bind(subject_value)
    .execute(executor)
    .await?;
    Ok(())
}

// --- Secret / SecretGrant (docs/architecture.md §Secret) ---
//
// A secret version is a row in `{schema}.secret_versions` holding only the
// *ciphertext* (sealed under that version's own `DataKey`, which is itself
// wrapped under the process-wide master key) plus metadata. The value is
// never stored in the clear, so the identical guarantee the inspector
// already relies on for a sensitive field holds here: a raw database dump
// and the inspector both see ciphertext, nothing else. Rotation/revocation
// destroy the version's `EncryptionKey` in the same transaction
// (`destroy_encryption_key_on`), which is real crypto-shredding.
//
// The `secret_grants` table is the only thing that lets a caller past
// `secrets::require_secret_access`; there is deliberately no admin
// override, so an ungranted adapter (or an admin) is refused a fetch.

fn secret_versions_table_ddl(schema: &str) -> String {
    format!(
        "CREATE TABLE IF NOT EXISTS {schema}.secret_versions (
            id BIGSERIAL PRIMARY KEY,
            name TEXT NOT NULL,
            version BIGINT NOT NULL,
            ciphertext TEXT NOT NULL,
            encryption_key_id BIGINT NOT NULL REFERENCES {schema}.encryption_keys (id),
            status TEXT NOT NULL CHECK (status IN ('active', 'rotated', 'revoked')),
            expires_at TIMESTAMPTZ,
            created_at TIMESTAMPTZ NOT NULL,
            rotated_at TIMESTAMPTZ,
            revoked_at TIMESTAMPTZ,
            last_read_at TIMESTAMPTZ,
            last_read_by TEXT,
            UNIQUE (name, version)
        )"
    )
}

fn secret_grants_table_ddl(schema: &str) -> String {
    format!(
        "CREATE TABLE IF NOT EXISTS {schema}.secret_grants (
            id TEXT PRIMARY KEY,
            name TEXT NOT NULL,
            grantee_role_id TEXT NOT NULL REFERENCES public.roles (id),
            status TEXT NOT NULL CHECK (status IN ('active', 'revoked')),
            created_at TIMESTAMPTZ NOT NULL,
            revoked_at TIMESTAMPTZ
        )"
    )
}

/// Creates `secret_versions`/`secret_grants` in one bounded context if they
/// are not already there - the same "patched into every bounded context,
/// every startup, no general per-context migration mechanism"
/// (`ensure_private_field_grants_table`'s own doc comment) treatment.
pub async fn ensure_secret_tables(pool: &Pool, bounded_context: &str) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(secret_versions_table_ddl(&schema)))
        .execute(pool)
        .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(
        &schema,
        "secret_versions_unique_active",
        format!(
            "CREATE UNIQUE INDEX IF NOT EXISTS secret_versions_unique_active \
             ON {schema}.secret_versions (name) WHERE status = 'active'"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(
        &schema,
        "secret_versions_by_name",
        format!(
            "CREATE INDEX IF NOT EXISTS secret_versions_by_name \
             ON {schema}.secret_versions (name, version DESC)"
        ),
    )))
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(secret_grants_table_ddl(&schema)))
        .execute(pool)
        .await?;
    sqlx::query(sqlx::AssertSqlSafe(create_index_patch(
        &schema,
        "secret_grants_by_grantee",
        format!(
            "CREATE INDEX IF NOT EXISTS secret_grants_by_grantee \
             ON {schema}.secret_grants (grantee_role_id, status)"
        ),
    )))
    .execute(pool)
    .await?;
    Ok(())
}

#[derive(sqlx::FromRow)]
struct SecretVersionRow {
    id: i64,
    name: String,
    version: i64,
    #[allow(dead_code)]
    ciphertext: String,
    #[allow(dead_code)]
    encryption_key_id: i64,
    status: String,
    expires_at: Option<DateTime<Utc>>,
    created_at: DateTime<Utc>,
    rotated_at: Option<DateTime<Utc>>,
    revoked_at: Option<DateTime<Utc>>,
    last_read_at: Option<DateTime<Utc>>,
    last_read_by: Option<String>,
}

const SECRET_VERSION_COLUMNS: &str = "id, name, version, ciphertext, encryption_key_id, status, \
     expires_at, created_at, rotated_at, revoked_at, last_read_at, last_read_by";

impl SecretVersionRow {
    /// The `Secret` domain value - note it carries no ciphertext field at
    /// all, so the value cannot ride along on a normal query's result even
    /// by accident.
    fn to_domain(&self, bounded_context: BoundedContext) -> Secret {
        Secret {
            bounded_context,
            name: self.name.clone(),
            version: self.version,
            status: secret_status_from_str(&self.status),
            expires_at: self.expires_at,
            created_at: self.created_at,
            rotated_at: self.rotated_at,
            revoked_at: self.revoked_at,
            last_read_at: self.last_read_at,
            last_read_by: self.last_read_by.clone(),
        }
    }
}

// Both status mappings fail closed: the CHECK constraints make any other
// string unreachable today, but should one ever appear (a hand edit, a
// later status added without updating this), it reads as the terminal,
// non-fetchable state rather than as `active`.
fn secret_status_from_str(s: &str) -> SecretStatus {
    match s {
        "active" => SecretStatus::Active,
        "rotated" => SecretStatus::Rotated,
        _ => SecretStatus::Revoked,
    }
}

fn secret_grant_status_from_str(s: &str) -> SecretGrantStatus {
    match s {
        "active" => SecretGrantStatus::Active,
        _ => SecretGrantStatus::Revoked,
    }
}

/// Serializes every mutating operation on one secret (create/rotate/revoke)
/// within a bounded context, across instances - a transaction-scoped
/// advisory lock keyed by the context and name. Without it two concurrent
/// first-creations could both decide version 1 and collide on
/// `(name, version)`; with it they serialize, the second seeing the first's
/// version and rotating it. Released automatically at commit/rollback.
async fn acquire_secret_lock(
    conn: &mut sqlx::PgConnection,
    bounded_context: &str,
    name: &str,
) -> crate::error::Result<()> {
    let key = format!("skilj-secret:{bounded_context}:{name}");
    sqlx::query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)")
        .bind(key)
        .execute(&mut *conn)
        .await?;
    Ok(())
}

/// The active version row. `for_update` takes a row lock (`SELECT ... FOR
/// UPDATE`) so two concurrent rotations of the same secret serialize: the
/// second waits, re-reads under `READ COMMITTED`, finds the row no longer
/// `active`, and provisions the next version instead of colliding on the
/// `(name, version)` unique constraint.
async fn get_active_secret_row_on(
    executor: impl sqlx::PgExecutor<'_>,
    bounded_context: &str,
    name: &str,
    for_update: bool,
) -> crate::error::Result<Option<SecretVersionRow>> {
    let schema = schema_ident(bounded_context);
    let lock = if for_update { " FOR UPDATE" } else { "" };
    let row: Option<SecretVersionRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {SECRET_VERSION_COLUMNS} FROM {schema}.secret_versions \
         WHERE name = $1 AND status = 'active'{lock}"
    )))
    .bind(name)
    .fetch_optional(executor)
    .await?;
    Ok(row)
}

/// The active version of one secret, metadata only - a normal query's own
/// result shape. Never the value.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context, name = %name))]
pub async fn get_active_secret(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
) -> crate::error::Result<Option<Secret>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(None);
    };
    Ok(get_active_secret_row_on(pool, bounded_context, name, false)
        .await?
        .map(|row| row.to_domain(bc)))
}

/// Every active secret's metadata in one bounded context - the shape a
/// `secrets` list query returns, `Secret` (metadata) and never
/// `SecretValue`. Ordered by name so the list is stable.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_active_secrets(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<Vec<Secret>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(Vec::new());
    };
    let schema = schema_ident(bounded_context);
    let rows: Vec<SecretVersionRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {SECRET_VERSION_COLUMNS} FROM {schema}.secret_versions \
         WHERE status = 'active' ORDER BY name"
    )))
    .fetch_all(pool)
    .await?;
    Ok(rows.iter().map(|row| row.to_domain(bc.clone())).collect())
}

/// Creates a secret (or a new version of one, rotating the previous active
/// version). The value is sealed under a fresh per-version `DataKey` in the
/// `"secret"`/`"{name}#{version}"` namespace and only the ciphertext is
/// stored. If a previous version was active, it is retired (`rotated`) and
/// its key destroyed in the *same* transaction - so an old secret value is
/// unrecoverable even against someone who later reads the whole database
/// with the master key in hand.
///
/// A concurrent rotation of the same secret serializes on the active row's
/// own lock (`get_active_secret_row_on`'s `for_update`): the second waits,
/// finds the version already retired, and provisions the next one rather
/// than colliding on `(name, version)`.
///
/// Takes the value as a [`SecretValue`], so the input side gets the same
/// no-`Debug`/no-serde protection as a fetched value, and the caller's
/// plaintext is wiped when it drops that value.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context, name = %name))]
pub async fn put_secret_value(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
    plaintext: &SecretValue,
    expires_at: Option<DateTime<Utc>>,
    key_service: &KeyService,
    now: DateTime<Utc>,
) -> crate::error::Result<Secret> {
    secrets::validate_secret_name(name).map_err(crate::error::Error::from)?;
    let bc = require_bounded_context(pool, bounded_context).await?;
    let schema = schema_ident(bounded_context);
    let mut tx = pool.begin().await?;
    acquire_secret_lock(&mut tx, bounded_context, name).await?;

    // Retire and shred the currently-active version, if there is one. Read
    // with the transaction so the version counter below is computed under
    // the same snapshot.
    if let Some(old) = get_active_secret_row_on(&mut *tx, bounded_context, name, true).await? {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "UPDATE {schema}.secret_versions SET status = 'rotated', rotated_at = $1 \
             WHERE id = $2"
        )))
        .bind(now)
        .bind(old.id)
        .execute(&mut *tx)
        .await?;
        let old_subject_value = secrets::subject_value(name, old.version);
        destroy_encryption_key_on(
            &mut *tx,
            &schema,
            secrets::SUBJECT_KEY,
            &old_subject_value,
            now,
        )
        .await?;
    }

    let next_version: i64 = sqlx::query_scalar(sqlx::AssertSqlSafe(format!(
        "SELECT COALESCE(MAX(version), 0) + 1 FROM {schema}.secret_versions WHERE name = $1"
    )))
    .bind(name)
    .fetch_one(&mut *tx)
    .await?;

    let subject_value = secrets::subject_value(name, next_version);
    let (_key, key_id, data_key) = get_or_create_encryption_key_on(
        &mut tx,
        bc.clone(),
        secrets::SUBJECT_KEY,
        &subject_value,
        key_service,
    )
    .await?;
    let ciphertext = encryption::encrypt_leaf(&data_key, plaintext.expose());

    let row: SecretVersionRow = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.secret_versions \
         (name, version, ciphertext, encryption_key_id, status, expires_at, created_at) \
         VALUES ($1, $2, $3, $4, 'active', $5, $6) \
         RETURNING {SECRET_VERSION_COLUMNS}"
    )))
    .bind(name)
    .bind(next_version)
    .bind(&ciphertext)
    .bind(key_id)
    .bind(expires_at)
    .bind(now)
    .fetch_one(&mut *tx)
    .await?;

    tx.commit().await?;
    Ok(row.to_domain(bc))
}

/// Explicitly revokes the active version of a secret and destroys its key -
/// the "end of life" that rotation also performs, but terminal and
/// deliberate: nothing can fetch this secret again. Returns the
/// now-revoked version.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context, name = %name))]
pub async fn revoke_secret(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
    now: DateTime<Utc>,
) -> crate::error::Result<Secret> {
    secrets::validate_secret_name(name).map_err(crate::error::Error::from)?;
    let bc = require_bounded_context(pool, bounded_context).await?;
    let schema = schema_ident(bounded_context);
    let mut tx = pool.begin().await?;
    acquire_secret_lock(&mut tx, bounded_context, name).await?;

    let Some(row) = get_active_secret_row_on(&mut *tx, bounded_context, name, true).await? else {
        return Err(secrets::Error::NotActive {
            name: name.to_string(),
        }
        .into());
    };

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.secret_versions SET status = 'revoked', revoked_at = $1 WHERE id = $2"
    )))
    .bind(now)
    .bind(row.id)
    .execute(&mut *tx)
    .await?;
    let subject_value = secrets::subject_value(name, row.version);
    destroy_encryption_key_on(&mut *tx, &schema, secrets::SUBJECT_KEY, &subject_value, now).await?;

    tx.commit().await?;

    let mut revoked = row.to_domain(bc);
    revoked.status = SecretStatus::Revoked;
    revoked.revoked_at = Some(now);
    Ok(revoked)
}

/// Grants one Role read access to one secret. The grant is what
/// `fetch_secret_value` checks; without it the fetch is refused.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context, name = %name))]
pub async fn grant_secret_access(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
    grantee_role_id: &str,
    now: DateTime<Utc>,
) -> crate::error::Result<SecretGrant> {
    let bc = require_bounded_context(pool, bounded_context).await?;
    let grant = secrets::grant_secret_access(&bc, name, grantee_role_id, now)
        .map_err(crate::error::Error::from)?;
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.secret_grants \
         (id, name, grantee_role_id, status, created_at) VALUES ($1, $2, $3, 'active', $4)"
    )))
    .bind(&grant.id)
    .bind(&grant.name)
    .bind(&grant.grantee_role_id)
    .bind(grant.created_at)
    .execute(pool)
    .await?;
    Ok(grant)
}

/// Ends every active grant of `name` to `grantee_role_id`. Returns how many
/// were revoked (0 is not an error - revoking a grant that was never made,
/// or was already revoked, is idempotent).
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context, name = %name))]
pub async fn revoke_secret_access(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
    grantee_role_id: &str,
    now: DateTime<Utc>,
) -> crate::error::Result<u64> {
    let schema = schema_ident(bounded_context);
    let result = sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.secret_grants SET status = 'revoked', revoked_at = $1 \
         WHERE name = $2 AND grantee_role_id = $3 AND status = 'active'"
    )))
    .bind(now)
    .bind(name)
    .bind(grantee_role_id)
    .execute(pool)
    .await?;
    Ok(result.rows_affected())
}

#[derive(sqlx::FromRow)]
struct SecretGrantRow {
    id: String,
    name: String,
    grantee_role_id: String,
    status: String,
    created_at: DateTime<Utc>,
    revoked_at: Option<DateTime<Utc>>,
}

const SECRET_GRANT_COLUMNS: &str = "id, name, grantee_role_id, status, created_at, revoked_at";

impl SecretGrantRow {
    fn to_domain(&self, bounded_context: BoundedContext) -> SecretGrant {
        SecretGrant {
            id: self.id.clone(),
            bounded_context,
            name: self.name.clone(),
            grantee_role_id: self.grantee_role_id.clone(),
            status: secret_grant_status_from_str(&self.status),
            created_at: self.created_at,
            revoked_at: self.revoked_at,
        }
    }
}

/// The active grants naming `grantee_role_id` in one bounded context -
/// everything `fetch_secret_value` consults for a caller.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_active_secret_grants_for_grantee(
    pool: &Pool,
    bounded_context: &str,
    grantee_role_id: &str,
) -> crate::error::Result<Vec<SecretGrant>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(Vec::new());
    };
    let schema = schema_ident(bounded_context);
    let rows: Vec<SecretGrantRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {SECRET_GRANT_COLUMNS} FROM {schema}.secret_grants \
         WHERE grantee_role_id = $1 AND status = 'active'"
    )))
    .bind(grantee_role_id)
    .fetch_all(pool)
    .await?;
    Ok(rows.iter().map(|row| row.to_domain(bc.clone())).collect())
}

/// The one place a secret is ever decrypted: an explicit fetch by a caller
/// already granted it.
///
/// Order matters for the leak list: the grant is checked **before** the
/// secret is even looked up, so an ungranted caller (`secret_access_not_granted`)
/// cannot tell a live secret from a missing one - the fetch is a single
/// opaque "no". A granted caller then gets `secret_not_active` if there is
/// no active version (rotated/revoked/never created), or the plaintext if
/// there is. The read is then summarised onto the version's own row
/// (`last_read_at`/`last_read_by`), one `UPDATE`, never an event per fetch.
///
/// `expires_at` is **not** checked here: an active version is returned even
/// once it has expired. That is deliberate - expiry is advisory, the
/// credential's own issuer is what enforces it, and an adapter refreshing
/// an expired OAuth access token typically still needs the stored refresh
/// token (or the expired value itself) to do so. Only rotation and
/// revocation end what a fetch can return; use
/// `secrets::secret_needs_refresh` to act before expiry.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context, name = %name))]
pub async fn fetch_secret_value(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
    caller_role_id: &str,
    key_service: &KeyService,
    now: DateTime<Utc>,
) -> crate::error::Result<SecretValue> {
    secrets::validate_secret_name(name).map_err(crate::error::Error::from)?;
    // Confirms the bounded context exists before anything else; the row
    // itself is not needed here.
    let _ = require_bounded_context(pool, bounded_context).await?;

    let grants =
        list_active_secret_grants_for_grantee(pool, bounded_context, caller_role_id).await?;
    secrets::require_secret_access(name, caller_role_id, &grants)
        .map_err(crate::error::Error::from)?;

    let Some(row) = get_active_secret_row_on(pool, bounded_context, name, false).await? else {
        return Err(secrets::Error::NotActive {
            name: name.to_string(),
        }
        .into());
    };

    let subject_value = secrets::subject_value(name, row.version);
    let Some(data_key) = get_active_data_key_on(
        pool,
        bounded_context,
        secrets::SUBJECT_KEY,
        &subject_value,
        key_service,
    )
    .await?
    else {
        // The active version's key is gone - a torn state that only a raced
        // revoke/rotate or a manual key destroy could produce. Report it as
        // no-active-secret rather than panic; nothing is fetchable.
        return Err(secrets::Error::NotActive {
            name: name.to_string(),
        }
        .into());
    };
    let plaintext = encryption::decrypt_leaf(&data_key, &row.ciphertext)?;

    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.secret_versions SET last_read_at = $1, last_read_by = $2 WHERE id = $3"
    )))
    .bind(now)
    .bind(caller_role_id)
    .bind(row.id)
    .execute(pool)
    .await?;

    Ok(SecretValue::new(plaintext))
}

/// `forgetSubject`'s blind-tag half (docs/architecture.md §205): for every
/// blind tag of `bounded_context` declared `Erasure::WithSubject` with this
/// `subject_key`, removes the tag from every event and command whose
/// `subject_tag` tag is `subject_value` - from `events.tags`, `event_tags`,
/// `commands.consistency_tags` and the items of `commands.consistency_query`
/// - so the value is free again and no hash of it is left. Called before
/// the key is destroyed, so a failure leaves `forgetSubject` retryable.
///
/// One transaction, which also bumps the registrations generation: every
/// instance's event cache refills a window whose registrations stamp
/// changed, so none keeps serving the erased tags. Returns how many events
/// lost a tag.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn forget_subject_in_blind_tags(
    pool: &Pool,
    bounded_context: &str,
    subject_key: &str,
    subject_value: &str,
) -> crate::error::Result<u64> {
    ensure_blind_tags_table(pool, bounded_context).await?;
    let schema = schema_ident(bounded_context);
    let erased: Vec<(String, String)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT tag_key, erasure->>'subject_tag' FROM {schema}.blind_tags \
         WHERE erasure->>'kind' = 'with_subject' AND erasure->>'subject_key' = $1 \
         ORDER BY tag_key"
    )))
    .bind(subject_key)
    .fetch_all(pool)
    .await?;
    if erased.is_empty() {
        return Ok(0);
    }
    ensure_registrations_generation(pool, bounded_context).await?;
    let mut tx = pool.begin().await?;
    // A rotation of these tags (docs/architecture.md §209) holds their
    // rows while it rewrites the same events: wait for it here, before
    // touching any, rather than meet it half-way.
    let keys: Vec<&str> = erased.iter().map(|(tag_key, _)| tag_key.as_str()).collect();
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "SELECT 1 FROM {schema}.blind_tags WHERE tag_key = ANY($1) FOR SHARE"
    )))
    .bind(&keys)
    .execute(&mut *tx)
    .await?;
    let mut events_changed = 0;
    for (tag_key, subject_tag) in &erased {
        let subject = serde_json::json!([{ "key": subject_tag, "value": subject_value }]);
        // The subject's events carrying the blind tag, found through
        // `event_tags` (docs/architecture.md §210), with the tag's index
        // rows to delete exactly.
        let carrying: Vec<(i64, String, Option<String>)> =
            sqlx::query_as(sqlx::AssertSqlSafe(format!(
                "SELECT e.sequence, e.event_type_name, t->>'value' \
                 FROM {schema}.events e, jsonb_array_elements(e.tags) t \
                 WHERE e.sequence = ANY(ARRAY(SELECT s.sequence FROM {schema}.event_tags s \
                    WHERE s.tag_key = $1 AND s.tag_value = $2)) \
                 AND t->>'key' = $3"
            )))
            .bind(subject_tag)
            .bind(subject_value)
            .bind(tag_key)
            .fetch_all(&mut *tx)
            .await?;
        let mut sequences: Vec<i64> = carrying.iter().map(|(sequence, _, _)| *sequence).collect();
        sequences.sort_unstable();
        sequences.dedup();
        events_changed += sequences.len() as u64;
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "UPDATE {schema}.events e SET tags = (\
                SELECT coalesce(jsonb_agg(t), '[]'::jsonb) \
                FROM jsonb_array_elements(e.tags) t WHERE t->>'key' <> $2) \
             WHERE e.sequence = ANY($1)"
        )))
        .bind(&sequences)
        .bind(tag_key)
        .execute(&mut *tx)
        .await?;
        let (valued, unvalued): (Vec<_>, Vec<_>) = carrying
            .into_iter()
            .partition(|(_, _, value)| value.is_some());
        let (valued_sequences, (valued_types, values)): (Vec<i64>, (Vec<String>, Vec<String>)) =
            valued
                .into_iter()
                .map(|(sequence, event_type, value)| {
                    (sequence, (event_type, value.unwrap_or_default()))
                })
                .unzip();
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "DELETE FROM {schema}.event_tags et \
             USING unnest($2::text[], $3::text[], $4::bigint[]) AS x(value, event_type, sequence) \
             WHERE et.tag_key = $1 AND et.tag_value = x.value \
             AND et.event_type_name = x.event_type AND et.sequence = x.sequence"
        )))
        .bind(tag_key)
        .bind(&values)
        .bind(&valued_types)
        .bind(&valued_sequences)
        .execute(&mut *tx)
        .await?;
        if !unvalued.is_empty() {
            let unvalued: Vec<i64> = unvalued.iter().map(|(sequence, _, _)| *sequence).collect();
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "DELETE FROM {schema}.event_tags \
                 WHERE tag_key = $1 AND tag_value IS NULL AND sequence = ANY($2)"
            )))
            .bind(tag_key)
            .bind(&unvalued)
            .execute(&mut *tx)
            .await?;
        }
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "UPDATE {schema}.commands c SET \
                consistency_tags = (\
                    SELECT coalesce(jsonb_agg(t), '[]'::jsonb) \
                    FROM jsonb_array_elements(c.consistency_tags) t WHERE t->>'key' <> $2), \
                consistency_query = (\
                    SELECT coalesce(jsonb_agg(jsonb_set(item, '{{tags}}', (\
                        SELECT coalesce(jsonb_agg(t), '[]'::jsonb) \
                        FROM jsonb_array_elements(coalesce(item->'tags', '[]'::jsonb)) t \
                        WHERE t->>'key' <> $2))), '[]'::jsonb) \
                    FROM jsonb_array_elements(c.consistency_query) item) \
             WHERE c.consistency_tags @> $1"
        )))
        .bind(Json(&subject))
        .bind(tag_key)
        .execute(&mut *tx)
        .await?;
    }
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.registrations_generation SET generation = generation + 1"
    )))
    .execute(&mut *tx)
    .await?;
    tx.commit().await?;
    Ok(events_changed)
}

// --- Command ---

#[derive(sqlx::FromRow)]
struct CommandRow {
    external_id: String,
    command_type_name: String,
    payload: String,
    metadata_type: String,
    metadata_version: i64,
    metadata_client_id: String,
    metadata_created_at: DateTime<Utc>,
    // issue #18 - `None` only for a row written before these
    // columns existed.
    metadata_correlation_id: Option<String>,
    metadata_causation_id: Option<String>,
    consistency_tags: Json<Vec<Tag>>,
    consistency_boundary: Option<i64>,
    consistency_query: Json<Vec<QueryItem>>,
}

impl CommandRow {
    async fn into_domain(
        self,
        pool: &Pool,
        bounded_context: &str,
    ) -> crate::error::Result<Command> {
        let command_type =
            require_command_type(pool, bounded_context, &self.command_type_name).await?;
        Ok(self.with_type(command_type))
    }

    fn with_type(self, command_type: CommandType) -> Command {
        Command {
            id: self.external_id,
            bounded_context: command_type.bounded_context.clone(),
            command_type,
            payload: self.payload,
            metadata: Metadata {
                r#type: self.metadata_type,
                version: self.metadata_version,
                client_id: self.metadata_client_id,
                created_at: self.metadata_created_at,
                correlation_id: self.metadata_correlation_id,
                causation_id: self.metadata_causation_id,
            },
            encryption_keys: Vec::new(),
            consistency_tags: self.consistency_tags.0,
            consistency_query: self.consistency_query.0,
            consistency_boundary: self.consistency_boundary,
        }
    }
}

/// `CommandRow::into_domain` for many rows at once: the bounded context
/// once and every command type the rows name in one query, instead of a
/// command type, its bounded context and that context's creator Role per
/// row (docs/architecture.md §126). A row naming a type that's gone is
/// the same `row_not_found` `into_domain` gives.
async fn commands_from_rows(
    pool: &Pool,
    bounded_context: &str,
    rows: Vec<CommandRow>,
) -> crate::error::Result<Vec<Command>> {
    if rows.is_empty() {
        return Ok(Vec::new());
    }
    let bc = require_bounded_context(pool, bounded_context).await?;
    let mut names: Vec<&str> = rows.iter().map(|r| r.command_type_name.as_str()).collect();
    names.sort_unstable();
    names.dedup();
    let command_types = get_command_types_by_names_with_bc(pool, &bc, &names).await?;
    rows.into_iter()
        .map(|row| {
            let command_type = command_types
                .get(&row.command_type_name)
                .cloned()
                .ok_or_else(crate::error::Error::row_not_found)?;
            Ok(row.with_type(command_type))
        })
        .collect()
}

// `external_id` - not `id`, this table's own internal `BIGSERIAL` primary
// key, purely an FK-linking detail `insert_command` returns separately
// and never surfaces on `Command` itself - is `Command.id` (drift audit
// finding #12): a real, `generate_token_id()`-assigned identity, added so
// `fetch_commands`'s own `triggered_event` lookup can match a specific
// command precisely rather than by whole-struct content equality.
const COMMAND_COLUMNS: &str = "external_id, command_type_name, payload, metadata_type, \
    metadata_version, metadata_client_id, metadata_created_at, metadata_correlation_id, \
    metadata_causation_id, consistency_tags, consistency_boundary, consistency_query";

/// Insert-only, unlike every `upsert_*` above - re-registration/promotion
/// don't apply to a `Command`, so every call is a new row, even though it
/// now has a real identity of its own (`Command.id`, drift audit finding
/// #12 - not this row's internal `BIGSERIAL id`, returned separately
/// below and never surfaced on the domain struct - see the migration's
/// own doc comment on `commands`). Returns the new row's internal `id`,
/// needed to link the `Event`s `process_command` produced back to it (see
/// `insert_event`'s own `command_id` parameter). `encryption_key_ids` is
/// `get_or_create_encryption_key`'s own returned `id`s for
/// `command.encryption_keys` - see `insert_event_and_update_sync_projections`'s
/// own doc comment on why the domain struct alone isn't enough to link
/// the join rows.
///
/// Takes an already-open `tx` rather than opening/committing its own
/// (previously the latter) - `ProcessCommand`'s own REST/GraphQL call
/// sites now share one outer transaction across `next_sequence`'s lock,
/// this insert, and every triggered `Event`'s own insert, so the command
/// row and every one of the events it triggered commit or roll back
/// together - see `DynamicConsistencyBoundaryHonoured` and the note above
/// the rules in specs/skilj.allium.
#[tracing::instrument(skip_all)]
pub async fn insert_command(
    tx: &mut Transaction<'_, Postgres>,
    command: &Command,
    encryption_key_ids: &[i64],
) -> crate::error::Result<i64> {
    let schema = schema_ident(&command.bounded_context.name);
    let (id,): (i64,) = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.commands ({COMMAND_COLUMNS}) \
         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12) RETURNING id"
    )))
    .bind(&command.id)
    .bind(&command.command_type.name)
    .bind(&command.payload)
    .bind(&command.metadata.r#type)
    .bind(command.metadata.version)
    .bind(&command.metadata.client_id)
    .bind(command.metadata.created_at)
    .bind(&command.metadata.correlation_id)
    .bind(&command.metadata.causation_id)
    .bind(Json(&command.consistency_tags))
    .bind(command.consistency_boundary)
    .bind(Json(&command.consistency_query))
    .fetch_one(&mut **tx)
    .await?;

    // One multi-row insert via `unnest` instead of one round trip per
    // key - most commands carry zero or one, but a command whose
    // payload touches several `sensitive_field_subjects` can carry
    // several, and each used to be its own serialized `INSERT` inside
    // this transaction's own held lock (docs/architecture.md's load-test
    // §: `commit_command_batch`'s per-command critical section).
    if !encryption_key_ids.is_empty() {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.command_encryption_keys (command_id, encryption_key_id) \
             SELECT $1, unnest($2::bigint[])"
        )))
        .bind(id)
        .bind(encryption_key_ids)
        .execute(&mut **tx)
        .await?;
    }

    Ok(id)
}

#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_command_by_id(
    pool: &Pool,
    bounded_context: &str,
    id: i64,
) -> crate::error::Result<Option<Command>> {
    let schema = schema_ident(bounded_context);
    let row: Option<CommandRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {COMMAND_COLUMNS} FROM {schema}.commands WHERE id = $1"
    )))
    .bind(id)
    .fetch_optional(pool)
    .await?;
    match row {
        Some(row) => Ok(Some(row.into_domain(pool, bounded_context).await?)),
        None => Ok(None),
    }
}

/// `get_command_by_id`'s batched sibling - one `WHERE id = ANY($1)`
/// round trip for however many distinct commands a caller needs, instead
/// of one round trip (each several deep via `CommandRow::into_domain`'s
/// own `get_command_type`) per id. Built for
/// `list_events_for_bounded_context_matching_tags_with_bc`'s own
/// row-processing loop (docs/architecture.md §61's round four) - a real
/// load test found resolving each `command_triggered` row's origin one
/// at a time was the single biggest cost inside `commit_command_batch`'s
/// own held lock, and a first, *concurrent* attempt at fixing it
/// measured worse (bursting many simultaneous connection requests
/// starved the next batch's own lock acquisition) before this batched
/// version replaced it. `ids` empty returns an empty map without
/// touching Postgres. Takes `bc` (not a bounded context name) for the
/// identical "caller already has this row, don't re-fetch it" reasoning
/// `get_event_type_with_bc` gives.
async fn get_commands_by_ids_with_bc(
    conn: &mut sqlx::PgConnection,
    bc: &BoundedContext,
    ids: &[i64],
) -> crate::error::Result<std::collections::HashMap<i64, Command>> {
    if ids.is_empty() {
        return Ok(std::collections::HashMap::new());
    }
    let schema = schema_ident(&bc.name);
    let rows: Vec<CommandRowWithId> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT id, {COMMAND_COLUMNS} FROM {schema}.commands WHERE id = ANY($1)"
    )))
    .bind(ids)
    .fetch_all(&mut *conn)
    .await?;

    let mut distinct_type_names: Vec<&str> = Vec::new();
    for row in &rows {
        if !distinct_type_names.contains(&row.command_type_name.as_str()) {
            distinct_type_names.push(&row.command_type_name);
        }
    }
    let command_types = get_command_types_by_names_with_bc(conn, bc, &distinct_type_names).await?;

    let mut commands = std::collections::HashMap::with_capacity(rows.len());
    for row in rows {
        // Unlike `get_command_type`'s own lookup (see `require_command_type`),
        // `get_command_types_by_names_with_bc` queries `{schema}.command_types`
        // directly with the `bc` already in hand - no internal existence
        // recheck to silently swallow. A `hard_delete_bounded_context` race
        // dropping the schema between the `commands` query above and this one
        // surfaces as a real `sqlx::Error` from that `.await?`, not a `None`
        // reaching this lookup - so a genuine miss here is a real bug in the
        // data (a `commands` row outliving the `command_types` row it names),
        // not a race, and this stays a panic.
        let command_type = command_types
            .get(&row.command_type_name)
            .expect("commands row references a command_types row that no longer exists")
            .clone();
        commands.insert(
            row.id,
            Command {
                id: row.external_id,
                bounded_context: command_type.bounded_context.clone(),
                command_type,
                payload: row.payload,
                metadata: Metadata {
                    r#type: row.metadata_type,
                    version: row.metadata_version,
                    client_id: row.metadata_client_id,
                    created_at: row.metadata_created_at,
                    correlation_id: row.metadata_correlation_id,
                    causation_id: row.metadata_causation_id,
                },
                encryption_keys: Vec::new(),
                consistency_tags: row.consistency_tags.0,
                consistency_query: row.consistency_query.0,
                consistency_boundary: row.consistency_boundary,
            },
        );
    }
    Ok(commands)
}

/// `CommandRow`'s own sibling with the internal `BIGSERIAL` id included -
/// `get_commands_by_ids_with_bc`'s own `WHERE id = ANY($1)` needs it to
/// map each returned row back to the id that requested it, which
/// `CommandRow` itself never carries (every other caller already knows
/// the id it asked for).
#[derive(sqlx::FromRow)]
struct CommandRowWithId {
    id: i64,
    external_id: String,
    command_type_name: String,
    payload: String,
    metadata_type: String,
    metadata_version: i64,
    metadata_client_id: String,
    metadata_created_at: DateTime<Utc>,
    metadata_correlation_id: Option<String>,
    metadata_causation_id: Option<String>,
    consistency_tags: Json<Vec<Tag>>,
    consistency_boundary: Option<i64>,
    consistency_query: Json<Vec<QueryItem>>,
}

/// `get_command_type`'s batched sibling - `get_event_type_with_bc`'s own
/// precedent, extended to a whole set of names in one `WHERE name =
/// ANY($1)` round trip. `names` empty returns an empty map without
/// touching Postgres.
async fn get_command_types_by_names_with_bc(
    executor: impl sqlx::PgExecutor<'_>,
    bc: &BoundedContext,
    names: &[&str],
) -> crate::error::Result<std::collections::HashMap<String, CommandType>> {
    if names.is_empty() {
        return Ok(std::collections::HashMap::new());
    }
    let schema = schema_ident(&bc.name);
    let rows: Vec<CommandTypeRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {COMMAND_TYPE_COLUMNS} FROM {schema}.command_types WHERE name = ANY($1)"
    )))
    .bind(names)
    .fetch_all(executor)
    .await?;
    Ok(rows
        .into_iter()
        .map(|row| (row.name.clone(), row.into_domain(bc.clone())))
        .collect())
}

/// `get_command_by_id`'s own sibling, addressed by `Command.id`
/// (`commands.external_id`) instead of the internal `BIGSERIAL` - what a
/// caller holding a domain `Command.id` (the private-field mechanism's
/// own `grantPrivateFieldAccessForCommand` mutation, naming the command
/// being shared by its own wire id) needs, without knowing the internal
/// one at all.
pub async fn get_command_by_external_id(
    pool: &Pool,
    bounded_context: &str,
    external_id: &str,
) -> crate::error::Result<Option<Command>> {
    let schema = schema_ident(bounded_context);
    let row: Option<CommandRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {COMMAND_COLUMNS} FROM {schema}.commands WHERE external_id = $1"
    )))
    .bind(external_id)
    .fetch_optional(pool)
    .await?;
    match row {
        Some(row) => Ok(Some(row.into_domain(pool, bounded_context).await?)),
        None => Ok(None),
    }
}

/// Where the command `external_id` sits in its bounded context's
/// recording order - the internal `commands.id` key, which only ever
/// grows with each insert. Rule `FetchCommands`' `recorded_after`: a
/// `fetchCommands` page continues after this position. `None` when no
/// such command exists here.
pub async fn command_recording_position(
    pool: &Pool,
    bounded_context: &str,
    external_id: &str,
) -> crate::error::Result<Option<i64>> {
    let schema = schema_ident(bounded_context);
    Ok(sqlx::query_scalar(sqlx::AssertSqlSafe(format!(
        "SELECT id FROM {schema}.commands WHERE external_id = $1"
    )))
    .bind(external_id)
    .fetch_optional(pool)
    .await?)
}

#[derive(sqlx::FromRow)]
struct PositionedCommandRow {
    id: i64,
    #[sqlx(flatten)]
    row: CommandRow,
}

/// One bounded `fetchCommands` page: the bounded context's commands
/// recorded after `after_position` (`-1` for the start), in recording
/// order, `max_commands` at a time, with `select` - the rule's own pure
/// function - choosing what to serve from each chunk (given how many
/// more fit) until the page is full or history ends. Rule
/// `FetchCommands`' `first_by_recording`, the command counterpart to
/// [`collect_event_page`]. `select` runs at least once, so its own
/// validation errors surface even on an empty history.
pub async fn collect_command_page(
    pool: &Pool,
    bounded_context: &str,
    mut after_position: i64,
    max_commands: usize,
    mut select: impl FnMut(&[Command], usize) -> crate::error::Result<Vec<Command>>,
) -> crate::error::Result<Vec<Command>> {
    let chunk_size = max_commands.max(1);
    let limit = i64::try_from(chunk_size).unwrap_or(i64::MAX);
    let schema = schema_ident(bounded_context);
    let mut page = Vec::new();
    loop {
        let rows: Vec<PositionedCommandRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "SELECT id, {COMMAND_COLUMNS} FROM {schema}.commands \
             WHERE id > $1 ORDER BY id LIMIT $2"
        )))
        .bind(after_position)
        .bind(limit)
        .fetch_all(pool)
        .await?;
        let exhausted = rows.len() < chunk_size;
        if let Some(last) = rows.last() {
            after_position = last.id;
        }
        let chunk = commands_from_rows(
            pool,
            bounded_context,
            rows.into_iter().map(|p| p.row).collect(),
        )
        .await?;
        page.extend(select(&chunk, chunk_size - page.len())?);
        if page.len() >= chunk_size || exhausted {
            return Ok(page);
        }
    }
}

/// Every `Command` currently stored for a whole bounded context - the
/// full-snapshot parameter `fetch_commands`' own `bounded_context_commands`
/// expects (same treatment `list_events_for_bounded_context` gets for
/// `Event`), added propagating `skilj-graphql`'s `CommandQuery` resolver
/// (Phase 3).
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_commands_for_bounded_context(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<Vec<Command>> {
    let schema = schema_ident(bounded_context);
    let rows: Vec<CommandRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {COMMAND_COLUMNS} FROM {schema}.commands ORDER BY id"
    )))
    .fetch_all(pool)
    .await?;

    commands_from_rows(pool, bounded_context, rows).await
}

// --- Projection / ProjectionRebuild ---

#[derive(sqlx::FromRow)]
struct ProjectionRow {
    name: String,
    schema: String,
    schema_version: i64,
    sync: bool,
    caught_up_to: Option<i64>,
    requires_capability: Option<String>,
}

/// Every `EventType` a `projection_consumed_event_types`-style join table
/// names for one projection - shared by `Projection.consumed_event_types`
/// and `ProjectionRebuild`'s own field of the same name, which read from
/// the two structurally identical join tables `join_table` names.
async fn consumed_event_types(
    pool: &Pool,
    bounded_context: &str,
    join_table: &str,
    projection_name: &str,
) -> crate::error::Result<Vec<EventType>> {
    let schema = schema_ident(bounded_context);
    let names: Vec<(String,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT event_type_name FROM {schema}.{join_table} WHERE projection_name = $1"
    )))
    .bind(projection_name)
    .fetch_all(pool)
    .await?;

    let mut event_types = Vec::with_capacity(names.len());
    for (event_type_name,) in names {
        // `require_event_type`, not `.expect()`: a concurrent
        // `hard_delete_bounded_context` committing between the join
        // query above and this lookup makes `get_event_type` come back
        // `None` (its own `get_bounded_context` misses), not a real
        // dangling join row - see `require_bounded_context`.
        event_types.push(require_event_type(pool, bounded_context, &event_type_name).await?);
    }
    Ok(event_types)
}

async fn replace_consumed_event_types(
    executor: &mut sqlx::PgConnection,
    bounded_context: &str,
    join_table: &str,
    projection_name: &str,
    event_types: &[EventType],
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.{join_table} WHERE projection_name = $1"
    )))
    .bind(projection_name)
    .execute(&mut *executor)
    .await?;
    for et in event_types {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.{join_table} (projection_name, event_type_name) VALUES ($1,$2)"
        )))
        .bind(projection_name)
        .bind(&et.name)
        .execute(&mut *executor)
        .await?;
    }
    Ok(())
}

const PROJECTION_COLUMNS: &str =
    "name, schema, schema_version, sync, caught_up_to, requires_capability";

/// See `upsert_event_type` above - same upsert shape, plus replacing this
/// projection's `projection_consumed_event_types` join rows wholesale
/// (simpler and plenty fast enough for a small, admin-managed list than
/// diffing old vs. new membership).
///
/// Both statements run inside one transaction, not back-to-back on the
/// bare pool: two concurrent `upsert_projection` calls for the same
/// `projection.name` (e.g. a rolling deploy's two instances reconciling
/// at once, or - what actually surfaced this, see `skilj-demo`'s test
/// suite - two `#[test]`s racing to register the same projection) used
/// to each run their own `DELETE` then `INSERT` directly against `pool`
/// with no lock between them, so both could pass the `DELETE` before
/// either reached its `INSERT`, then both try to insert the identical
/// `(projection_name, event_type_name)` row and one loses to
/// `projection_consumed_event_types_pkey`. Wrapping the row upsert and
/// the join-table replace in a single transaction fixes this for free:
/// the `INSERT ... ON CONFLICT (name) DO UPDATE` against `projections`
/// takes (and, on the losing side, waits on) that row's lock for the
/// rest of the transaction, so a second concurrent call can't reach its
/// own `DELETE`/`INSERT` pair until the first has committed.
#[tracing::instrument(skip_all)]
pub async fn upsert_projection(pool: &Pool, projection: &Projection) -> crate::error::Result<()> {
    let mut tx = pool.begin().await?;
    upsert_projection_in_tx(&mut tx, projection).await?;
    tx.commit().await?;
    notify_registration_changed(pool).await;
    Ok(())
}

/// [`upsert_projection`] inside the caller's transaction, without the
/// commit or the registration-changed notification.
async fn upsert_projection_in_tx(
    tx: &mut Transaction<'_, Postgres>,
    projection: &Projection,
) -> crate::error::Result<()> {
    let schema = schema_ident(&projection.bounded_context.name);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.projections ({PROJECTION_COLUMNS}) \
         VALUES ($1,$2,$3,$4,$5,$6) \
         ON CONFLICT (name) DO UPDATE SET \
            schema = EXCLUDED.schema, schema_version = EXCLUDED.schema_version, \
            sync = EXCLUDED.sync, caught_up_to = EXCLUDED.caught_up_to, \
            requires_capability = EXCLUDED.requires_capability"
    )))
    .bind(&projection.name)
    .bind(&projection.schema)
    .bind(projection.schema_version)
    .bind(projection.sync)
    .bind(projection.caught_up_to)
    .bind(&projection.requires_capability)
    .execute(&mut **tx)
    .await?;
    replace_consumed_event_types(
        tx,
        &projection.bounded_context.name,
        "projection_consumed_event_types",
        &projection.name,
        &projection.consumed_event_types,
    )
    .await
}

/// Get-or-create-with-lock for one projection instance's own
/// `projection_state` row, keyed by `(projection_name, key)` - the
/// insert-or-update `insert_event_and_update_sync_projections`/
/// `catch_up_bounded_context` both need now that instances are created
/// lazily, on first touch, rather than pre-seeded at registration
/// ([§9](../../../docs/architecture.md#next-steps)'s "keyed / multi-row Projections" pass). `ON CONFLICT ... DO
/// UPDATE SET state = {schema}.projection_state.state` is a no-op write
/// on the already-exists path - it exists purely so Postgres still
/// acquires the row lock there too (the identical guarantee a plain
/// `SELECT ... FOR UPDATE` gave the old always-pre-seeded schema),
/// without ever overwriting real accumulated state with
/// `default_state_json`. Generic over `impl sqlx::PgExecutor<'_>` (the
/// same generalisation `insert_event` itself already has) so both
/// callers can run this inside their own already-open transaction.
///
/// Also returns the row's own `as_of_sequence` (issue #25's
/// investigation finding - see `apply_projection_fold_update`'s own doc
/// comment) - every caller needs it immediately after to decide whether
/// this specific row has already folded the event it's about to fold,
/// the same shape `fold_snapshot_chunk_in_tx`'s own row lock returns for
/// `Snapshot`.
async fn get_or_create_projection_state_for_update(
    executor: impl sqlx::PgExecutor<'_>,
    schema: &str,
    projection_name: &str,
    key: &str,
    default_state_json: &str,
) -> crate::error::Result<(i64, String)> {
    let (as_of_sequence, state): (i64, String) = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.projection_state (projection_name, key, state, updated_at) \
         VALUES ($1, $2, $3, now()) \
         ON CONFLICT (projection_name, key) DO UPDATE SET state = {schema}.projection_state.state \
         RETURNING as_of_sequence, state"
    )))
    .bind(projection_name)
    .bind(key)
    .bind(default_state_json)
    .fetch_one(executor)
    .await?;
    Ok((as_of_sequence, state))
}

/// Applies one projection fold's `UPDATE ... SET state = ...` - shared by
/// every "fold one event, persist the new state" call site
/// (`insert_event_and_update_sync_projections_in_tx`, the partitioned
/// catch-up, and `fold_history_into_new_sync_projection`). The
/// unpartitioned catch-up folds a chunk of events at once and writes each
/// key back in one statement of its own (docs/architecture.md §182).
/// `table` is `"projection_state"` or `"projection_rebuild_state"`;
/// `extra_where` is appended to the `WHERE` clause verbatim - `""` for the
/// live table, `" AND status = 'building'"` for the rebuild one.
///
/// Also derives and persists this instance's own `owner` column
/// alongside `state` - cross-tenant projection read fix
/// (docs/architecture.md's own write-up of this pass). When
/// `owner_tag_key` is `Some` and `event.tags` carries a tag with that
/// key *and* a non-null value, that value becomes this row's own
/// `owner`; otherwise `owner` is left exactly as already stored - an
/// event lacking the tag (or carrying it with a null value, the "mapped
/// field was absent" case - see `Tag.value` in the spec) never clears an
/// already-established owner. See `plugin::Projection::OWNER_TAG_KEY`'s
/// own doc comment for the full contract.
///
/// Also advances `as_of_sequence` to `event.sequence` (issue
/// #25's investigation finding) - every call site's own `event.sequence`
/// only ever increases within its own walk, so a plain unconditional
/// `SET` is correct here without needing a `GREATEST(...)` guard; what
/// actually makes this safe under two instances racing the same row is
/// each call site's own new pre-fold check against the value
/// `get_or_create_projection_state_for_update` just returned, *before* `dispatcher.project()` is ever called - by the
/// time this function runs, the caller has already decided this event
/// genuinely hasn't been folded into this row yet.
#[allow(clippy::too_many_arguments)]
async fn apply_projection_fold_update(
    executor: impl sqlx::PgExecutor<'_>,
    schema: &str,
    table: &str,
    extra_where: &str,
    projection_name: &str,
    key: &str,
    new_state: &str,
    owner_tag_key: Option<&str>,
    event: &Event,
) -> crate::error::Result<()> {
    match event_owner(owner_tag_key, event) {
        Some(owner) => {
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "UPDATE {schema}.{table} SET state = $1, owner = $2, as_of_sequence = $3, \
                 updated_at = now() WHERE projection_name = $4 AND key = $5{extra_where}"
            )))
            .bind(new_state)
            .bind(owner)
            .bind(event.sequence)
            .bind(projection_name)
            .bind(key)
            .execute(executor)
            .await?;
        }
        None => {
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "UPDATE {schema}.{table} SET state = $1, as_of_sequence = $2, updated_at = now() \
                 WHERE projection_name = $3 AND key = $4{extra_where}"
            )))
            .bind(new_state)
            .bind(event.sequence)
            .bind(projection_name)
            .bind(key)
            .execute(executor)
            .await?;
        }
    }
    Ok(())
}

/// The owner `event` gives a projection row: the value of its tag keyed
/// `owner_tag_key`, when it has one with a non-null value - see
/// [`apply_projection_fold_update`]. Shared with `catch_up_bounded_context`'s
/// chunked fold (docs/architecture.md §182).
fn event_owner(owner_tag_key: Option<&str>, event: &Event) -> Option<String> {
    owner_tag_key.and_then(|owner_tag_key| {
        event
            .tags
            .iter()
            .find(|tag| tag.key == owner_tag_key)
            .and_then(|tag| tag.value.clone())
    })
}

/// Set in every `snapshots.snapshot_version` this version writes: its
/// rows fold an event into every value of the tag key the event carries
/// (docs/architecture.md §202), where earlier versions folded it into the
/// first only. A row without it - written before the upgrade, or by an
/// older instance during a rolling deploy - never matches, so it is
/// treated as at an older `Snapshot::VERSION`: absent to a command, and
/// reset and refolded by catch-up when an event next touches its value.
const SNAPSHOT_EVERY_VALUE_FOLD: i64 = 1 << 40;

/// The `snapshots.snapshot_version` a row folded by this version at
/// `Snapshot::VERSION` `version` carries.
fn stored_snapshot_version(version: u64) -> i64 {
    (version as i64) | SNAPSHOT_EVERY_VALUE_FOLD
}

/// The `Snapshot::VERSION` a stored `snapshot_version` was folded at, as
/// the read functions report it: 0 for a row from before
/// [`SNAPSHOT_EVERY_VALUE_FOLD`], which no current `VERSION` trusts.
fn reported_snapshot_version(stored: i64) -> u64 {
    if stored & SNAPSHOT_EVERY_VALUE_FOLD == 0 {
        0
    } else {
        (stored & !SNAPSHOT_EVERY_VALUE_FOLD) as u64
    }
}

/// `(snapshot_version, as_of_sequence, state, updated_at)` -
/// `get_snapshot_state`'s own return shape, named to satisfy
/// `clippy::type_complexity` rather than because anything else reuses
/// it.
type SnapshotStateRow = (u64, i64, String, DateTime<Utc>);

/// One snapshot's own materialised state, JSON-encoded, alongside the
/// `snapshot_version` it was written at, the `sequence` it's folded up
/// to, and when that last happened - `None` when nothing has ever been
/// written for this `(snapshot_name, tag_key, tag_value)` triple. Every
/// caller (the GraphQL inspection endpoint, and `submit_command`'s own
/// snapshot-accelerated `decide_from_snapshot` path) treats both
/// "nothing yet" and "a stored `snapshot_version` that no longer
/// matches the currently-registered `Snapshot::VERSION`" identically -
/// a cold start, not an error - see `CommandType::decide_from_snapshot`'s
/// own doc comment. The version is reported without the every-value
/// flag the stored column carries, and as 0 for a row folded before
/// docs/architecture.md §202.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_snapshot_state(
    pool: &Pool,
    bounded_context: &str,
    snapshot_name: &str,
    tag_key: &str,
    tag_value: &str,
) -> crate::error::Result<Option<SnapshotStateRow>> {
    let schema = schema_ident(bounded_context);
    let row: Option<(i64, i64, String, DateTime<Utc>)> =
        sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT snapshot_version, as_of_sequence, state::text, updated_at FROM {schema}.snapshots \
         WHERE snapshot_name = $1 AND tag_key = $2 AND tag_value = $3"
    )))
        .bind(snapshot_name)
        .bind(tag_key)
        .bind(tag_value)
        .fetch_optional(pool)
        .await?;
    Ok(row.map(|(version, as_of_sequence, state, updated_at)| {
        (
            reported_snapshot_version(version),
            as_of_sequence,
            state,
            updated_at,
        )
    }))
}

/// `get_snapshot_state`'s own sibling, also returning the row's `owner`
/// column - cross-tenant read fix (docs/architecture.md's own write-up
/// of these passes). A separate function rather than changing
/// `get_snapshot_state`'s own return shape: that function's other
/// caller, `submit_command`'s snapshot-accelerated `decide_from_snapshot`
/// path, is a write-path internal accelerator, not a caller read -
/// deliberately untouched here, the same "`ProcessCommand`'s
/// `matching_events` is deliberately untouched" principle the raw-event
/// pass already stated. Only `snapshot_query::inspect_snapshot_field`,
/// which needs `owner` to enforce `RoleAccessMapping.scope`, calls this
/// one instead.
pub async fn get_snapshot_state_and_owner(
    pool: &Pool,
    bounded_context: &str,
    snapshot_name: &str,
    tag_key: &str,
    tag_value: &str,
) -> crate::error::Result<Option<(SnapshotStateRow, Option<String>)>> {
    type RawSnapshotStateAndOwnerRow = (i64, i64, String, DateTime<Utc>, Option<String>);
    let schema = schema_ident(bounded_context);
    let row: Option<RawSnapshotStateAndOwnerRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT snapshot_version, as_of_sequence, state::text, updated_at, owner \
         FROM {schema}.snapshots WHERE snapshot_name = $1 AND tag_key = $2 AND tag_value = $3"
    )))
    .bind(snapshot_name)
    .bind(tag_key)
    .bind(tag_value)
    .fetch_optional(pool)
    .await?;
    Ok(
        row.map(|(version, as_of_sequence, state, updated_at, owner)| {
            (
                (
                    reported_snapshot_version(version),
                    as_of_sequence,
                    state,
                    updated_at,
                ),
                owner,
            )
        }),
    )
}

/// For each `(snapshot_name, tag_key, tag_value, Snapshot::VERSION)`, in
/// order, the stored row's `(as_of_sequence, state)` when it is current -
/// folded at that `VERSION` under the every-value rule
/// ([`stored_snapshot_version`]) - and `None` when there is none or it
/// isn't. One statement for all of them (docs/architecture.md §202).
async fn get_current_snapshot_rows(
    pool: &Pool,
    bounded_context: &str,
    wanted: &[(&str, &str, &str, u64)],
) -> crate::error::Result<Vec<Option<(i64, String)>>> {
    if wanted.is_empty() {
        return Ok(Vec::new());
    }
    let schema = schema_ident(bounded_context);
    let names: Vec<&str> = wanted.iter().map(|w| w.0).collect();
    let keys: Vec<&str> = wanted.iter().map(|w| w.1).collect();
    let values: Vec<&str> = wanted.iter().map(|w| w.2).collect();
    let versions: Vec<i64> = wanted
        .iter()
        .map(|w| stored_snapshot_version(w.3))
        .collect();
    let rows: Vec<(i32, i64, String)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT w.ord::int, s.as_of_sequence, s.state::text          FROM unnest($1::text[], $2::text[], $3::text[], $4::bigint[])              WITH ORDINALITY AS w(snapshot_name, tag_key, tag_value, snapshot_version, ord)          JOIN {schema}.snapshots s ON s.snapshot_name = w.snapshot_name              AND s.tag_key = w.tag_key AND s.tag_value = w.tag_value              AND s.snapshot_version = w.snapshot_version"
    )))
    .bind(&names)
    .bind(&keys)
    .bind(&values)
    .bind(&versions)
    .fetch_all(pool)
    .await?;
    let mut found = vec![None; wanted.len()];
    for (ord, as_of_sequence, state) in rows {
        found[ord as usize - 1] = Some((as_of_sequence, state));
    }
    Ok(found)
}

/// What `submit_command`'s own snapshot-accelerated `decide_from_snapshot`
/// call needs, resolved from a stored `snapshots` row (or a cold start).
pub struct ResolvedSnapshot {
    pub state_json: String,
    pub as_of_sequence: i64,
}

/// Shared by `skilj-graphql`'s `submitCommand` resolver and `skilj-rest`'s
/// `post_commands_trigger` route ([docs/architecture.md §19](../../../docs/architecture.md#optional-snapshotting-matching-events)), so the "does
/// this command take the snapshot-accelerated path" decision lives once,
/// not duplicated per surface the way plenty of resolver-local logic
/// legitimately is elsewhere - this one has real, non-trivial rules
/// worth keeping in exactly one place.
///
/// `None` when `snapshot_name` isn't actually registered
/// (`SnapshotDispatcher::tag_key` returning `None`), or when
/// `consistency_tags` isn't *exactly* the snapshot's own single
/// `TAG_KEY` - `CommandType::snapshot()`'s own doc comment on why a
/// multi-tag command opting in is a silent fallback, not an error.
/// `Some` otherwise: a fresh/cold snapshot (nothing stored yet, or a
/// stored `snapshot_version` that no longer matches the currently-
/// registered one - "model changed", `CommandType::decide_from_snapshot`'s
/// own doc comment) resolves to `Snapshot::State::default()`,
/// JSON-encoded, at `as_of_sequence: -1` - the same cold-start shape
/// `fold_snapshot_chunk_in_tx` gives the background catch-up task.
pub async fn resolve_snapshot_context(
    pool: &Pool,
    bounded_context: &str,
    snapshot_dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    snapshot_name: &str,
    consistency_tags: &[Tag],
) -> crate::error::Result<Option<ResolvedSnapshot>> {
    let Some(tag_key) = snapshot_dispatcher.tag_key(bounded_context, snapshot_name) else {
        return Ok(None);
    };
    let [only_tag] = consistency_tags else {
        return Ok(None);
    };
    if only_tag.key != tag_key {
        return Ok(None);
    }
    let Some(tag_value) = &only_tag.value else {
        return Ok(None);
    };

    let version = snapshot_dispatcher
        .version(bounded_context, snapshot_name)
        .unwrap_or(0);
    let stored = get_current_snapshot_rows(
        pool,
        bounded_context,
        &[(snapshot_name, tag_key, tag_value.as_str(), version)],
    )
    .await?
    .pop()
    .flatten();
    let (as_of_sequence, state_json) = match stored {
        Some((as_of_sequence, state_json)) => (as_of_sequence, state_json),
        _ => (
            -1,
            snapshot_dispatcher
                .default_state(bounded_context, snapshot_name)
                .unwrap_or_default(),
        ),
    };
    Ok(Some(ResolvedSnapshot {
        state_json,
        as_of_sequence,
    }))
}

/// The background catch-up task's own progress marker for every
/// registered snapshot in one bounded context, in one query -
/// issue #15's batched replacement for what used to be a `get_snapshot_progress`
/// call per snapshot name (one query each). A name absent from the
/// returned map has never had a catch-up tick yet - `catch_up_snapshots`
/// treats that the same as this function's own predecessor did
/// (`unwrap_or(-1)` at the call site), just without a per-name round
/// trip to discover it. Plain read, no lock: only used to compute
/// `catch_up_snapshots`' own starting point for the *next* tick, never
/// to decide whether a specific write is safe - that's
/// `fold_snapshot_chunk_in_tx`'s own job, per row.
async fn list_snapshot_progress_for_bounded_context(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<std::collections::HashMap<String, i64>> {
    let schema = schema_ident(bounded_context);
    let rows: Vec<(String, i64)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT snapshot_name, caught_up_to FROM {schema}.snapshot_progress"
    )))
    .fetch_all(pool)
    .await?;
    Ok(rows.into_iter().collect())
}

/// Advances (or seeds) one snapshot's own progress marker - called once
/// per event `catch_up_snapshots` processes, for every registered
/// snapshot, regardless of whether that particular event actually
/// touched any of its rows - the identical "position always advances,
/// state only changes when consumed" treatment `Projection`'s own
/// `caught_up_to` already gets.
async fn upsert_snapshot_progress(
    executor: impl sqlx::PgExecutor<'_>,
    schema: &str,
    snapshot_name: &str,
    caught_up_to: i64,
) -> crate::error::Result<()> {
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.snapshot_progress (snapshot_name, caught_up_to) VALUES ($1, $2) \
         ON CONFLICT (snapshot_name) DO UPDATE SET caught_up_to = $2"
    )))
    .bind(snapshot_name)
    .bind(caught_up_to)
    .execute(executor)
    .await?;
    Ok(())
}

/// One projection instance's own materialised state, JSON-encoded -
/// `None` when nothing has touched this `(projection_name, key)` pair
/// yet (a legitimate, common state now that instances are created
/// lazily - a customer with no purchase history yet, say - not an
/// error; `resolvers::projection_query` falls back to
/// `ProjectionDispatcher::default_state` for it, the same value a fresh
/// instance would lazily start from).
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_projection_state(
    pool: &Pool,
    bounded_context: &str,
    projection_name: &str,
    key: &str,
) -> crate::error::Result<Option<String>> {
    let schema = schema_ident(bounded_context);
    let row: Option<(String,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT state FROM {schema}.projection_state WHERE projection_name = $1 AND key = $2"
    )))
    .bind(projection_name)
    .bind(key)
    .fetch_optional(pool)
    .await?;
    Ok(row.map(|(state,)| state))
}

/// `get_projection_state`'s own twin, also returning the row's `owner`
/// column - cross-tenant projection read fix (docs/architecture.md's own
/// write-up of this pass). A separate function rather than changing
/// `get_projection_state`'s own return shape: that function has many
/// existing callers (tests included) uninterested in `owner` at all: only
/// `projection_query`'s resolver, which needs `owner` to enforce
/// `RoleAccessMapping.scope` (see `projections::query_projection`), calls
/// this one instead. `None` for "no row at all" (an untouched key) is not
/// distinguished from `Some((state, None))` at the SQL level by this
/// function - only the caller decides what "no proven owner" versus "no
/// row yet" means for its own enforcement.
pub async fn get_projection_state_and_owner(
    pool: &Pool,
    bounded_context: &str,
    projection_name: &str,
    key: &str,
) -> crate::error::Result<Option<(String, Option<String>)>> {
    let schema = schema_ident(bounded_context);
    let row: Option<(String, Option<String>)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT state, owner FROM {schema}.projection_state \
         WHERE projection_name = $1 AND key = $2"
    )))
    .bind(projection_name)
    .bind(key)
    .fetch_optional(pool)
    .await?;
    Ok(row)
}

/// [`get_projection_state_and_owner`] for many `keys` of one projection in
/// one statement - federation's `_entities` resolves a router's whole page
/// of instances at once (docs/architecture.md §199). Keys with no row are
/// absent from the map.
pub async fn get_projection_states_and_owners(
    pool: &Pool,
    bounded_context: &str,
    projection_name: &str,
    keys: &[String],
) -> crate::error::Result<std::collections::HashMap<String, (String, Option<String>)>> {
    let schema = schema_ident(bounded_context);
    let rows: Vec<(String, String, Option<String>)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT key, state, owner FROM {schema}.projection_state \
         WHERE projection_name = $1 AND key = ANY($2)"
    )))
    .bind(projection_name)
    .bind(keys)
    .fetch_all(pool)
    .await?;
    Ok(rows
        .into_iter()
        .map(|(key, state, owner)| (key, (state, owner)))
        .collect())
}

/// A building `ProjectionRebuild`'s own materialised state, JSON-encoded,
/// for one instance/`key`. `None` when either nothing is staged at all
/// or a staged rebuild hasn't reached this key yet (`catch_up_bounded_context`
/// hasn't reached it in a poll tick yet, or the dispatcher has never
/// recognised it - see `ProjectionDispatcher::default_state`). Mirrors
/// `get_projection_state` above - for tests and anything else wanting to
/// read this row directly outside the consumer's own row-locked
/// transaction.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_projection_rebuild_state(
    pool: &Pool,
    bounded_context: &str,
    projection_name: &str,
    key: &str,
) -> crate::error::Result<Option<String>> {
    let schema = schema_ident(bounded_context);
    // Always the `'building'` row: a pending rebuild is never folded, so
    // it has no state of its own.
    let row: Option<(String,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT state FROM {schema}.projection_rebuild_state \
         WHERE projection_name = $1 AND status = 'building' AND key = $2"
    )))
    .bind(projection_name)
    .bind(key)
    .fetch_optional(pool)
    .await?;
    Ok(row.map(|(state,)| state))
}

#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
/// Just `name`'s `caught_up_to` - `None` if no such projection, `Some(None)`
/// if it has folded nothing yet. The one column `ProjectionQuery`'s
/// `waitForSequence` loop polls, in one query rather than
/// [`get_projection`]'s three (docs/architecture.md §88).
pub async fn projection_caught_up_to(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
) -> crate::error::Result<Option<Option<i64>>> {
    let schema = schema_ident(bounded_context);
    let row: Option<(Option<i64>,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT caught_up_to FROM {schema}.projections WHERE name = $1"
    )))
    .bind(name)
    .fetch_optional(pool)
    .await?;
    Ok(row.map(|(caught_up_to,)| caught_up_to))
}

pub async fn get_projection(
    pool: &Pool,
    bounded_context: &str,
    name: &str,
) -> crate::error::Result<Option<Projection>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(None);
    };
    let schema = schema_ident(bounded_context);
    let Some(row): Option<ProjectionRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {PROJECTION_COLUMNS} FROM {schema}.projections WHERE name = $1"
    )))
    .bind(name)
    .fetch_optional(pool)
    .await?
    else {
        return Ok(None);
    };
    let consumed = consumed_event_types(
        pool,
        bounded_context,
        "projection_consumed_event_types",
        name,
    )
    .await?;
    Ok(Some(Projection {
        bounded_context: bc,
        name: row.name,
        schema: row.schema,
        schema_version: row.schema_version,
        consumed_event_types: consumed,
        sync: row.sync,
        caught_up_to: row.caught_up_to,
        requires_capability: row.requires_capability,
    }))
}

/// Every `Projection` registered in one bounded context - backs
/// `TypeRegistration`'s own `exposes: for projection in
/// bounded_context.projections`. Same per-row `consumed_event_types`
/// resolution `get_projection` does, just for every row in the context's
/// own `projections` table rather than one name.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_projections_for_bounded_context(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<Vec<Projection>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(Vec::new());
    };
    let schema = schema_ident(bounded_context);
    let rows: Vec<ProjectionRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {PROJECTION_COLUMNS} FROM {schema}.projections"
    )))
    .fetch_all(pool)
    .await?;

    let mut projections = Vec::with_capacity(rows.len());
    for row in rows {
        let consumed = consumed_event_types(
            pool,
            bounded_context,
            "projection_consumed_event_types",
            &row.name,
        )
        .await?;
        projections.push(Projection {
            bounded_context: bc.clone(),
            name: row.name,
            schema: row.schema,
            schema_version: row.schema_version,
            consumed_event_types: consumed,
            sync: row.sync,
            caught_up_to: row.caught_up_to,
            requires_capability: row.requires_capability,
        });
    }
    // Name order, and part of the contract for the same reason
    // `list_bounded_contexts`'s is: `skilj-graphql`'s schema build walks
    // these in order and resolves generated type-name collisions
    // first-wins, so whichever projection survives a collision is decided
    // by the order it walks them in. Two contexts colliding needs names
    // like `a_b` + `c` against `a` + `b_c`, but one bounded context can
    // collide with itself too - a nested `{parent}_{field}` type name can
    // equal another of its own top-level names - and then the row order
    // Postgres happens to return is what decides it.
    projections.sort_by(|a, b| a.name.cmp(&b.name));
    Ok(projections)
}

/// The names of `bounded_context`'s `sync` projections - all
/// `insert_event_and_update_sync_projections_in_tx` needs of them (the
/// `ProjectionDispatcher` answers everything else by name). Every call
/// site fetches it once per commit and passes the same slice to every
/// event that commit inserts (issue #32).
///
/// Read on the caller's own transaction, after it took this bounded
/// context's `sequence` row lock: `promote_projection_rebuild` - the one
/// place a projection's `sync` flag can flip mid-flight - takes that same
/// lock before it promotes (drift audit finding #6), so the two can't
/// interleave. It must not be a separate pooled read (docs/architecture.md
/// §116): every other writer to this bounded context waits on that lock
/// holding a connection, so with a pool's worth of them waiting the
/// holder could never get a second one, and all of them failed at the
/// acquire timeout.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn sync_projection_names(
    conn: &mut sqlx::PgConnection,
    bounded_context: &str,
) -> crate::error::Result<Vec<String>> {
    let schema = schema_ident(bounded_context);
    Ok(sqlx::query_scalar(sqlx::AssertSqlSafe(format!(
        "SELECT name FROM {schema}.projections WHERE sync ORDER BY name"
    )))
    .fetch_all(conn)
    .await?)
}

#[derive(sqlx::FromRow)]
struct ProjectionRebuildRow {
    projection_name: String,
    schema: String,
    schema_version: i64,
    sync: bool,
    caught_up_to: Option<i64>,
    status: String,
}

fn projection_rebuild_status_to_str(status: ProjectionRebuildStatus) -> &'static str {
    match status {
        ProjectionRebuildStatus::Pending => "pending",
        ProjectionRebuildStatus::Building => "building",
    }
}

fn projection_rebuild_status_from_str(s: &str) -> ProjectionRebuildStatus {
    match s {
        "building" => ProjectionRebuildStatus::Building,
        _ => ProjectionRebuildStatus::Pending,
    }
}

const PROJECTION_REBUILD_COLUMNS: &str =
    "projection_name, schema, schema_version, sync, caught_up_to, status";

/// `consumed_event_types`/`replace_consumed_event_types` above's own twin
/// for `projection_rebuild_consumed_event_types` - not built on those
/// generic helpers directly, since that table now carries a `status`
/// column the plain `projections`/`projection_consumed_event_types` pair
/// never needed (see `provision_bounded_context_schema`'s own doc comment
/// on why: a pending row and a building row each need their own
/// consumed-types set, never mixed up).
async fn rebuild_consumed_event_types(
    pool: &Pool,
    bounded_context: &str,
    projection_name: &str,
    status: ProjectionRebuildStatus,
) -> crate::error::Result<Vec<EventType>> {
    let schema = schema_ident(bounded_context);
    let names: Vec<(String,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT event_type_name FROM {schema}.projection_rebuild_consumed_event_types \
         WHERE projection_name = $1 AND status = $2"
    )))
    .bind(projection_name)
    .bind(projection_rebuild_status_to_str(status))
    .fetch_all(pool)
    .await?;

    let mut event_types = Vec::with_capacity(names.len());
    for (event_type_name,) in names {
        // Same race as `consumed_event_types` above: a concurrent
        // `hard_delete_bounded_context` makes this a `RowNotFound`
        // error, not a dangling join row.
        event_types.push(require_event_type(pool, bounded_context, &event_type_name).await?);
    }
    Ok(event_types)
}

async fn replace_rebuild_consumed_event_types(
    pool: &Pool,
    bounded_context: &str,
    projection_name: &str,
    status: ProjectionRebuildStatus,
    event_types: &[EventType],
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    let status = projection_rebuild_status_to_str(status);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.projection_rebuild_consumed_event_types \
         WHERE projection_name = $1 AND status = $2"
    )))
    .bind(projection_name)
    .bind(status)
    .execute(pool)
    .await?;
    for et in event_types {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.projection_rebuild_consumed_event_types \
             (projection_name, status, event_type_name) VALUES ($1,$2,$3)"
        )))
        .bind(projection_name)
        .bind(status)
        .bind(&et.name)
        .execute(pool)
        .await?;
    }
    Ok(())
}

/// Upsert **within `rebuild.status`'s own row** - matching
/// `RegisterProjection`'s own "restaging replaces the pending row"
/// semantics (`ON CONFLICT (projection_name, status)`, not
/// `projection_name` alone - see `provision_bounded_context_schema`'s own
/// doc comment on why one projection can have both a pending and a
/// building row at once). Never call this to persist a *status
/// transition* (pending becoming building) - that would leave the old
/// row behind as a stale duplicate under its own now-wrong status instead
/// of replacing it; see `transition_projection_rebuild_to_building` for
/// that case, the only one `rebuild_projection`'s own output is ever fed
/// into.
///
/// Note that `register_projection`'s own struct-update construction
/// (`ProjectionRebuild { caught_up_to: None, ..staged.clone() }`) sets
/// `caught_up_to` back to `None` on every restage - any progress
/// `catch_up_bounded_context` had already made toward the old
/// `schema`/`consumed_event_types` is invalidated the moment this is
/// called. This function doesn't touch `projection_rebuild_state` itself,
/// since `catch_up_bounded_context` is what notices `caught_up_to = None`
/// and resets that row, using whatever the *current* dispatcher considers
/// the default (see `ProjectionDispatcher::default_state`'s own doc
/// comment for why it, not this function, has to be the one deciding
/// that value).
#[tracing::instrument(skip_all)]
pub async fn upsert_projection_rebuild(
    pool: &Pool,
    rebuild: &ProjectionRebuild,
) -> crate::error::Result<()> {
    let schema = schema_ident(&rebuild.projection.bounded_context.name);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.projection_rebuilds ({PROJECTION_REBUILD_COLUMNS}) \
         VALUES ($1,$2,$3,$4,$5,$6) \
         ON CONFLICT (projection_name, status) DO UPDATE SET \
            schema = EXCLUDED.schema, schema_version = EXCLUDED.schema_version, \
            sync = EXCLUDED.sync, caught_up_to = EXCLUDED.caught_up_to"
    )))
    .bind(&rebuild.projection.name)
    .bind(&rebuild.schema)
    .bind(rebuild.schema_version)
    .bind(rebuild.sync)
    .bind(rebuild.caught_up_to)
    .bind(projection_rebuild_status_to_str(rebuild.status))
    .execute(pool)
    .await?;
    replace_rebuild_consumed_event_types(
        pool,
        &rebuild.projection.bounded_context.name,
        &rebuild.projection.name,
        rebuild.status,
        &rebuild.consumed_event_types,
    )
    .await
}

/// Persists `rebuild_projection`'s own output - a pending row transitioning
/// to building, per `rule RebuildProjection`'s `ensures: staged.status =
/// building`. One transaction: the old `(projection_name, 'pending')` row
/// and its own join rows are deleted, and the new `(projection_name,
/// 'building')` row (`rebuild`, already carrying `status: Building`) is
/// inserted in their place - never both left behind as if this were two
/// independent rows, and never a window in which neither exists if this
/// fails partway. `ON CONFLICT (projection_name, status) DO UPDATE` on the
/// insert half is defensive, not the expected path: `RebuildProjection`'s
/// own `requires: staged.status = pending` doesn't check for an
/// *already*-building row, so a caller triggering it while one is still
/// replaying re-stages the build under the freshly toggled row rather
/// than erroring - still at most one building row afterward, satisfying
/// `UniqueRebuildPerProjectionAndStatus` either way.
#[tracing::instrument(skip_all)]
pub async fn transition_projection_rebuild_to_building(
    pool: &Pool,
    rebuild: &ProjectionRebuild,
) -> crate::error::Result<()> {
    debug_assert_eq!(
        rebuild.status,
        ProjectionRebuildStatus::Building,
        "transition_projection_rebuild_to_building's own rebuild must already carry status: \
         Building - rebuild_projection's own output does"
    );
    let mut tx = pool.begin().await?;
    let schema = schema_ident(&rebuild.projection.bounded_context.name);
    let pending = projection_rebuild_status_to_str(ProjectionRebuildStatus::Pending);

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.projection_rebuild_consumed_event_types \
         WHERE projection_name = $1 AND status = $2"
    )))
    .bind(&rebuild.projection.name)
    .bind(pending)
    .execute(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.projection_rebuilds WHERE projection_name = $1 AND status = $2"
    )))
    .bind(&rebuild.projection.name)
    .bind(pending)
    .execute(&mut *tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.projection_rebuilds ({PROJECTION_REBUILD_COLUMNS}) \
         VALUES ($1,$2,$3,$4,$5,$6) \
         ON CONFLICT (projection_name, status) DO UPDATE SET \
            schema = EXCLUDED.schema, schema_version = EXCLUDED.schema_version, \
            sync = EXCLUDED.sync, caught_up_to = EXCLUDED.caught_up_to"
    )))
    .bind(&rebuild.projection.name)
    .bind(&rebuild.schema)
    .bind(rebuild.schema_version)
    .bind(rebuild.sync)
    .bind(rebuild.caught_up_to)
    .bind(projection_rebuild_status_to_str(rebuild.status))
    .execute(&mut *tx)
    .await?;
    let building = projection_rebuild_status_to_str(rebuild.status);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.projection_rebuild_consumed_event_types \
         WHERE projection_name = $1 AND status = $2"
    )))
    .bind(&rebuild.projection.name)
    .bind(building)
    .execute(&mut *tx)
    .await?;
    for et in &rebuild.consumed_event_types {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.projection_rebuild_consumed_event_types \
             (projection_name, status, event_type_name) VALUES ($1,$2,$3)"
        )))
        .bind(&rebuild.projection.name)
        .bind(building)
        .bind(&et.name)
        .execute(&mut *tx)
        .await?;
    }

    tx.commit().await?;
    Ok(())
}

/// `None` when this projection has no rebuild staged *at this `status`* -
/// the `staged` parameter `register_projection`/`rebuild_projection`/
/// `discard_projection_rebuild` each expect "as already looked up by the
/// caller" (see their own doc comments) is always the *pending* row per
/// the spec's own `let staged = ProjectionRebuild{projection: ...,
/// status: pending}` in every one of those three rules -
/// `catch_up_bounded_context` is the one caller that asks for `Building`
/// instead.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_projection_rebuild(
    pool: &Pool,
    bounded_context: &str,
    projection_name: &str,
    status: ProjectionRebuildStatus,
) -> crate::error::Result<Option<ProjectionRebuild>> {
    let Some(projection) = get_projection(pool, bounded_context, projection_name).await? else {
        return Ok(None);
    };
    let schema = schema_ident(bounded_context);
    let Some(row): Option<ProjectionRebuildRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {PROJECTION_REBUILD_COLUMNS} FROM {schema}.projection_rebuilds \
         WHERE projection_name = $1 AND status = $2"
    )))
    .bind(projection_name)
    .bind(projection_rebuild_status_to_str(status))
    .fetch_optional(pool)
    .await?
    else {
        return Ok(None);
    };
    debug_assert_eq!(
        row.projection_name, projection_name,
        "projection_rebuilds row matched the WHERE clause but its own projection_name column disagrees"
    );
    let consumed =
        rebuild_consumed_event_types(pool, bounded_context, projection_name, status).await?;
    Ok(Some(ProjectionRebuild {
        projection,
        schema: row.schema,
        schema_version: row.schema_version,
        consumed_event_types: consumed,
        sync: row.sync,
        caught_up_to: row.caught_up_to,
        status: projection_rebuild_status_from_str(&row.status),
    }))
}

/// Persists `discard_projection_rebuild`'s outcome - the spec's own
/// `ensures` is a deletion (`not exists staged`), which that pure
/// function can't perform itself (see its own doc comment); this is the
/// caller-side deletion it hands back to. `status` is always `Pending` in
/// practice - `DiscardProjectionRebuild`'s own `staged` is a pending row
/// by definition (see `rule DiscardProjectionRebuild`'s `let`) - but a
/// real parameter rather than hardcoded, matching `get_projection_rebuild`'s
/// own shape, since the caller (not this function) is what already knows
/// which row `discard_projection_rebuild`'s own `staged` argument was.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn delete_projection_rebuild(
    pool: &Pool,
    bounded_context: &str,
    projection_name: &str,
    status: ProjectionRebuildStatus,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    let status = projection_rebuild_status_to_str(status);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.projection_rebuild_consumed_event_types \
         WHERE projection_name = $1 AND status = $2"
    )))
    .bind(projection_name)
    .bind(status)
    .execute(pool)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.projection_rebuilds WHERE projection_name = $1 AND status = $2"
    )))
    .bind(projection_name)
    .bind(status)
    .execute(pool)
    .await?;
    Ok(())
}

// --- RoleAccessMapping ---

#[derive(sqlx::FromRow)]
struct RoleAccessMappingRow {
    role_id: String,
    bounded_context: String,
    level: String,
    can_read_sensitive: bool,
    scope: Option<String>,
    capabilities: Vec<String>,
    delegable: Vec<String>,
    status: String,
    created_at: DateTime<Utc>,
    revoked_at: Option<DateTime<Utc>>,
}

impl RoleAccessMappingRow {
    /// Needs `pool` (unlike every other row type's `into_domain`) since
    /// `RoleAccessMapping` embeds a whole `Role` and a whole
    /// `BoundedContext`, not just their ids - two more queries per row.
    /// Fine for the single-row reads that use it; listings go through
    /// `mappings_from_rows` instead, which batches both
    /// (docs/architecture.md §126).
    ///
    /// `Ok(None)`, not a panic, when the role or bounded context this
    /// row points to is gone by the time the follow-up query runs:
    /// `hard_delete_bounded_context`'s `DROP SCHEMA`+`DELETE` and its
    /// `ON DELETE CASCADE` onto this very table mean no *committed*
    /// state ever has a `role_access_mappings` row outliving its
    /// `bounded_contexts` row - but this method's own initial `SELECT`
    /// and this follow-up lookup are two separate, unsynchronized
    /// queries, not one snapshot, so a concurrent hard delete landing
    /// in that gap is exactly this: a row this method legitimately read
    /// a moment ago, now legitimately gone. Treating that as "wasn't in
    /// the snapshot after all" rather than panicking is the same call
    /// `list_role_access_mappings`'s "gone by the time you look" case
    /// deserves anywhere it's read without a shared transaction.
    async fn into_domain(self, pool: &Pool) -> crate::error::Result<Option<RoleAccessMapping>> {
        let Some(role) = get_role(pool, &self.role_id).await? else {
            return Ok(None);
        };
        let Some(bounded_context) = get_bounded_context(pool, &self.bounded_context).await? else {
            return Ok(None);
        };
        Ok(Some(RoleAccessMapping {
            role,
            bounded_context,
            level: access_level_from_str(&self.level),
            can_read_sensitive: self.can_read_sensitive,
            scope: self.scope,
            capabilities: self.capabilities.into_iter().collect(),
            delegable: self.delegable.into_iter().collect(),
            status: role_status_from_str(&self.status),
            created_at: self.created_at,
            revoked_at: self.revoked_at,
        }))
    }
}

const ROLE_ACCESS_MAPPING_COLUMNS: &str =
    "role_id, bounded_context, level, can_read_sensitive, scope, capabilities, delegable, \
     status, created_at, revoked_at";

#[tracing::instrument(skip_all)]
pub async fn insert_role_access_mapping<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    mapping: &RoleAccessMapping,
) -> crate::error::Result<()> {
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO role_access_mappings ({ROLE_ACCESS_MAPPING_COLUMNS}) \
         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)"
    )))
    .bind(&mapping.role.id)
    .bind(&mapping.bounded_context.name)
    .bind(access_level_to_str(mapping.level))
    .bind(mapping.can_read_sensitive)
    .bind(&mapping.scope)
    .bind(mapping.capabilities.iter().collect::<Vec<_>>())
    .bind(mapping.delegable.iter().collect::<Vec<_>>())
    .bind(role_status_to_str(mapping.status))
    .bind(mapping.created_at)
    .bind(mapping.revoked_at)
    .execute(executor)
    .await?;
    Ok(())
}

/// `None` when this `(role, bounded_context)` pair has no *active*
/// mapping - a revoked one (if any) doesn't count, matching every rule
/// in `access_control` that reads "the" mapping for a pair
/// (`grant_role_access_mapping`'s `DuplicateActiveMapping` check,
/// `revoke_role_access_mapping`'s own lookup). The partial unique index
/// on `(role_id, bounded_context) WHERE status = 'active'` guarantees at
/// most one row can ever match.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_active_role_access_mapping(
    pool: &Pool,
    role_id: &str,
    bounded_context: &str,
) -> crate::error::Result<Option<RoleAccessMapping>> {
    let row: Option<RoleAccessMappingRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {ROLE_ACCESS_MAPPING_COLUMNS} FROM role_access_mappings \
         WHERE role_id = $1 AND bounded_context = $2 AND status = 'active'"
    )))
    .bind(role_id)
    .bind(bounded_context)
    .fetch_optional(pool)
    .await?;
    match row {
        Some(row) => row.into_domain(pool).await,
        None => Ok(None),
    }
}

/// Most capabilities one grant may hold, and most it may delegate
/// (`invariant CapabilitiesAreWellFormed`). Enforced here too, in the
/// statement that adds one, so two concurrent grants cannot both pass a
/// count each read before the other wrote.
pub const MAX_CAPABILITIES_PER_MAPPING: usize = 16;

/// Add `capability` to the active mapping's `capabilities`, in one
/// statement: `true` when it was added, `false` when the mapping is
/// gone or revoked, already holds it, or already holds
/// [`MAX_CAPABILITIES_PER_MAPPING`].
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn add_mapping_capability<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    role_id: &str,
    bounded_context: &str,
    capability: &str,
) -> crate::error::Result<bool> {
    let done = sqlx::query(
        "UPDATE role_access_mappings SET capabilities = array_append(capabilities, $1) \
         WHERE role_id = $2 AND bounded_context = $3 AND status = 'active' \
         AND NOT ($1 = ANY(capabilities)) AND cardinality(capabilities) < $4",
    )
    .bind(capability)
    .bind(role_id)
    .bind(bounded_context)
    .bind(MAX_CAPABILITIES_PER_MAPPING as i32)
    .execute(executor)
    .await?;
    Ok(done.rows_affected() == 1)
}

/// Remove `capability` from the active mapping's `capabilities`: `true`
/// when it was held and is now gone.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn remove_mapping_capability<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    role_id: &str,
    bounded_context: &str,
    capability: &str,
) -> crate::error::Result<bool> {
    let done = sqlx::query(
        "UPDATE role_access_mappings SET capabilities = array_remove(capabilities, $1) \
         WHERE role_id = $2 AND bounded_context = $3 AND status = 'active' \
         AND $1 = ANY(capabilities)",
    )
    .bind(capability)
    .bind(role_id)
    .bind(bounded_context)
    .execute(executor)
    .await?;
    Ok(done.rows_affected() == 1)
}

/// Replace the active mapping's `delegable` set: `true` when the mapping
/// was active and so changed, `false` when the mapping is gone or revoked
/// or the set is over [`MAX_CAPABILITIES_PER_MAPPING`]. The size guard is
/// enforced again here, in the statement itself, so an oversized set is
/// refused even if the caller's own check were bypassed - the same
/// defense-in-depth [`add_mapping_capability`] takes.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn set_mapping_delegable<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    role_id: &str,
    bounded_context: &str,
    delegable: &std::collections::BTreeSet<String>,
) -> crate::error::Result<bool> {
    let done = sqlx::query(
        "UPDATE role_access_mappings SET delegable = $1 \
         WHERE role_id = $2 AND bounded_context = $3 AND status = 'active' \
         AND cardinality($1) <= $4",
    )
    .bind(delegable.iter().collect::<Vec<_>>())
    .bind(role_id)
    .bind(bounded_context)
    .bind(MAX_CAPABILITIES_PER_MAPPING as i32)
    .execute(executor)
    .await?;
    Ok(done.rows_affected() == 1)
}

// --- the access trail (docs/architecture.md §229) ---

/// The `admin` bounded context, which every trail event is written to.
/// An error rather than a skipped write when it is missing: a change that
/// cannot be recorded is not made.
#[tracing::instrument(skip_all)]
pub async fn require_admin_bounded_context(pool: &Pool) -> crate::error::Result<BoundedContext> {
    require_bounded_context(pool, crate::bootstrap::ADMIN_BOUNDED_CONTEXT_NAME).await
}

/// `rule RecordAccessEvent`: appends `change` to the admin bounded
/// context on `tx`, so it commits or rolls back with the change it
/// describes. The admin context's `sequence` row lock is held until `tx`
/// ends, which is what keeps its log gapless. Not broadcast and not put in
/// the event cache: nothing subscribes to these, and a read that misses
/// the cache falls back to the database.
#[tracing::instrument(skip_all, fields(kind = change.kind.name()))]
pub async fn record_access_event(
    tx: &mut Transaction<'_, Postgres>,
    admin: &BoundedContext,
    change: AccessChange,
) -> crate::error::Result<()> {
    let sequence = next_sequence(&mut **tx, &admin.name).await?;
    let event = change.into_event(admin, sequence, Utc::now());
    insert_event(&mut **tx, &event, None).await
}

/// `GrantRoleAccessMapping`/`CreateBoundedContextFromTemplate`'s write:
/// inserts the mapping and records `AccessGranted` in one transaction.
/// `actor_role_id` is the granting Role, `None` for a grant no Role made
/// (local mode's seed). `insert_role_access_mapping` alone writes no
/// trail; startup's baseline (`baseline_access_events`) covers a row made
/// that way.
#[tracing::instrument(skip_all)]
pub async fn grant_role_access_mapping_with_trail(
    pool: &Pool,
    mapping: &RoleAccessMapping,
    actor_role_id: Option<&str>,
) -> crate::error::Result<()> {
    let admin = require_admin_bounded_context(pool).await?;
    let mut tx = pool.begin().await?;
    insert_role_access_mapping(&mut *tx, mapping).await?;
    record_access_event(
        &mut tx,
        &admin,
        AccessChange::granted(mapping, actor_role_id),
    )
    .await?;
    tx.commit().await?;
    Ok(())
}

/// `RevokeRoleAccessMapping`'s write: revokes the active mapping and
/// records `AccessRevoked` in one transaction. Nothing is recorded when
/// there was no active mapping to revoke (two requests racing, a stale
/// list): `false`, as for [`change_mapping_capability_with_trail`].
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn revoke_role_access_mapping_with_trail(
    pool: &Pool,
    role_id: &str,
    bounded_context: &str,
    revoked_at: DateTime<Utc>,
    actor_role_id: &str,
) -> crate::error::Result<bool> {
    let admin = require_admin_bounded_context(pool).await?;
    let mut tx = pool.begin().await?;
    if !revoke_active_role_access_mapping(&mut *tx, role_id, bounded_context, revoked_at).await? {
        return Ok(false);
    }
    record_access_event(
        &mut tx,
        &admin,
        AccessChange::revoked(role_id, bounded_context, actor_role_id, false),
    )
    .await?;
    tx.commit().await?;
    Ok(true)
}

/// The capability mutations' write: applies the grant or revoke and, only
/// when it applied, records the event in the same transaction. `false`
/// when a concurrent change got there first (nothing is recorded).
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn change_mapping_capability_with_trail(
    pool: &Pool,
    role_id: &str,
    bounded_context: &str,
    capability: &str,
    grant: bool,
    actor_role_id: &str,
    via_admin: bool,
) -> crate::error::Result<bool> {
    let admin = require_admin_bounded_context(pool).await?;
    let mut tx = pool.begin().await?;
    let applied = if grant {
        add_mapping_capability(&mut *tx, role_id, bounded_context, capability).await?
    } else {
        remove_mapping_capability(&mut *tx, role_id, bounded_context, capability).await?
    };
    if !applied {
        return Ok(false);
    }
    record_access_event(
        &mut tx,
        &admin,
        AccessChange::capability(
            grant,
            role_id,
            bounded_context,
            actor_role_id,
            capability,
            via_admin,
        ),
    )
    .await?;
    tx.commit().await?;
    Ok(true)
}

/// `SetDelegableCapabilities`' write, with its `DelegableCapabilitiesSet`
/// event in the same transaction.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn set_mapping_delegable_with_trail(
    pool: &Pool,
    role_id: &str,
    bounded_context: &str,
    delegable: &std::collections::BTreeSet<String>,
    actor_role_id: &str,
) -> crate::error::Result<bool> {
    let admin = require_admin_bounded_context(pool).await?;
    let mut tx = pool.begin().await?;
    if !set_mapping_delegable(&mut *tx, role_id, bounded_context, delegable).await? {
        return Ok(false);
    }
    record_access_event(
        &mut tx,
        &admin,
        AccessChange::delegable_set(role_id, bounded_context, actor_role_id, delegable),
    )
    .await?;
    tx.commit().await?;
    Ok(true)
}

/// Registers the access event types in the admin bounded context
/// (`rule RegisterAccessEventTypes`): each missing one is added, and one
/// already registered gets its schema brought up to date when the library
/// describes it differently now (a release that adds an optional payload
/// field, say), so the stored schema never lags what is written. Nothing
/// else about a registered type is touched, and a restart with nothing new
/// changes nothing. Must run after the per-context startup patches, since
/// the rows carry columns they add.
#[tracing::instrument(skip_all)]
pub async fn register_access_event_types(pool: &Pool) -> crate::error::Result<()> {
    let admin = require_admin_bounded_context(pool).await?;
    for kind in AccessEventKind::ALL {
        let wanted = crate::access_trail::access_event_type(&admin, kind);
        let current = get_event_type(pool, &admin.name, kind.name()).await?;
        let up_to_date = current.as_ref().is_some_and(|current| {
            let parse = |schema: &str| serde_json::from_str::<serde_json::Value>(schema).ok();
            parse(&current.schema).is_some() && parse(&current.schema) == parse(&wanted.schema)
        });
        if !up_to_date {
            upsert_event_type(pool, &wanted).await?;
        }
    }
    Ok(())
}

/// The admin context's `events.origin_kind` check, widened to accept
/// `skilj_recorded`. Only the admin context's table is changed: it is the
/// only one that holds such events, and leaving every other context's
/// check as it was keeps a large events table from being rescanned. Runs
/// the `ALTER` only while the check lacks the value (docs/architecture.md
/// §158).
#[tracing::instrument(skip_all)]
pub async fn ensure_admin_events_origin_kind(pool: &Pool) -> crate::error::Result<()> {
    let schema = schema_ident(crate::bootstrap::ADMIN_BOUNDED_CONTEXT_NAME);
    let mut tx = pool.begin().await?;
    // Instances starting together take turns: the second finds the check
    // already widened. (Without the lock a constraint dropped by the first
    // reads back as NULL to the second's catalog query.)
    sqlx::query("SELECT pg_advisory_xact_lock(hashtext('skilj_admin_events_origin_kind'))")
        .execute(&mut *tx)
        .await?;
    let current: Option<(String, Option<String>)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT conname::text, pg_get_constraintdef(oid) FROM pg_constraint \
         WHERE conrelid = '{schema}.events'::regclass AND contype = 'c' \
         AND pg_get_constraintdef(oid) LIKE '%origin_kind%'"
    )))
    .fetch_optional(&mut *tx)
    .await?;
    let Some((name, definition)) = current else {
        return Ok(());
    };
    if definition.is_some_and(|definition| definition.contains("skilj_recorded")) {
        return Ok(());
    }
    let name = name.replace('"', "\"\"");
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "ALTER TABLE {schema}.events DROP CONSTRAINT \"{name}\""
    )))
    .execute(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "ALTER TABLE {schema}.events ADD CONSTRAINT events_origin_kind_check CHECK (\
         origin_kind IN ('external_triggered', 'directly_created', 'command_triggered', \
         'system_triggered', 'skilj_recorded'))"
    )))
    .execute(&mut *tx)
    .await?;
    tx.commit().await?;
    Ok(())
}

/// The whole of the trail's startup: the admin events table accepts
/// `skilj_recorded`, the access trail's event types and the master-key
/// trail's (docs/architecture.md §230) are registered, and every grant
/// without history is baselined. Returns how many it baselined. Needs the
/// admin bounded context to exist.
#[tracing::instrument(skip_all)]
pub async fn ensure_access_trail(pool: &Pool) -> crate::error::Result<usize> {
    ensure_admin_events_origin_kind(pool).await?;
    register_access_event_types(pool).await?;
    register_master_key_event_types(pool).await?;
    baseline_access_events(pool).await
}

/// `rule BaselineAccessEvents`: one `AccessBaselined` event for each
/// active mapping that has no access event yet, recording what it holds
/// now. Safe to repeat and safe to run on several instances at once: each
/// baseline re-checks under the admin context's `sequence` row lock, so
/// the loser finds the winner's event and writes nothing. Returns how many
/// it wrote.
#[tracing::instrument(skip_all)]
pub async fn baseline_access_events(pool: &Pool) -> crate::error::Result<usize> {
    let admin = require_admin_bounded_context(pool).await?;
    let schema = schema_ident(&admin.name);
    let mut written = 0;
    for listed in list_role_access_mappings(pool).await? {
        if listed.status != RoleStatus::Active {
            continue;
        }
        let mut tx = pool.begin().await?;
        // The mapping row first, as every writer does (a revoke or a
        // capability change locks the row, then takes the sequence lock):
        // the other order deadlocks. Re-read under that lock, because the
        // listing above is stale by now: a grant revoked or deleted since
        // is not ours to baseline, and one whose capabilities changed
        // must be baselined with what it holds now.
        let row: Option<RoleAccessMappingRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "SELECT {ROLE_ACCESS_MAPPING_COLUMNS} FROM role_access_mappings \
             WHERE role_id = $1 AND bounded_context = $2 AND status = 'active' FOR UPDATE"
        )))
        .bind(&listed.role.id)
        .bind(&listed.bounded_context.name)
        .fetch_optional(&mut *tx)
        .await?;
        let Some(row) = row else {
            continue;
        };
        let mapping = RoleAccessMapping {
            level: access_level_from_str(&row.level),
            can_read_sensitive: row.can_read_sensitive,
            scope: row.scope,
            capabilities: row.capabilities.into_iter().collect(),
            delegable: row.delegable.into_iter().collect(),
            ..listed
        };
        // The lock `next_sequence` takes, taken next: the existence check
        // below then cannot race another instance's baseline.
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "SELECT next_value FROM {schema}.sequence FOR UPDATE"
        )))
        .execute(&mut *tx)
        .await?;
        // Covered means the trail already says the grant is held, not that
        // some event names it: a grant a raw writer made and a capability
        // change then touched has a `CapabilityGranted` and no start, and
        // one raw-re-granted after an `AccessRevoked` folds to not held.
        let records =
            access_event_records(&mut *tx, &mapping.role.id, &mapping.bounded_context.name).await?;
        if fold_access_events(&records, DateTime::<Utc>::MAX_UTC).held {
            continue;
        }
        record_access_event(&mut tx, &admin, AccessChange::baselined(&mapping)).await?;
        tx.commit().await?;
        written += 1;
    }
    Ok(written)
}

/// Every access event for one grant, oldest first (`AccessHistory` folds
/// them).
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_access_event_records(
    pool: &Pool,
    role_id: &str,
    bounded_context: &str,
) -> crate::error::Result<Vec<AccessEventRecord>> {
    access_event_records(pool, role_id, bounded_context).await
}

/// [`list_access_event_records`] on any executor, so the baseline can read
/// a grant's history inside the transaction that holds the admin context's
/// sequence lock. One grant's history is one tagged read: the events whose
/// `role` tag is the Role and whose `bounded_context` tag is the context,
/// through `event_tags` (§210) rather than a scan of the payloads. A row
/// that does not parse is an error, not a gap: an audit read that silently
/// dropped a revocation would answer wrongly.
async fn access_event_records<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    role_id: &str,
    bounded_context: &str,
) -> crate::error::Result<Vec<AccessEventRecord>> {
    let schema = schema_ident(crate::bootstrap::ADMIN_BOUNDED_CONTEXT_NAME);
    let rows: Vec<(String, String, DateTime<Utc>)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT e.event_type_name, e.payload, e.metadata_created_at FROM {schema}.events e \
         WHERE e.sequence IN (SELECT sequence FROM {schema}.event_tags \
             WHERE tag_key = 'role' AND tag_value = $2 AND event_type_name = ANY($1)) \
         AND e.sequence IN (SELECT sequence FROM {schema}.event_tags \
             WHERE tag_key = 'bounded_context' AND tag_value = $3 AND event_type_name = ANY($1)) \
         ORDER BY e.sequence"
    )))
    .bind(
        AccessEventKind::ALL
            .iter()
            .filter(|kind| kind.is_mapping_event())
            .map(|kind| kind.name())
            .collect::<Vec<_>>(),
    )
    .bind(role_id)
    .bind(bounded_context)
    .fetch_all(executor)
    .await?;
    Ok(rows
        .into_iter()
        .map(|(name, payload, created_at)| {
            let kind = AccessEventKind::from_name(&name).ok_or_else(|| {
                sqlx::Error::Decode(format!("{name} is not an access event type").into())
            })?;
            let payload =
                serde_json::from_str(&payload).map_err(|e| sqlx::Error::Decode(e.into()))?;
            Ok(AccessEventRecord {
                kind,
                payload,
                created_at,
            })
        })
        .collect::<Result<Vec<_>, sqlx::Error>>()?)
}

/// Every `RoleAccessMapping` this engine currently knows of, active or
/// not - the full-snapshot parameter `grant_role_access_mapping`'s own
/// `existing_mappings` expects (see its doc comment). Same "small,
/// admin-managed, unscoped is fine" reasoning as `list_roles`. A row
/// whose role or bounded context was concurrently hard-deleted between
/// this method's own `SELECT` and `RoleAccessMappingRow::into_domain`'s
/// follow-up lookups is silently dropped, not an error - see that
/// method's own doc comment.
#[tracing::instrument(skip_all)]
pub async fn list_role_access_mappings(
    pool: &Pool,
) -> crate::error::Result<Vec<RoleAccessMapping>> {
    let rows: Vec<RoleAccessMappingRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {ROLE_ACCESS_MAPPING_COLUMNS} FROM role_access_mappings"
    )))
    .fetch_all(pool)
    .await?;
    mappings_from_rows(pool, rows, None).await
}

/// Every active `RoleAccessMapping` on `bounded_context` - what every
/// GraphQL resolver returning a `BoundedContext` shows with it
/// (`boundedContexts` for every context). It used to list every mapping
/// in the deployment and filter, at two queries per mapping
/// (docs/architecture.md §126).
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context.name))]
pub async fn list_active_role_access_mappings_for_bounded_context(
    pool: &Pool,
    bounded_context: &BoundedContext,
) -> crate::error::Result<Vec<RoleAccessMapping>> {
    let rows: Vec<RoleAccessMappingRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {ROLE_ACCESS_MAPPING_COLUMNS} FROM role_access_mappings \
         WHERE bounded_context = $1 AND status = 'active' ORDER BY id"
    )))
    .bind(&bounded_context.name)
    .fetch_all(pool)
    .await?;
    mappings_from_rows(pool, rows, Some(bounded_context)).await
}

/// `RoleAccessMappingRow::into_domain` for many rows at once: every Role
/// they name in one query, and each distinct bounded context once
/// (`known`, when the caller already has it, not at all), instead of both
/// per row. A row naming a Role or bounded context that's gone is skipped,
/// as `into_domain` skips it.
async fn mappings_from_rows(
    pool: &Pool,
    rows: Vec<RoleAccessMappingRow>,
    known: Option<&BoundedContext>,
) -> crate::error::Result<Vec<RoleAccessMapping>> {
    if rows.is_empty() {
        return Ok(Vec::new());
    }
    let mut role_ids: Vec<&str> = rows.iter().map(|r| r.role_id.as_str()).collect();
    role_ids.sort_unstable();
    role_ids.dedup();
    let roles: std::collections::HashMap<String, Role> =
        sqlx::query_as::<_, RoleRow>(sqlx::AssertSqlSafe(format!(
            "SELECT {ROLE_COLUMNS} FROM roles WHERE id = ANY($1)"
        )))
        .bind(&role_ids)
        .fetch_all(pool)
        .await?
        .into_iter()
        .map(|row| {
            let role = row.into_domain();
            (role.id.clone(), role)
        })
        .collect();

    let mut contexts: std::collections::HashMap<String, Option<BoundedContext>> =
        std::collections::HashMap::new();
    if let Some(bc) = known {
        contexts.insert(bc.name.clone(), Some(bc.clone()));
    }
    for row in &rows {
        if !contexts.contains_key(&row.bounded_context) {
            let bc = get_bounded_context(pool, &row.bounded_context).await?;
            contexts.insert(row.bounded_context.clone(), bc);
        }
    }

    Ok(rows
        .into_iter()
        .filter_map(|row| {
            Some(RoleAccessMapping {
                role: roles.get(&row.role_id)?.clone(),
                bounded_context: contexts.get(&row.bounded_context)?.clone()?,
                level: access_level_from_str(&row.level),
                can_read_sensitive: row.can_read_sensitive,
                scope: row.scope,
                capabilities: row.capabilities.into_iter().collect(),
                delegable: row.delegable.into_iter().collect(),
                status: role_status_from_str(&row.status),
                created_at: row.created_at,
                revoked_at: row.revoked_at,
            })
        })
        .collect())
}

/// The names of the bounded contexts `role_id` has an active mapping to -
/// just the names, for the per-caller GraphQL schema
/// (docs/architecture.md §138), which needs nothing else.
pub async fn list_accessible_bounded_context_names(
    pool: &Pool,
    role_id: &str,
) -> crate::error::Result<std::collections::BTreeSet<String>> {
    let names: Vec<String> = sqlx::query_scalar(
        "SELECT DISTINCT bounded_context FROM role_access_mappings \
         WHERE role_id = $1 AND status = 'active'",
    )
    .bind(role_id)
    .fetch_all(pool)
    .await?;
    Ok(names.into_iter().collect())
}

/// What `role_id` may see of each bounded context it has an active
/// mapping to: the name and the capabilities that mapping holds. For the
/// per-caller GraphQL schema, which leaves a projection out for a caller
/// not holding the capability it requires (docs/architecture.md §228).
pub async fn list_accessible_grants(
    pool: &Pool,
    role_id: &str,
) -> crate::error::Result<Vec<(String, Vec<String>)>> {
    Ok(sqlx::query_as(
        "SELECT bounded_context, capabilities FROM role_access_mappings \
         WHERE role_id = $1 AND status = 'active'",
    )
    .bind(role_id)
    .fetch_all(pool)
    .await?)
}

/// Every currently-*active* `RoleAccessMapping` for one `Role` - the
/// `active_mappings` parameter `revoke_role` expects (see its own doc
/// comment: "as already looked up by the caller").
#[tracing::instrument(skip_all)]
pub async fn list_active_role_access_mappings_for_role(
    pool: &Pool,
    role_id: &str,
) -> crate::error::Result<Vec<RoleAccessMapping>> {
    let rows: Vec<RoleAccessMappingRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {ROLE_ACCESS_MAPPING_COLUMNS} FROM role_access_mappings \
         WHERE role_id = $1 AND status = 'active'"
    )))
    .bind(role_id)
    .fetch_all(pool)
    .await?;
    mappings_from_rows(pool, rows, None).await
}

/// Persists a `revoke_role_access_mapping` (or `revoke_role`'s own
/// cascade) outcome directly, by the same unambiguous `(role_id,
/// bounded_context, status = 'active')` triple `get_active_role_access_mapping`
/// reads by - safe without needing a synthetic id, since at most one row
/// can ever match (see the migration's own partial unique index). `impl
/// PgExecutor` - same reasoning as `update_role`'s own doc comment.
/// `true` when an active mapping was revoked, `false` when there was none
/// (already revoked by a concurrent request, or never made): the trail
/// records a revocation only on `true`.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn revoke_active_role_access_mapping<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    role_id: &str,
    bounded_context: &str,
    revoked_at: DateTime<Utc>,
) -> crate::error::Result<bool> {
    let done = sqlx::query(
        "UPDATE role_access_mappings SET status = 'revoked', revoked_at = $1 \
         WHERE role_id = $2 AND bounded_context = $3 AND status = 'active'",
    )
    .bind(revoked_at)
    .bind(role_id)
    .bind(bounded_context)
    .execute(executor)
    .await?;
    Ok(done.rows_affected() == 1)
}

/// `rule RevokeRole`'s own atomic whole - the role's own status update
/// and every one of its now-`revoked` `RoleAccessMapping`s, in one
/// transaction (drift audit P4 batch: this used to run as N+1 separate
/// autocommit statements - `update_role` then one `revoke_active_role_access_mapping`
/// per mapping - so a crash or a database error partway through could
/// leave a role revoked with some of its own mappings still active, or
/// the reverse. Mirrors the "one transaction, single commit" shape
/// `submit_command` already establishes for the identical reason -
/// `RevokedRoleImpliesMappingsRevoked` now holds for real, not just when
/// nothing goes wrong partway through.
#[tracing::instrument(skip_all)]
pub async fn revoke_role_and_mappings(
    pool: &Pool,
    role: &Role,
    mappings: &[RoleAccessMapping],
    actor_role_id: &str,
) -> crate::error::Result<()> {
    let admin = require_admin_bounded_context(pool).await?;
    let mut tx = pool.begin().await?;
    update_role(&mut *tx, role).await?;
    for mapping in mappings {
        let revoked_at = mapping
            .revoked_at
            .expect("revoke_role always stamps revoked_at on every mapping it returns");
        if !revoke_active_role_access_mapping(
            &mut *tx,
            &role.id,
            &mapping.bounded_context.name,
            revoked_at,
        )
        .await?
        {
            continue;
        }
        record_access_event(
            &mut tx,
            &admin,
            AccessChange::revoked(&role.id, &mapping.bounded_context.name, actor_role_id, true),
        )
        .await?;
    }
    tx.commit().await?;
    Ok(())
}

// --- next_sequence ---

/// Backs the `next_sequence` black box (see the note above rule
/// `CreateExternalEvent` and `event_store::create_external_event`'s own
/// doc comment): allocates the next `Event.sequence` for a bounded
/// context, serialised via the row lock the `UPDATE ... RETURNING`
/// acquires - concurrent callers block on it rather than racing to the
/// same value. The context's own `{schema}.sequence` row is seeded once,
/// at provisioning time (see `provision_bounded_context_schema`), so this
/// is a plain `UPDATE` - no more insert-if-missing step needed now that a
/// bounded context can't exist at all without one.
///
/// Generic over `sqlx::PgExecutor` rather than `&Pool` specifically -
/// every real call site now passes `&mut *tx` from an already-open
/// transaction, so this row's own lock is held for that whole
/// transaction rather than released the instant this one statement's
/// implicit autocommit finishes (see the note above the rules: "locked
/// ... as part of the same transaction that inserts the new Command/
/// Event rows, then incremented and released on commit" - the gaplessness
/// guarantee this gives depends on that, not on this function alone). A
/// bare `&Pool` still works too (autocommit, the pre-fix behaviour) -
/// every direct `db::next_sequence(&pool, ...)` test call keeps compiling
/// unchanged.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn next_sequence<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<i64> {
    let schema = schema_ident(bounded_context);
    let (next,): (i64,) = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.sequence SET next_value = next_value + 1 RETURNING next_value"
    )))
    .fetch_one(executor)
    .await?;
    Ok(next)
}

/// `next_sequence`'s own batch form - one command triggering several
/// events (`CommandDecision::Accepted { events }` with more than one
/// `EventSpec`) used to call `next_sequence` once per event, each its own
/// round trip to Postgres, all of them while `submit_command`'s own
/// bounded-context lock is held (issue #32: that lock hold
/// duration, not pool size, is what caps real-world write throughput).
/// This claims the whole range in one `UPDATE ... RETURNING`, exactly the
/// same row-lock-based serialisation as the single-value form (already
/// held by the `SELECT ... FOR UPDATE` every real caller takes first), so
/// the semantics are identical - just one round trip for `count` sequence
/// numbers instead of `count` of them. `count == 0` short-circuits without
/// touching the row at all, since `next_value + 0` would still be a wasted
/// round trip for a command whose decision produced no events.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn next_sequence_batch<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
    count: i64,
) -> crate::error::Result<Vec<i64>> {
    if count == 0 {
        return Ok(Vec::new());
    }
    let schema = schema_ident(bounded_context);
    let (last,): (i64,) = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.sequence SET next_value = next_value + $1 RETURNING next_value"
    )))
    .bind(count)
    .fetch_one(executor)
    .await?;
    Ok(((last - count + 1)..=last).collect())
}

/// The identity of `bounded_context`'s `events` table (its OID) together
/// with [`latest_sequence`], in one round trip. Hard-deleting a bounded
/// context drops its schema and frees the name for reuse, and recreating
/// it creates a new table with a new OID - so anything keyed by the *name*
/// (the event cache's windows) can tell a successor from its predecessor,
/// which sequences alone can't (docs/architecture.md §95).
///
/// The identity includes the database's [`Epoch`] too (docs/architecture.md
/// §176): a promoted standby keeps the table's OID, but its log can end
/// before the old primary's did, and the sequences past that end are
/// reused for different events.
///
/// The same round trip also stamps the bounded context's type
/// registrations ([`RegistrationsStamp`]), so the event cache notices a
/// re-registration - by any instance - before serving events that carry
/// copies of the old one (docs/architecture.md §180). The stamp is
/// `registrations_generation`'s counter (§189); a bounded context without
/// one - provisioned by an older instance mid rolling deploy, and not yet
/// patched by a restart - is stamped by hashing its registrations instead.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn events_table_identity(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<EventsTableState> {
    let schema = schema_ident(bounded_context);
    let identity = |registrations: String| {
        format!(
            "SELECT '{schema}.events'::regclass::oid::bigint, \
                    (SELECT MAX(sequence) FROM {schema}.events), {EPOCH_SQL}, ({registrations})"
        )
    };
    let counted = sqlx::query_as(sqlx::AssertSqlSafe(identity(format!(
        "SELECT 'g' || generation FROM {schema}.registrations_generation"
    ))))
    .fetch_one(pool)
    .await;
    let (oid, max, epoch, registrations): (i64, Option<i64>, String, String) = match counted {
        Err(sqlx::Error::Database(e)) if e.code().as_deref() == Some("42P01") => {
            sqlx::query_as(sqlx::AssertSqlSafe(identity(format!(
                "SELECT (SELECT md5(coalesce(string_agg((to_jsonb(t) - 'schema' \
                    - 'schedule_position' - 'last_fired_at')::text, ',' ORDER BY t.name), '')) \
                 FROM {schema}.event_types t) \
                || (SELECT md5(coalesce(string_agg((to_jsonb(c) - 'schema')::text, ',' \
                    ORDER BY c.name), '')) FROM {schema}.command_types c)"
            ))))
            .fetch_one(pool)
            .await?
        }
        counted => counted?,
    };
    Ok(EventsTableState {
        table: TableIdentity {
            oid,
            epoch: Epoch(epoch),
        },
        latest: max,
        registrations: RegistrationsStamp(registrations),
    })
}

/// What [`events_table_identity`] reads in its one round trip.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EventsTableState {
    pub table: TableIdentity,
    /// [`latest_sequence`].
    pub latest: Option<i64>,
    pub registrations: RegistrationsStamp,
}

/// A fingerprint of a bounded context's `EventType`/`CommandType`
/// registrations: it changes whenever a declaration does
/// (`private_fields`, `owner_tag_key`, `tag_mappings`, ...). A scheduled
/// fire moves only `schedule_position`/`last_fired_at`, which don't count,
/// so firing doesn't look like a re-registration (docs/architecture.md
/// §180). Normally `registrations_generation`'s counter (§189), else a hash
/// of the registrations - see [`events_table_identity`]. Compared for
/// equality, never parsed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RegistrationsStamp(String);

/// Which `events` table, on which history, a set of events came from -
/// see [`events_table_identity`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TableIdentity {
    pub oid: i64,
    pub epoch: Epoch,
}

/// The database's epoch: its system identifier and current timeline,
/// `"{system_identifier}-{timeline}"` (docs/architecture.md §176). A
/// promoted standby keeps the system identifier but starts a new
/// timeline, and so does a point-in-time restore; a fresh cluster (a
/// dump restored elsewhere) has a new system identifier. In each case the
/// log may end before positions held outside the database - a client's
/// `after`, a bridge's consumed batch, a broker's acknowledged offset -
/// and later sequences are reused for different events, so a position is
/// only meaningful together with the epoch it was read in. Opaque to
/// clients: compared for equality, never parsed.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Epoch(String);

impl Epoch {
    /// An epoch a client handed back, to compare against [`current_epoch`].
    pub fn from_client(epoch: impl Into<String>) -> Self {
        Self(epoch.into())
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }
}

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

/// The SQL expression for [`Epoch`]. Both functions are executable by
/// every role by default. The timeline comes from the current WAL file's
/// name: it changes the moment a standby is promoted, where
/// `pg_control_checkpoint()`'s only changes at the next checkpoint. Valid
/// on a primary only, which is the only server skilj talks to.
///
/// `pg_control_system()` reads `global/pg_control` under `ControlFileLock`
/// on every call, and this runs on every event-cache freshen, so the
/// system identifier is kept in a session setting the first time and read
/// from there after (docs/architecture.md §195): it can't change for one
/// session, which is always connected to the same server. `nullif` because
/// `DISCARD ALL` (a pooler's reset) leaves the setting empty, not unset.
const EPOCH_SQL: &str = "coalesce(nullif(current_setting('skilj.system_identifier', true), ''), \
     set_config('skilj.system_identifier', \
         (SELECT system_identifier::text FROM pg_control_system()), false)) \
     || '-' || substr(pg_walfile_name(pg_current_wal_lsn()), 1, 8)";

/// The database's current [`Epoch`] - on a transaction's connection, the
/// epoch of the server that transaction commits on.
pub async fn current_epoch<'e>(executor: impl sqlx::PgExecutor<'e>) -> crate::error::Result<Epoch> {
    let (epoch,): (String,) = sqlx::query_as(sqlx::AssertSqlSafe(format!("SELECT {EPOCH_SQL}")))
        .fetch_one(executor)
        .await?;
    Ok(Epoch(epoch))
}

/// Refuses `supplied` - an epoch a client read a position in - unless it
/// is `current` (docs/architecture.md §176). `None` passes: a client that
/// sends no epoch is served as before.
pub fn require_epoch(supplied: Option<&str>, current: &Epoch) -> crate::error::Result<()> {
    match supplied {
        Some(supplied) if supplied != current.as_str() => {
            Err(crate::event_store::Error::EpochChanged {
                supplied: supplied.to_string(),
                current: current.to_string(),
            }
            .into())
        }
        _ => Ok(()),
    }
}

/// [`latest_sequence`] and [`current_epoch`] in one round trip, so both
/// come from the same server: what a client-supplied position is checked
/// against (docs/architecture.md §148, §176).
pub async fn latest_sequence_and_epoch(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<(Option<i64>, Epoch)> {
    let schema = schema_ident(bounded_context);
    let (max, epoch): (Option<i64>, String) = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT (SELECT MAX(sequence) FROM {schema}.events), {EPOCH_SQL}"
    )))
    .fetch_one(pool)
    .await?;
    Ok((max, Epoch(epoch)))
}

/// Records `epoch` as the last one seen and returns the one recorded
/// before it, when it differs - `None` the first time and while it's
/// unchanged. Of several instances noticing the same change, only the
/// first gets it back, so it's reported once (docs/architecture.md §176).
pub async fn record_epoch(
    pool: &Pool,
    epoch: &Epoch,
    now: DateTime<Utc>,
) -> crate::error::Result<Option<Epoch>> {
    let previous: Option<(Option<String>,)> = sqlx::query_as(
        "WITH previous AS (SELECT epoch FROM skilj_epoch WHERE id = 1) \
         INSERT INTO skilj_epoch (id, epoch, recorded_at) VALUES (1, $1, $2) \
         ON CONFLICT (id) DO UPDATE SET epoch = EXCLUDED.epoch, recorded_at = EXCLUDED.recorded_at \
         WHERE skilj_epoch.epoch <> EXCLUDED.epoch \
         RETURNING (SELECT epoch FROM previous)",
    )
    .bind(epoch.as_str())
    .bind(now)
    .fetch_optional(pool)
    .await?;
    Ok(previous.and_then(|(previous,)| previous).map(Epoch))
}

/// The highest `sequence` currently committed in a bounded context -
/// `None` when it has no events at all yet. `catch_up_bounded_context`'s
/// own cheap first check every poll tick, so a quiet context (nothing
/// since the last tick) costs one small aggregate query, not a full event
/// reload - `list_events_for_bounded_context_from` only ever runs once
/// this comes back higher than everything that still needs catching up.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn latest_sequence(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<Option<i64>> {
    let schema = schema_ident(bounded_context);
    let (max,): (Option<i64>,) = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT MAX(sequence) FROM {schema}.events"
    )))
    .fetch_one(pool)
    .await?;
    Ok(max)
}

// --- Event ---

/// One row's origin, for `get_event_by_sequence`'s single-row read -
/// reads of many rows resolve origins in one batch through
/// `events_from_rows` instead (docs/architecture.md §125). Async, unlike
/// every other `*_from_row`/`*_to_str` helper in this module, because
/// `command_triggered` needs a second query - `EventOrigin::CommandTriggered`
/// embeds a whole `Command` by value (see the migration's own doc
/// comment on `commands`), not just an id.
async fn event_origin_from_row(
    pool: &Pool,
    bounded_context: &str,
    kind: &str,
    source_content: Option<String>,
    source_context: Option<String>,
    command_id: Option<i64>,
) -> crate::error::Result<EventOrigin> {
    Ok(match kind {
        "external_triggered" => EventOrigin::ExternalTriggered {
            source_content: source_content
                .expect("external_triggered event row without origin_source_content"),
            source_context,
        },
        "directly_created" => EventOrigin::DirectlyCreated,
        "system_triggered" => EventOrigin::SystemTriggered,
        "skilj_recorded" => EventOrigin::SkiljRecorded,
        "command_triggered" => {
            let command_id =
                command_id.expect("command_triggered event row without origin_command_id");
            let command = require_command(pool, bounded_context, command_id).await?;
            EventOrigin::CommandTriggered {
                command: Box::new(command),
            }
        }
        other => EventOrigin::Unknown {
            kind: other.to_string(),
        },
    })
}

/// Every `Event` currently stored for one `(bounded_context, event_type)`
/// pair, ordered by `sequence` - the full-snapshot parameter
/// `fetch_events`/`consume_events` each expect (see their own doc
/// comments). `list_events_cached` below is what their own real REST
/// call sites use instead (`crate::event_cache`'s own module doc
/// comment); this function is its unconditional-load fallback, and
/// still used directly wherever the whole type's history is genuinely
/// wanted regardless of recency.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_events(
    pool: &Pool,
    bounded_context: &str,
    event_type_name: &str,
) -> crate::error::Result<Vec<Event>> {
    let bc = require_bounded_context(pool, bounded_context).await?;
    let et = require_event_type(pool, bounded_context, event_type_name).await?;

    let schema = schema_ident(bounded_context);
    let rows: Vec<EventRowAnyType> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, metadata_client_id, \
         metadata_created_at, metadata_correlation_id, metadata_causation_id, tags, \
         origin_kind, origin_source_content, origin_source_context, \
         origin_command_id FROM {schema}.events WHERE event_type_name = $1 ORDER BY sequence"
    )))
    .bind(event_type_name)
    .fetch_all(pool)
    .await?;

    let known = std::collections::HashMap::from([(et.name.clone(), et)]);
    events_from_rows(&mut *pool.acquire().await?, &bc, rows, Some(&known)).await
}

#[derive(sqlx::FromRow)]
struct EventRowAnyType {
    event_type_name: String,
    sequence: i64,
    payload: String,
    metadata_type: String,
    metadata_version: i64,
    metadata_client_id: String,
    metadata_created_at: DateTime<Utc>,
    // issue #18 - `None` only for a row written before these
    // columns existed.
    metadata_correlation_id: Option<String>,
    metadata_causation_id: Option<String>,
    tags: Json<Vec<Tag>>,
    origin_kind: String,
    origin_source_content: Option<String>,
    origin_source_context: Option<String>,
    origin_command_id: Option<i64>,
}

/// Every `Event` currently stored for a whole bounded context, across
/// every `EventType`, ordered by `sequence` - the full-snapshot parameter
/// `consistency_boundary_and_matching_events` (and so
/// `event_store::process_command`) expects for `bounded_context_events`,
/// per §1.7's own persistence note. Unlike `list_events` above, a given
/// row's `EventType` isn't known ahead of the query, so each distinct
/// `event_type_name` seen is resolved once and cached for the rest of
/// this call rather than reloaded per row.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_events_for_bounded_context(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<Vec<Event>> {
    let bc = require_bounded_context(pool, bounded_context).await?;

    let schema = schema_ident(bounded_context);
    let rows: Vec<EventRowAnyType> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, \
         metadata_client_id, metadata_created_at, metadata_correlation_id, \
         metadata_causation_id, tags, origin_kind, origin_source_content, \
         origin_source_context, origin_command_id FROM {schema}.events ORDER BY sequence"
    )))
    .fetch_all(pool)
    .await?;

    events_from_rows(&mut *pool.acquire().await?, &bc, rows, None).await
}

/// Every `Event` committed after `after_sequence`, ordered by `sequence`.
/// `catch_up_bounded_context`'s own bounded load, unlike
/// `list_events_for_bounded_context` above's "always reload everything"
/// shape. Same per-row resolution as that function, just with a `WHERE`
/// clause and a starting point.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_events_for_bounded_context_from(
    pool: &Pool,
    bounded_context: &str,
    after_sequence: i64,
) -> crate::error::Result<Vec<Event>> {
    let bc = require_bounded_context(pool, bounded_context).await?;

    let schema = schema_ident(bounded_context);
    let rows: Vec<EventRowAnyType> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, \
         metadata_client_id, metadata_created_at, metadata_correlation_id, \
         metadata_causation_id, tags, origin_kind, origin_source_content, \
         origin_source_context, origin_command_id FROM {schema}.events \
         WHERE sequence > $1 ORDER BY sequence"
    )))
    .bind(after_sequence)
    .fetch_all(pool)
    .await?;

    events_from_rows(&mut *pool.acquire().await?, &bc, rows, None).await
}

/// `list_events_for_bounded_context_from`'s own capped sibling -
/// issue #25's `catch_up_partitioned_projection` is the one
/// caller (`MAX_EVENTS_PER_PARTITION_TICK`'s own doc comment explains
/// why it needs a cap that function's other caller, `catch_up_snapshots`,
/// doesn't). A separate function rather than an optional `limit`
/// parameter added to `list_events_for_bounded_context_from` itself, so
/// that function's existing, unrelated caller stays untouched.
pub async fn list_events_for_bounded_context_from_limited(
    pool: &Pool,
    bounded_context: &str,
    after_sequence: i64,
    limit: i64,
) -> crate::error::Result<Vec<Event>> {
    let bc = require_bounded_context(pool, bounded_context).await?;

    let schema = schema_ident(bounded_context);
    let rows: Vec<EventRowAnyType> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, \
         metadata_client_id, metadata_created_at, metadata_correlation_id, \
         metadata_causation_id, tags, origin_kind, origin_source_content, \
         origin_source_context, origin_command_id FROM {schema}.events \
         WHERE sequence > $1 ORDER BY sequence LIMIT $2"
    )))
    .bind(after_sequence)
    .bind(limit)
    .fetch_all(pool)
    .await?;

    events_from_rows(&mut *pool.acquire().await?, &bc, rows, None).await
}

/// Tag-indexed sibling of `list_events_for_bounded_context`/`_from` -
/// [docs/architecture.md §19](../../../docs/architecture.md#optional-snapshotting-matching-events)'s "Problem 1" fix. Those two always fetch
/// the *whole* bounded context and leave tag-matching to the caller's
/// own in-memory filter (`consistency_boundary_and_matching_events`'s
/// own union semantics) - fine while a bounded context is small, but a
/// full unfiltered scan on every command submission once it isn't. This
/// pushes the same union-of-tags matching down into the query itself,
/// through `event_tags` (docs/architecture.md §210; §19's GIN index on
/// `events.tags` before it) - one sub-select per wanted tag, their union,
/// optionally further bounded by `sequence > after_sequence` (folds in
/// both `queryEvents`' own pagination and `submit_command`'s
/// DCB-conflict redispatch check, which needs the identical "tag-scoped
/// and newer than X" shape - see that function's own call site).
///
/// An empty `tags` slice returns `Ok(vec![])` without ever touching
/// Postgres - mirrors `consistency_boundary_and_matching_events`'s own
/// "no `tag_mappings` declared" case exactly, so a `CommandType`/
/// `EventType` with no tags sees no behavioural change at all.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_events_for_bounded_context_matching_tags(
    pool: &Pool,
    bounded_context: &str,
    tags: &[Tag],
    after_sequence: Option<i64>,
) -> crate::error::Result<Vec<Event>> {
    if tags.is_empty() {
        return Ok(Vec::new());
    }

    let bc = require_bounded_context(pool, bounded_context).await?;
    list_events_for_bounded_context_matching_tags_with_bc(
        &mut *pool.acquire().await?,
        &bc,
        tags,
        after_sequence,
        None,
        None,
    )
    .await
}

/// The same query [`list_events_for_bounded_context_matching_tags`] runs,
/// for a caller that already has the `BoundedContext` row in hand and
/// would otherwise be re-fetching it redundantly - `submit_one_command_in_tx`'s
/// own per-command DCB-conflict delta check is exactly that caller: every
/// command in a `CommandBatcher` batch shares the identical bounded
/// context (that's what the batch's own queue is keyed on), and
/// `command_type.bounded_context` is already that same row, loaded once
/// when the command type itself was resolved - re-fetching it (plus,
/// transitively, `get_role` for its `created_by_role_id`) once per
/// command in a large, self-tuning batch was pure round-trip waste sitting
/// inside the batch leader's own held lock.
async fn list_events_for_bounded_context_matching_tags_with_bc(
    conn: &mut sqlx::PgConnection,
    bc: &BoundedContext,
    tags: &[Tag],
    after_sequence: Option<i64>,
    known_event_types: Option<&std::collections::HashMap<String, EventType>>,
    limit: Option<i64>,
) -> crate::error::Result<Vec<Event>> {
    if tags.is_empty() {
        return Ok(Vec::new());
    }

    let schema = schema_ident(&bc.name);
    // One `event_tags` sub-select per wanted tag, their union the events'
    // sequences (docs/architecture.md §210). Parameters: each tag's key and
    // value, then the position and the limit.
    let mut binds: Vec<Option<String>> = Vec::new();
    let types = all_event_types(&schema);
    let after_param = 2 * tags.len() + 1;
    let limit_param = after_param + usize::from(after_sequence.is_some());
    let filter = match after_sequence {
        Some(_) => format!(" AND t.sequence > ${after_param}::bigint"),
        None => String::new(),
    };
    let selects: Vec<String> = tags
        .iter()
        .map(|tag| {
            binds.push(Some(tag.key.clone()));
            let key = format!("${}", binds.len());
            let value = match &tag.value {
                Some(value) => {
                    binds.push(Some(value.clone()));
                    format!("= ${}", binds.len())
                }
                None => {
                    // Keeps the parameter numbering fixed.
                    binds.push(None);
                    format!("IS NULL AND ${}::text IS NULL", binds.len())
                }
            };
            event_tags_select(
                &schema,
                &key,
                &value,
                &types,
                &filter,
                limit.map(|_| (TagOrder::Oldest, format!("${limit_param}::bigint"))),
            )
        })
        .collect();
    let limit_clause = match limit {
        Some(_) => format!(" LIMIT ${limit_param}::bigint"),
        None => String::new(),
    };
    let sql = format!(
        "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, \
         metadata_client_id, metadata_created_at, metadata_correlation_id, \
         metadata_causation_id, tags, origin_kind, origin_source_content, \
         origin_source_context, origin_command_id FROM {schema}.events \
         WHERE sequence = ANY(ARRAY({})) ORDER BY sequence{limit_clause}",
        selects.join(" UNION ")
    );
    let mut query = sqlx::query_as::<_, EventRowAnyType>(sqlx::AssertSqlSafe(sql));
    for bind in binds {
        query = query.bind(bind);
    }
    if let Some(after_sequence) = after_sequence {
        query = query.bind(after_sequence);
    }
    if let Some(limit) = limit {
        query = query.bind(limit);
    }
    let rows: Vec<EventRowAnyType> = query.fetch_all(&mut *conn).await?;

    events_from_rows(conn, bc, rows, known_event_types).await
}

/// The statements built from [`event_tags_select`] read the events as
/// `sequence = ANY(ARRAY(<sub-selects>))`, not `sequence IN (...)`
/// (docs/architecture.md §210). With `IN`, Postgres chose a join from row
/// estimates, and the generic plan it settles on after a few executions
/// of a statement - planned for a tag with a few events - took 2.5 times
/// as long on a long-lived tag. An array leaves it one plan: primary-key
/// lookups, in sequence order.
///
/// Which end of a tag's matches [`event_tags_select`] keeps, when it keeps
/// only some.
#[derive(Clone, Copy)]
enum TagOrder {
    /// The first matches - a chunk of a read in sequence order.
    Oldest,
    /// The last matches - an item with `latest`.
    Newest,
}

/// Every event type `schema`'s bounded context registers, as a SQL array:
/// what a tag read with no types of its own probes `event_tags` for. A
/// superset of the type of any event, which `events.event_type_name`
/// references (docs/architecture.md §210). Evaluated once per statement.
fn all_event_types(schema: &str) -> String {
    format!("ARRAY(SELECT name FROM {schema}.event_types)")
}

/// A sub-select of the sequences in `event_tags` carrying the tag `key`
/// (`value_condition` on its value) with one of `types`, and `filter` -
/// `AND` conditions on `t`, its position and any further tags - in no
/// particular order (docs/architecture.md §210).
///
/// The index is `(tag_key, tag_value, event_type_name, sequence)`, so a
/// tag's events are in sequence order within each type, not across them.
/// Without `limit` that doesn't matter: one index range per type. With
/// it - an item's `latest`, or a chunk - each type's range is read from
/// the wanted end, `limit` entries at most, through a lateral join, and
/// the per-type results are cut to `limit` again. Ordering the whole
/// tag instead would read every entry of a long-lived tag to keep one.
fn event_tags_select(
    schema: &str,
    key: &str,
    value_condition: &str,
    types: &str,
    filter: &str,
    limit: Option<(TagOrder, String)>,
) -> String {
    match limit {
        None => format!(
            "(SELECT t.sequence FROM {schema}.event_tags t \
             WHERE t.tag_key = {key} AND t.tag_value {value_condition} \
             AND t.event_type_name = ANY({types}){filter})"
        ),
        Some((order, limit)) => {
            let direction = match order {
                TagOrder::Oldest => "",
                TagOrder::Newest => " DESC",
            };
            format!(
                "(SELECT l.sequence FROM unnest({types}) AS ty(name) \
                 CROSS JOIN LATERAL (SELECT t.sequence FROM {schema}.event_tags t \
                    WHERE t.tag_key = {key} AND t.tag_value {value_condition} \
                    AND t.event_type_name = ty.name{filter} \
                    ORDER BY t.sequence{direction} LIMIT {limit}) l \
                 ORDER BY l.sequence{direction} LIMIT {limit})"
            )
        }
    }
}

/// The events of `bc` matching `query`, after `after_sequence` when given,
/// in sequence order - an item with `latest` contributes only that many
/// of its matches, the newest (docs/architecture.md §198). One statement, so one snapshot: the
/// union of one sub-select per item.
///
/// An item with tags is read through `event_tags`: an index probe on its
/// first tag and each of its types - every registered type when it names
/// none - each other tag checked on the event it finds. That is what keeps
/// "the latest lifecycle event of this company" one probe per type however
/// many other events carry the company's tag (docs/architecture.md §210).
/// One with types and no tags goes through `events_by_type`.
///
/// The statement's text depends only on the shape of `query` - how many
/// items, which kinds, how many tags, and whether a tag's value is null -
/// so a command type always sends the same few to the statement cache.
async fn list_events_matching_query_with_bc(
    conn: &mut sqlx::PgConnection,
    bc: &BoundedContext,
    query: &[QueryItem],
    after_sequence: Option<i64>,
    known_event_types: Option<&std::collections::HashMap<String, EventType>>,
) -> crate::error::Result<Vec<Event>> {
    list_events_matching_items_with_bc(
        conn,
        bc,
        query,
        &vec![after_sequence; query.len()],
        known_event_types,
    )
    .await
}

/// [`list_events_matching_query_with_bc`] with a position of its own per
/// item: `afters[i]` for `query[i]`. A snapshot item reads its tag value's
/// events after the stored row's `as_of_sequence`, the other items their
/// whole history, in the one statement (docs/architecture.md §202). The
/// result is every event some item matched past that item's position.
async fn list_events_matching_items_with_bc(
    conn: &mut sqlx::PgConnection,
    bc: &BoundedContext,
    query: &[QueryItem],
    afters: &[Option<i64>],
    known_event_types: Option<&std::collections::HashMap<String, EventType>>,
) -> crate::error::Result<Vec<Event>> {
    if query.is_empty() {
        return Ok(Vec::new());
    }
    let schema = schema_ident(&bc.name);
    enum Bind {
        Text(Option<String>),
        Texts(Vec<String>),
        Json(String),
        Sequence(i64),
    }
    let mut binds: Vec<Bind> = Vec::new();
    let param = |binds: &mut Vec<Bind>, bind: Bind| {
        binds.push(bind);
        format!("${}", binds.len())
    };
    // One parameter per distinct position, so a query with one position
    // for every item sends the statement it always did.
    let mut positions: Vec<(i64, String)> = Vec::new();
    let mut selects = Vec::with_capacity(query.len());
    for (item, item_after) in query.iter().zip(afters) {
        let after = item_after.map(|after| {
            match positions.iter().find(|(position, _)| *position == after) {
                Some((_, placeholder)) => placeholder.clone(),
                None => {
                    let placeholder =
                        format!("{}::bigint", param(&mut binds, Bind::Sequence(after)));
                    positions.push((after, placeholder.clone()));
                    placeholder
                }
            }
        });
        let after_clause = |column: &str| match &after {
            Some(after) => format!(" AND {column} > {after}"),
            None => String::new(),
        };
        let latest = |binds: &mut Vec<Bind>, column: &str| match item.latest {
            Some(count) => format!(
                " ORDER BY {column} DESC LIMIT {}",
                param(binds, Bind::Sequence(i64::from(count)))
            ),
            None => String::new(),
        };
        let select = match (item.event_types.is_empty(), item.tags.split_first()) {
            (no_types, Some((first, rest))) => {
                let key = param(&mut binds, Bind::Text(Some(first.key.clone())));
                let value = match &first.value {
                    Some(value) => {
                        format!("= {}", param(&mut binds, Bind::Text(Some(value.clone()))))
                    }
                    None => "IS NULL".to_string(),
                };
                // Without types, every type the bounded context registers:
                // a superset of any event's, which `events.event_type_name`
                // references (docs/architecture.md §210).
                let types = if no_types {
                    all_event_types(&schema)
                } else {
                    format!(
                        "{}::text[]",
                        param(&mut binds, Bind::Texts(item.event_types.clone()))
                    )
                };
                let rest = if rest.is_empty() {
                    String::new()
                } else {
                    let tags = param(
                        &mut binds,
                        Bind::Json(
                            serde_json::to_string(rest).expect("Tag serialisation is infallible"),
                        ),
                    );
                    format!(
                        " AND EXISTS (SELECT 1 FROM {schema}.events r \
                         WHERE r.sequence = t.sequence AND r.tags @> {tags}::jsonb)"
                    )
                };
                let latest = item.latest.map(|count| {
                    (
                        TagOrder::Newest,
                        param(&mut binds, Bind::Sequence(i64::from(count))),
                    )
                });
                event_tags_select(
                    &schema,
                    &key,
                    &value,
                    &types,
                    &format!("{}{rest}", after_clause("t.sequence")),
                    latest,
                )
            }
            (false, None) => {
                let types = param(&mut binds, Bind::Texts(item.event_types.clone()));
                format!(
                    "(SELECT sequence FROM {schema}.events \
                     WHERE event_type_name = ANY({types}::text[]){}{})",
                    after_clause("sequence"),
                    latest(&mut binds, "sequence"),
                )
            }
            // Matches nothing (`QueryItem::matches`): refused by `build()`,
            // and derived only for an item no event can match.
            (true, None) => continue,
        };
        selects.push(select);
    }
    if selects.is_empty() {
        return Ok(Vec::new());
    }
    let sql = format!(
        "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, \
         metadata_client_id, metadata_created_at, metadata_correlation_id, \
         metadata_causation_id, tags, origin_kind, origin_source_content, \
         origin_source_context, origin_command_id FROM {schema}.events \
         WHERE sequence = ANY(ARRAY({})) ORDER BY sequence",
        selects.join(" UNION ")
    );
    let mut statement = sqlx::query_as::<_, EventRowAnyType>(sqlx::AssertSqlSafe(sql));
    for bind in binds {
        statement = match bind {
            Bind::Text(text) => statement.bind(text),
            Bind::Texts(texts) => statement.bind(texts),
            Bind::Json(json) => statement.bind(json),
            Bind::Sequence(sequence) => statement.bind(sequence),
        };
    }
    let rows: Vec<EventRowAnyType> = statement.fetch_all(&mut *conn).await?;
    events_from_rows(conn, bc, rows, known_event_types).await
}

/// The snapshot state `item` reads, when it is a snapshot item whose tag
/// derived a value: the entry of `states` for its snapshot and value.
fn snapshot_state_of<'s>(
    item: &QueryItem,
    states: &'s [crate::plugin::SnapshotState],
) -> Option<&'s crate::plugin::SnapshotState> {
    let (Some(name), [tag]) = (&item.snapshot, item.tags.as_slice()) else {
        return None;
    };
    let value = tag.value.as_deref()?;
    states
        .iter()
        .find(|state| state.snapshot == *name && state.tag_value == value)
}

/// Folds every event of `events` (in sequence order) past a state's
/// `folded_through` into each of `states` it belongs to - an event
/// matching a snapshot item of `query` for that snapshot and value - with
/// the snapshot's own fold for that value (docs/architecture.md §202).
fn fold_into_snapshot_states(
    snapshots: &dyn crate::plugin::SnapshotDispatcher,
    bounded_context: &str,
    query: &[QueryItem],
    states: &mut [crate::plugin::SnapshotState],
    events: &[Event],
) -> crate::error::Result<()> {
    for event in events {
        for state in states.iter_mut() {
            if event.sequence <= state.folded_through {
                continue;
            }
            let belongs = query.iter().any(|item| {
                item.snapshot.as_deref() == Some(state.snapshot.as_str())
                    && item.tags.first().and_then(|t| t.value.as_deref())
                        == Some(state.tag_value.as_str())
                    && item.matches(event)
            });
            if !belongs {
                continue;
            }
            let folded = snapshots
                .fold_value(
                    bounded_context,
                    &state.snapshot,
                    &state.tag_value,
                    &state.state_json,
                    event,
                )
                .ok_or_else(|| unregistered_snapshot(&state.snapshot))??;
            state.state_json = folded;
            state.folded_through = event.sequence;
        }
    }
    Ok(())
}

fn unregistered_snapshot(name: &str) -> crate::error::Error {
    crate::error::Error::configuration(format!(
        "a consistency_query() item names snapshot {name}, which this instance doesn't register"
    ))
}

/// A command's read before the lock when its query has snapshot items
/// (docs/architecture.md §202). The stored rows of every snapshot and tag
/// value the items derive come first, in one statement; a row that is
/// missing, or at another `Snapshot::VERSION`, is the default state at -1.
/// Then one read of every item: a snapshot item past its row's
/// `as_of_sequence`, the others their whole history - from the event
/// cache when its window holds everything after the lowest of those
/// positions, else from Postgres. The events past each state's position
/// are folded into it. Returns the events read, the position the read is
/// complete through, and the states.
async fn read_query_with_snapshots(
    pool: &Pool,
    cache: &crate::event_cache::EventCache,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    bounded_context: &str,
    query: &[QueryItem],
) -> crate::error::Result<(Vec<Event>, i64, Vec<crate::plugin::SnapshotState>)> {
    let Some(snapshots) = dispatcher.snapshots() else {
        let name = query
            .iter()
            .find_map(|item| item.snapshot.as_deref())
            .unwrap_or_default();
        return Err(unregistered_snapshot(name));
    };
    let mut wanted: Vec<(&str, &str, &str, u64)> = Vec::new();
    for item in query {
        let (Some(name), [tag]) = (&item.snapshot, item.tags.as_slice()) else {
            continue;
        };
        let Some(value) = tag.value.as_deref() else {
            continue;
        };
        if wanted.iter().any(|w| w.0 == name && w.2 == value) {
            continue;
        }
        let version = snapshots
            .version(bounded_context, name)
            .ok_or_else(|| unregistered_snapshot(name))?;
        wanted.push((name, tag.key.as_str(), value, version));
    }
    let rows = get_current_snapshot_rows(pool, bounded_context, &wanted).await?;
    let mut states = Vec::with_capacity(wanted.len());
    for ((name, _, value, _), row) in wanted.iter().zip(rows) {
        let (folded_through, state_json) = match row {
            Some(row) => row,
            None => (
                -1,
                snapshots
                    .default_state(bounded_context, name)
                    .ok_or_else(|| unregistered_snapshot(name))?,
            ),
        };
        states.push(crate::plugin::SnapshotState {
            snapshot: name.to_string(),
            tag_value: value.to_string(),
            state_json,
            folded_through,
        });
    }

    let afters: Vec<Option<i64>> = query
        .iter()
        .map(|item| snapshot_state_of(item, &states).map(|state| state.folded_through))
        .collect();
    let lowest = afters.iter().map(|a| a.unwrap_or(-1)).min().unwrap_or(-1);
    let past_its_item = |event: &Event| {
        query
            .iter()
            .zip(&afters)
            .any(|(item, after)| item.matches(event) && event.sequence > after.unwrap_or(-1))
    };
    let (events, covered_through) = match cache
        .try_events_matching_query(pool, bounded_context, query, lowest)
        .await?
    {
        Some((events, covered_through)) => (
            events.into_iter().filter(|e| past_its_item(e)).collect(),
            covered_through,
        ),
        None => {
            let (covered_through, bc) = futures_util::try_join!(
                latest_sequence(pool, bounded_context),
                require_bounded_context(pool, bounded_context),
            )?;
            let events = list_events_matching_items_with_bc(
                &mut *pool.acquire().await?,
                &bc,
                query,
                &afters,
                None,
            )
            .await?;
            (events, covered_through.unwrap_or(-1))
        }
    };
    fold_into_snapshot_states(snapshots, bounded_context, query, &mut states, &events)?;
    Ok((events, covered_through, states))
}

/// `list_events_matching_query_with_bc` for a command's read before the
/// lock: cache first, then Postgres, returning the position the read is
/// complete through, as [`list_events_for_bounded_context_matching_tags_cached`]
/// does. The cache serves it only from a window that holds everything
/// after `after_sequence`, and selects the last matches of items with
/// `latest` from it the
/// same way.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_events_matching_query_cached(
    pool: &Pool,
    cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    query: &[QueryItem],
    after_sequence: Option<i64>,
) -> crate::error::Result<(Vec<Event>, i64)> {
    match cache
        .try_events_matching_query(pool, bounded_context, query, after_sequence.unwrap_or(-1))
        .await?
    {
        Some((events, covered_through)) => Ok((
            crate::event_store::select_matching_events(query, &events),
            covered_through,
        )),
        None => {
            let (covered_through, bc) = futures_util::try_join!(
                latest_sequence(pool, bounded_context),
                require_bounded_context(pool, bounded_context),
            )?;
            let events = list_events_matching_query_with_bc(
                &mut *pool.acquire().await?,
                &bc,
                query,
                after_sequence,
                None,
            )
            .await?;
            Ok((events, covered_through.unwrap_or(-1)))
        }
    }
}

/// Turns `events` rows of any type from `bc` into [`Event`]s on `conn`,
/// batching the lookups they need: one query for every event type
/// `known_event_types` doesn't already answer, and one (plus one for
/// their command types) for every originating command a
/// `command_triggered` row names. Every read of many events goes through
/// it (docs/architecture.md §125) - they used to resolve each row's
/// originating command one at a time, several queries each. The DCB
/// delta query and a new sync projection's locked tail read run it on the
/// transaction holding the bounded context's `sequence` lock
/// (docs/architecture.md §117); the others on a connection of their own.
async fn events_from_rows(
    conn: &mut sqlx::PgConnection,
    bc: &BoundedContext,
    rows: Vec<EventRowAnyType>,
    known_event_types: Option<&std::collections::HashMap<String, EventType>>,
) -> crate::error::Result<Vec<Event>> {
    let row_count = rows.len();
    let row_loop_started = std::time::Instant::now();

    // Every distinct event type this result set needs that
    // `known_event_types` (a caller's already-warmed map, e.g.
    // `decide_command_in_tx`'s own) doesn't already answer, batched into
    // one `WHERE name = ANY($1)` round trip - `get_commands_by_ids_with_bc`'s
    // own precedent below, same reasoning: a batched query, not a
    // concurrent burst of small ones (a first, concurrent attempt at
    // fixing this whole row-processing loop measured worse overall, by
    // starving the next batch's own lock acquisition - see this
    // function's own doc comment for the full story).
    let mut event_types: std::collections::HashMap<String, EventType> =
        std::collections::HashMap::new();
    let mut missing_type_names: Vec<&str> = Vec::new();
    for row in &rows {
        if event_types.contains_key(&row.event_type_name) {
            continue;
        }
        match known_event_types.and_then(|m| m.get(&row.event_type_name)) {
            Some(et) => {
                event_types.insert(row.event_type_name.clone(), et.clone());
            }
            None => {
                if !missing_type_names.contains(&row.event_type_name.as_str()) {
                    missing_type_names.push(&row.event_type_name);
                }
            }
        }
    }
    let event_type_lookup_started = std::time::Instant::now();
    event_types
        .extend(get_event_types_by_names_with_bc(&mut *conn, bc, &missing_type_names).await?);
    let event_type_lookup_elapsed = event_type_lookup_started.elapsed();

    // The real cost this whole investigation found (docs/architecture.md
    // §61's round four): a `command_triggered` row's own origin needs the
    // *entire* originating `Command` (`get_command_by_id`, itself several
    // round trips deep - `get_command_type` → `get_bounded_context` →
    // `get_role`). A first attempt fetched these concurrently, one
    // `event_origin_from_row` future per row - measured *worse*, not
    // better: bursting many simultaneous connection requests out of a
    // shared, already-contended pool starved the *next* batch's own lock
    // acquisition (`command batch leader lock wait` climbed to ~1.7s mean
    // in that measurement). This instead batches the distinct
    // `origin_command_id`s this result set actually needs into one
    // `WHERE id = ANY($1)` query (`get_commands_by_ids_with_bc`, itself
    // internally batching the distinct `command_type_name`s the same
    // way) - one or two round trips total for the whole row set, not one
    // per row, concurrent or not.
    let origin_lookup_started = std::time::Instant::now();
    let mut command_ids: Vec<i64> = Vec::new();
    for row in &rows {
        if row.origin_kind == "command_triggered" {
            if let Some(id) = row.origin_command_id {
                if !command_ids.contains(&id) {
                    command_ids.push(id);
                }
            }
        }
    }
    let commands_by_id = get_commands_by_ids_with_bc(conn, bc, &command_ids).await?;
    let mut origins = Vec::with_capacity(rows.len());
    for row in &rows {
        origins.push(match row.origin_kind.as_str() {
            "external_triggered" => EventOrigin::ExternalTriggered {
                source_content: row
                    .origin_source_content
                    .clone()
                    .expect("external_triggered event row without origin_source_content"),
                source_context: row.origin_source_context.clone(),
            },
            "directly_created" => EventOrigin::DirectlyCreated,
            "system_triggered" => EventOrigin::SystemTriggered,
            "skilj_recorded" => EventOrigin::SkiljRecorded,
            "command_triggered" => {
                let command_id = row
                    .origin_command_id
                    .expect("command_triggered event row without origin_command_id");
                // `commands_by_id` came from `get_commands_by_ids_with_bc`
                // (see its own sibling note in `get_commands_by_ids_with_bc`
                // above) - a `bc`-in-hand, no-recheck batch query, so a
                // `hard_delete_bounded_context` race surfaces as a real
                // `Err` before this lookup, not a silent miss. A genuine
                // miss here is a real bug (an `events` row outliving the
                // `commands` row it names), not a race.
                let command = commands_by_id
                    .get(&command_id)
                    .expect("events row references a commands row that no longer exists");
                EventOrigin::CommandTriggered {
                    command: Box::new(command.clone()),
                }
            }
            other => EventOrigin::Unknown {
                kind: other.to_string(),
            },
        });
    }
    let origin_lookup_elapsed = origin_lookup_started.elapsed();

    let mut events = Vec::with_capacity(rows.len());
    for (row, origin) in rows.into_iter().zip(origins) {
        events.push(Event {
            bounded_context: bc.clone(),
            event_type: event_types[&row.event_type_name].clone(),
            payload: row.payload,
            metadata: Metadata {
                r#type: row.metadata_type,
                version: row.metadata_version,
                client_id: row.metadata_client_id,
                created_at: row.metadata_created_at,
                correlation_id: row.metadata_correlation_id,
                causation_id: row.metadata_causation_id,
            },
            sequence: row.sequence,
            tags: row.tags.0,
            encryption_keys: Vec::new(),
            origin,
        });
    }
    tracing::debug!(
        row_count,
        row_loop_us = row_loop_started.elapsed().as_micros(),
        event_type_lookup_us = event_type_lookup_elapsed.as_micros(),
        origin_lookup_us = origin_lookup_elapsed.as_micros(),
        "event rows resolved"
    );
    Ok(events)
}

/// One `Event` by its own `sequence` - `InspectEvent`'s own lookup key
/// (`context event: Event`), added propagating `skilj-graphql`'s
/// `EventQuery` resolver (Phase 3). `None` when no event in this bounded
/// context has that sequence.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_event_by_sequence(
    pool: &Pool,
    bounded_context: &str,
    sequence: i64,
) -> crate::error::Result<Option<Event>> {
    let Some(bc) = get_bounded_context(pool, bounded_context).await? else {
        return Ok(None);
    };

    let schema = schema_ident(bounded_context);
    let Some(row): Option<EventRowAnyType> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, \
         metadata_client_id, metadata_created_at, metadata_correlation_id, \
         metadata_causation_id, tags, origin_kind, origin_source_content, \
         origin_source_context, origin_command_id FROM {schema}.events WHERE sequence = $1"
    )))
    .bind(sequence)
    .fetch_optional(pool)
    .await?
    else {
        return Ok(None);
    };

    let et = require_event_type(pool, bounded_context, &row.event_type_name).await?;
    let origin = event_origin_from_row(
        pool,
        bounded_context,
        &row.origin_kind,
        row.origin_source_content,
        row.origin_source_context,
        row.origin_command_id,
    )
    .await?;
    Ok(Some(Event {
        bounded_context: bc,
        event_type: et,
        payload: row.payload,
        metadata: Metadata {
            r#type: row.metadata_type,
            version: row.metadata_version,
            client_id: row.metadata_client_id,
            created_at: row.metadata_created_at,
            correlation_id: row.metadata_correlation_id,
            causation_id: row.metadata_causation_id,
        },
        sequence: row.sequence,
        tags: row.tags.0,
        encryption_keys: Vec::new(),
        origin,
    }))
}

/// The most recent `limit` events of a whole bounded context, ascending
/// by `sequence` - `event_cache::EventCache::warm`'s own fetch, and the
/// only place this module issues a `DESC ... LIMIT` query at all (every
/// other listing function loads a range in ascending order directly).
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_recent_events_for_bounded_context(
    pool: &Pool,
    bounded_context: &str,
    limit: usize,
) -> crate::error::Result<Vec<Event>> {
    let bc = require_bounded_context(pool, bounded_context).await?;

    let schema = schema_ident(bounded_context);
    let rows: Vec<EventRowAnyType> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, \
         metadata_client_id, metadata_created_at, metadata_correlation_id, \
         metadata_causation_id, tags, origin_kind, origin_source_content, \
         origin_source_context, origin_command_id FROM {schema}.events \
         ORDER BY sequence DESC LIMIT $1"
    )))
    .bind(limit as i64)
    .fetch_all(pool)
    .await?;

    let mut events = events_from_rows(&mut *pool.acquire().await?, &bc, rows, None).await?;
    // The query above fetched newest-first to make LIMIT cheap - reverse
    // back to sequence order.
    events.reverse();
    Ok(events)
}

/// The type-scoped, `after_sequence`-bounded twin of `list_events` above -
/// `list_events_cached`'s own fallback path, so falling back to Postgres
/// doesn't itself load more than the request actually needs.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_events_from(
    pool: &Pool,
    bounded_context: &str,
    event_type_name: &str,
    after_sequence: i64,
) -> crate::error::Result<Vec<Event>> {
    let bc = require_bounded_context(pool, bounded_context).await?;
    let et = require_event_type(pool, bounded_context, event_type_name).await?;

    let schema = schema_ident(bounded_context);
    let rows: Vec<EventRowAnyType> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, metadata_client_id, \
         metadata_created_at, metadata_correlation_id, metadata_causation_id, tags, \
         origin_kind, origin_source_content, origin_source_context, \
         origin_command_id FROM {schema}.events WHERE event_type_name = $1 AND sequence > $2 \
         ORDER BY sequence"
    )))
    .bind(event_type_name)
    .bind(after_sequence)
    .fetch_all(pool)
    .await?;

    let known = std::collections::HashMap::from([(et.name.clone(), et)]);
    events_from_rows(&mut *pool.acquire().await?, &bc, rows, Some(&known)).await
}

/// At most one event of each of `event_types`, in `bounded_context` -
/// what `projections::register_projection` needs for its only use of
/// history: whether *any* event of a consumed type exists yet (so a new
/// sync projection needs a history fold). One witness per type answers
/// that exactly as the full history would, without loading it - which
/// the `registerProjection` mutation, every projection's startup
/// reconciliation and template resync all used to do.
pub async fn witness_events_of_types(
    pool: &Pool,
    bounded_context: &str,
    event_types: &[EventType],
) -> crate::error::Result<Vec<Event>> {
    let mut witnesses = Vec::new();
    for event_type in event_types {
        witnesses.extend(
            list_events_from_limited(pool, bounded_context, &event_type.name, -1, 1).await?,
        );
    }
    Ok(witnesses)
}

/// How many events one background catch-up tick loads at most - for a
/// `CrossContextRoute`/`ScheduleDeadline`/`CancelDeadline` source, an
/// async projection or rebuild (`catch_up_bounded_context`) or a snapshot
/// (`catch_up_snapshots`). The rest wait for the next tick, which picks
/// up from the persisted cursor/`caught_up_to`/snapshot progress.
pub const MAX_EVENTS_PER_CATCH_UP_TICK: i64 = 1000;

/// [`list_events_cached`], at most `limit` events.
async fn list_events_cached_limited(
    pool: &Pool,
    cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    event_type_name: &str,
    after_sequence: i64,
    limit: i64,
) -> crate::error::Result<Vec<Event>> {
    match cache
        .try_events_after(pool, bounded_context, after_sequence)
        .await?
    {
        Some(events) => Ok(events
            .into_iter()
            .filter(|e| e.event_type.name == event_type_name)
            .take(usize::try_from(limit).unwrap_or(usize::MAX))
            .collect()),
        None => {
            list_events_from_limited(
                pool,
                bounded_context,
                event_type_name,
                after_sequence,
                limit,
            )
            .await
        }
    }
}

/// The highest sequence of `event_type_name` in `bounded_context`
/// (only among events created at or before `created_at_or_before`, when
/// given), or `-1` - a new catch-up cursor's `Latest`/`AtTime` seed, as
/// one aggregate query.
async fn highest_sequence_of_type(
    pool: &Pool,
    bounded_context: &str,
    event_type_name: &str,
    created_at_or_before: Option<DateTime<Utc>>,
) -> crate::error::Result<i64> {
    let schema = schema_ident(bounded_context);
    let (max,): (Option<i64>,) = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT MAX(sequence) FROM {schema}.events WHERE event_type_name = $1 \
         AND ($2::timestamptz IS NULL OR metadata_created_at <= $2)"
    )))
    .bind(event_type_name)
    .bind(created_at_or_before)
    .fetch_one(pool)
    .await?;
    Ok(max.unwrap_or(-1))
}

/// [`list_events_from`] capped at `limit` events - [`for_each_event_chunk`]'s
/// Postgres fallback for a type-scoped read.
pub async fn list_events_from_limited(
    pool: &Pool,
    bounded_context: &str,
    event_type_name: &str,
    after_sequence: i64,
    limit: i64,
) -> crate::error::Result<Vec<Event>> {
    let bc = require_bounded_context(pool, bounded_context).await?;
    let et = require_event_type(pool, bounded_context, event_type_name).await?;

    let schema = schema_ident(bounded_context);
    let rows: Vec<EventRowAnyType> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, metadata_client_id, \
         metadata_created_at, metadata_correlation_id, metadata_causation_id, tags, \
         origin_kind, origin_source_content, origin_source_context, \
         origin_command_id FROM {schema}.events WHERE event_type_name = $1 AND sequence > $2 \
         ORDER BY sequence LIMIT $3"
    )))
    .bind(event_type_name)
    .bind(after_sequence)
    .bind(limit)
    .fetch_all(pool)
    .await?;

    let known = std::collections::HashMap::from([(et.name.clone(), et)]);
    events_from_rows(&mut *pool.acquire().await?, &bc, rows, Some(&known)).await
}

/// `FetchEvents`/`ConsumeEvents`'s own real read path - see
/// `crate::event_cache`'s own module doc comment for the full design.
/// Tries the cache first; `list_events_from` above is the fallback, so a
/// coverage miss still only loads what the request actually needs, not
/// the whole type's history.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_events_cached(
    pool: &Pool,
    cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    event_type_name: &str,
    after_sequence: i64,
) -> crate::error::Result<Vec<Event>> {
    match cache
        .try_events_after(pool, bounded_context, after_sequence)
        .await?
    {
        Some(events) => Ok(events
            .into_iter()
            .filter(|e| e.event_type.name == event_type_name)
            .collect()),
        None => list_events_from(pool, bounded_context, event_type_name, after_sequence).await,
    }
}

/// Walks a bounded context's events after `after_sequence`, in sequence
/// order, `chunk_size` at a time - only `event_type_name`'s when given -
/// handing each chunk to `visit` until it returns `false` or
/// history runs out. Cache-first per chunk, like `list_events_cached`;
/// the Postgres fallback is `LIMIT`ed, so a long history is never loaded
/// whole. This is how the `config.max_events_per_read`-bounded reads
/// (`FetchEvents`, `ConsumeEvents`, `QueryEvents`) find their page without
/// holding more than a chunk plus that page in memory - see
/// [`collect_event_page`].
pub async fn for_each_event_chunk(
    pool: &Pool,
    cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    event_type_name: Option<&str>,
    mut after_sequence: i64,
    chunk_size: usize,
    mut visit: impl FnMut(&[Event]) -> crate::error::Result<bool>,
) -> crate::error::Result<()> {
    let chunk_size = chunk_size.max(1);
    let limit = i64::try_from(chunk_size).unwrap_or(i64::MAX);
    loop {
        let chunk = match cache
            .try_events_after(pool, bounded_context, after_sequence)
            .await?
        {
            Some(events) => {
                // The window is complete from `after_sequence` on, so a
                // short type-filtered result here is the real end.
                let chunk: Vec<Event> = events
                    .into_iter()
                    .filter(|e| event_type_name.is_none_or(|name| e.event_type.name == name))
                    .take(chunk_size)
                    .collect();
                let exhausted = chunk.len() < chunk_size;
                (chunk, exhausted)
            }
            None => {
                let chunk = match event_type_name {
                    Some(name) => {
                        list_events_from_limited(pool, bounded_context, name, after_sequence, limit)
                            .await?
                    }
                    None => {
                        list_events_for_bounded_context_from_limited(
                            pool,
                            bounded_context,
                            after_sequence,
                            limit,
                        )
                        .await?
                    }
                };
                let exhausted = chunk.len() < chunk_size;
                (chunk, exhausted)
            }
        };
        let (chunk, exhausted) = chunk;
        if let Some(last) = chunk.last() {
            after_sequence = last.sequence;
        }
        if !visit(&chunk)? || exhausted {
            return Ok(());
        }
    }
}

/// One bounded page: walks [`for_each_event_chunk`], `max_events` at a
/// time (so memory stays at about a chunk plus the page), and asks `select`
/// for the events to serve out of each chunk (given how many more fit),
/// stopping once `max_events` are selected or history ends. `select` is
/// the rule's own pure function (`event_store::fetch_events_page` and
/// friends), so the page is exactly the first `max_events` it would have
/// served over the whole history. It runs at least once, even on an
/// empty history, so its own validation errors still surface.
#[allow(clippy::too_many_arguments)]
pub async fn collect_event_page(
    pool: &Pool,
    cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    event_type_name: Option<&str>,
    after_sequence: i64,
    max_events: usize,
    select: impl FnMut(&[Event], usize) -> crate::error::Result<Vec<Event>>,
) -> crate::error::Result<Vec<Event>> {
    Ok(collect_scanned_event_page(
        pool,
        cache,
        bounded_context,
        event_type_name,
        after_sequence,
        max_events,
        select,
    )
    .await?
    .events)
}

/// A page from [`collect_scanned_event_page`]: the events served, and the
/// highest sequence the walk examined (`None` if it examined nothing).
#[derive(Debug, Clone, PartialEq)]
pub struct ScannedEventPage {
    pub events: Vec<Event>,
    pub scanned_through: Option<i64>,
}

/// [`collect_event_page`], also reporting how far it walked. When the
/// page came back short of `max_events`, the walk reached the end of
/// history, and `select` passed over every examined event it didn't
/// serve - so a reader's cursor can move to `scanned_through` rather than
/// the last event served, and the next poll doesn't walk the same
/// non-matching events again (docs/architecture.md §112). Safe because
/// events become visible in sequence order: `next_sequence`'s row lock
/// is held until its transaction commits, so nothing can later appear
/// below a sequence already read.
#[allow(clippy::too_many_arguments)]
pub async fn collect_scanned_event_page(
    pool: &Pool,
    cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    event_type_name: Option<&str>,
    after_sequence: i64,
    max_events: usize,
    mut select: impl FnMut(&[Event], usize) -> crate::error::Result<Vec<Event>>,
) -> crate::error::Result<ScannedEventPage> {
    let mut page = Vec::new();
    let mut scanned_through = None;
    for_each_event_chunk(
        pool,
        cache,
        bounded_context,
        event_type_name,
        after_sequence,
        max_events,
        |chunk| {
            if let Some(last) = chunk.last() {
                scanned_through = Some(last.sequence);
            }
            page.extend(select(chunk, max_events - page.len())?);
            Ok(page.len() < max_events)
        },
    )
    .await?;
    Ok(ScannedEventPage {
        events: page,
        scanned_through,
    })
}

/// The tag-filtered counterpart of [`for_each_event_chunk`]
/// (docs/architecture.md §108): walks the events carrying any of `tags`,
/// after `after_sequence`, in sequence order, `chunk_size` at a time
/// through the tag index, calling `f` per chunk until it returns `false`
/// or the matches run out. So a tag shared by a large part of a bounded
/// context's history is never loaded whole. `f` runs at least once, even
/// with no matches, so the caller's own validation still happens.
pub async fn for_each_tagged_event_chunk(
    pool: &Pool,
    bounded_context: &str,
    tags: &[Tag],
    after_sequence: i64,
    chunk_size: usize,
    mut f: impl FnMut(&[Event]) -> crate::error::Result<bool>,
) -> crate::error::Result<()> {
    let bc = require_bounded_context(pool, bounded_context).await?;
    let chunk_size = chunk_size.max(1);
    let limit = i64::try_from(chunk_size).unwrap_or(i64::MAX);
    let mut after = after_sequence;
    loop {
        let chunk = list_events_for_bounded_context_matching_tags_with_bc(
            &mut *pool.acquire().await?,
            &bc,
            tags,
            Some(after),
            None,
            Some(limit),
        )
        .await?;
        if !f(&chunk)? || chunk.len() < chunk_size {
            return Ok(());
        }
        after = chunk.last().map_or(after, |e| e.sequence);
    }
}

/// [`collect_event_page`] over [`for_each_tagged_event_chunk`]: the first
/// `max_events` events `select` serves out of those carrying any of
/// `tags` after `after_sequence`, read a chunk at a time.
pub async fn collect_tagged_event_page(
    pool: &Pool,
    bounded_context: &str,
    tags: &[Tag],
    after_sequence: i64,
    max_events: usize,
    mut select: impl FnMut(&[Event], usize) -> crate::error::Result<Vec<Event>>,
) -> crate::error::Result<Vec<Event>> {
    let mut page = Vec::new();
    for_each_tagged_event_chunk(
        pool,
        bounded_context,
        tags,
        after_sequence,
        max_events,
        |chunk| {
            page.extend(select(chunk, max_events - page.len())?);
            Ok(page.len() < max_events)
        },
    )
    .await?;
    Ok(page)
}

/// `QueryEvents`/`CountEvents`'s own real read path when no `tags`
/// filter is given - see `crate::event_cache`'s own module doc comment
/// for the full design. `after_sequence: -1` asks for full history
/// (`CountEvents`, which has no `after_sequence` of its own);
/// `list_events_for_bounded_context`/`list_events_for_bounded_context_from`
/// (both already existed, reused unchanged) are the fallback for either
/// case respectively. `ProcessCommand`'s own DCB pre-check, and
/// `QueryEvents`/`CountEvents` when a `tags` filter *is* given, use
/// `list_events_for_bounded_context_matching_tags_cached` below instead -
/// [docs/architecture.md §19](../../../docs/architecture.md#optional-snapshotting-matching-events)'s "Problem 1" fix, avoiding exactly the
/// full-bounded-context fetch this function's own fallback still does.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_events_for_bounded_context_cached(
    pool: &Pool,
    cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    after_sequence: i64,
) -> crate::error::Result<Vec<Event>> {
    match cache
        .try_events_after(pool, bounded_context, after_sequence)
        .await?
    {
        Some(events) => Ok(events),
        None if after_sequence < 0 => list_events_for_bounded_context(pool, bounded_context).await,
        None => list_events_for_bounded_context_from(pool, bounded_context, after_sequence).await,
    }
}

/// `ProcessCommand`'s own DCB pre-check, and `QueryEvents`/`CountEvents`
/// when a `tags` filter is supplied - the cached counterpart to
/// `list_events_for_bounded_context_matching_tags` above, same
/// cache-first/Postgres-fallback shape `list_events_for_bounded_context_cached`
/// already has, via `EventCache::try_events_matching_tags` instead of
/// `try_events_after`. Already tag-scoped either way - see that
/// function's own doc comment.
///
/// Also returns the position the read is complete through - every
/// matching event at or below it is in the result - which is where a
/// command's re-check under the lock starts (docs/architecture.md §178).
/// From the cache, the window's highest sequence. From Postgres, the
/// latest sequence read *before* the tag query: events commit in sequence
/// order under the bounded context's lock, so everything up to it is
/// visible to the query that follows. A newer event the query also
/// happened to see is above the position; the re-check starts above the
/// highest event the read holds anyway, so it doesn't come back.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn list_events_for_bounded_context_matching_tags_cached(
    pool: &Pool,
    cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    tags: &[Tag],
    after_sequence: Option<i64>,
) -> crate::error::Result<(Vec<Event>, i64)> {
    match cache
        .try_events_matching_tags(pool, bounded_context, tags, after_sequence.unwrap_or(-1))
        .await?
    {
        Some(served) => Ok(served),
        None => {
            // Both before the tag query, alongside each other: the latest
            // sequence used to cost a round trip of its own ahead of the
            // bounded context's lookup, on every miss (docs/architecture.md
            // §195).
            let (covered_through, bc) = futures_util::try_join!(
                latest_sequence(pool, bounded_context),
                require_bounded_context(pool, bounded_context),
            )?;
            let events = list_events_for_bounded_context_matching_tags_with_bc(
                &mut *pool.acquire().await?,
                &bc,
                tags,
                after_sequence,
                None,
                None,
            )
            .await?;
            Ok((events, covered_through.unwrap_or(-1)))
        }
    }
}

/// `InspectEvent`'s own real read path - see `crate::event_cache`'s own
/// module doc comment for the full design.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn get_event_by_sequence_cached(
    pool: &Pool,
    cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    sequence: i64,
) -> crate::error::Result<Option<Event>> {
    match cache
        .try_event_by_sequence(pool, bounded_context, sequence)
        .await?
    {
        Some(event) => Ok(Some(event)),
        None => get_event_by_sequence(pool, bounded_context, sequence).await,
    }
}

/// `command_id` must be `Some` exactly when `event.origin` is
/// `CommandTriggered`, and `None` otherwise - the caller's own
/// `insert_command(pool, &result.command)` (returning the new row's id)
/// runs first for a `ProcessCommandResult`, then this is called once per
/// produced `Event` with that same id.
#[tracing::instrument(skip_all)]
pub async fn insert_event<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    event: &Event,
    command_id: Option<i64>,
) -> crate::error::Result<()> {
    let (origin_kind, source_content, source_context) = match &event.origin {
        EventOrigin::ExternalTriggered {
            source_content,
            source_context,
        } => {
            debug_assert!(command_id.is_none());
            (
                "external_triggered",
                Some(source_content.clone()),
                source_context.clone(),
            )
        }
        EventOrigin::DirectlyCreated => {
            debug_assert!(command_id.is_none());
            ("directly_created", None, None)
        }
        EventOrigin::SystemTriggered => {
            debug_assert!(command_id.is_none());
            ("system_triggered", None, None)
        }
        EventOrigin::SkiljRecorded => {
            debug_assert!(command_id.is_none());
            ("skilj_recorded", None, None)
        }
        EventOrigin::CommandTriggered { .. } => {
            debug_assert!(
                command_id.is_some(),
                "insert_event: a CommandTriggered origin needs command_id - call \
                 insert_command(pool, &result.command) first and pass its returned id"
            );
            ("command_triggered", None, None)
        }
        // Only ever read back from a newer version's row; this build has
        // no way to write the per-kind columns it would need.
        EventOrigin::Unknown { .. } => {
            return Err(crate::error::Error::Unsupported {
                what: "EventOrigin",
            })
        }
    };

    let schema = schema_ident(&event.bounded_context.name);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.events (sequence, event_type_name, payload, metadata_type, \
         metadata_version, metadata_client_id, metadata_created_at, metadata_correlation_id, \
         metadata_causation_id, tags, \
         origin_kind, origin_source_content, origin_source_context, origin_command_id) \
         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14)"
    )))
    .bind(event.sequence)
    .bind(&event.event_type.name)
    .bind(&event.payload)
    .bind(&event.metadata.r#type)
    .bind(event.metadata.version)
    .bind(&event.metadata.client_id)
    .bind(event.metadata.created_at)
    .bind(&event.metadata.correlation_id)
    .bind(&event.metadata.causation_id)
    .bind(Json(&event.tags))
    .bind(origin_kind)
    .bind(source_content)
    .bind(source_context)
    .bind(command_id)
    .execute(executor)
    .await?;
    Ok(())
}

/// The real, transactional half of [§8](../../../docs/architecture.md#open-for-a-future-pass) item 6: inserts `event` and, in
/// the *same* transaction, folds it into every `sync = true` `Projection`
/// in its bounded context via `dispatcher` - "commits or fails with the
/// write" (the note above the rules), the whole reason sync projections
/// exist as a distinct, deliberately-friction-laden opt-in over the
/// async default. Every event-creation call site (`CreateExternalEvent`/
/// `CreateDirectEvent`'s REST handlers, `ProcessCommand`'s REST and
/// GraphQL handlers alike) calls this instead of the plain `insert_event`
/// above - which stays exactly as it is, still the right shape for a
/// bounded context with no sync projections at all (every event-writing
/// test fixture so far) and for `insert_event`'s own use inside this
/// function.
///
/// `SELECT ... FOR UPDATE` on each sync projection's own `projection_state`
/// row is what makes this safe under concurrent writers to the same
/// projection - the identical row-lock-based serialisation
/// `next_sequence` already relies on for sequence assignment, just one
/// row per sync projection instead of one row per bounded context.
/// `caught_up_to` advances for every sync projection in the context
/// regardless of whether it actually consumes this event's type (the
/// note above the rules: "advances that projection's own caught_up_to...
/// either way") - `dispatcher.project()` itself is what decides whether
/// the *state* changes; this function always bumps the position.
#[tracing::instrument(skip_all)]
pub async fn insert_event_and_update_sync_projections(
    pool: &Pool,
    event: &Event,
    command_id: Option<i64>,
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    encryption_key_ids: &[i64],
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
) -> crate::error::Result<()> {
    let mut tx = pool.begin().await?;
    let sync_projections = sync_projection_names(&mut tx, &event.bounded_context.name).await?;
    insert_event_and_update_sync_projections_in_tx(
        &mut tx,
        event,
        command_id,
        dispatcher,
        encryption_key_ids,
        &sync_projections,
    )
    .await?;
    tx.commit().await?;

    // EventSubscription's own real-time delivery - after the commit, not
    // before: a subscriber must never see an event that could still have
    // rolled back (see EventBroadcaster's own doc comment for why this
    // is the one choke point every event-creation call site already
    // shares).
    broadcaster.publish(event);
    record_event_appended(event);
    notify_event_appended(pool, event, broadcaster.instance_id()).await;
    event_cache.append(event).await;

    Ok(())
}

/// The transactional core of `insert_event_and_update_sync_projections`
/// above, split out so `next_sequence`'s own lock, this event's insert,
/// and (for `ProcessCommand`) the triggering `Command`'s own insert can
/// all share one already-open transaction instead of each getting their
/// own - see the note above the rules in specs/skilj.allium: "a single
/// row per bounded context... is locked... as part of the same
/// transaction that inserts the new Command/Event rows, then incremented
/// and released on commit." Neither commits `tx` nor broadcasts - both
/// stay the caller's job, exactly once, after every event in a single
/// submission (a `ProcessCommand` call can trigger several) has been
/// folded in.
///
/// `sync_projections` - the names of the bounded context's `sync`
/// projections - is the caller's job (issue #32): fetched once
/// per commit via [`sync_projection_names`], on this same transaction
/// after its `sequence` row lock is held - see that function's doc
/// comment for why both halves of that matter.
#[tracing::instrument(skip_all)]
pub async fn insert_event_and_update_sync_projections_in_tx(
    tx: &mut Transaction<'_, Postgres>,
    event: &Event,
    command_id: Option<i64>,
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    encryption_key_ids: &[i64],
    sync_projections: &[String],
) -> crate::error::Result<()> {
    let bounded_context = &event.bounded_context.name;
    let schema = schema_ident(bounded_context);

    insert_event(&mut **tx, event, command_id).await?;

    // `event.encryption_keys`' own `id`s aren't carried on the domain
    // struct (it has none, matching `entity EncryptionKey` itself) -
    // `encryption_key_ids` is what `get_or_create_encryption_key` handed
    // the caller back alongside it, threaded through here so this
    // transaction can also link the join rows atomically with the event
    // insert they belong to.
    // Same `unnest`-batched insert as `insert_command`'s own
    // `command_encryption_keys` above, same reasoning - one round trip
    // for however many keys this event's payload needed, not one per
    // key.
    if !encryption_key_ids.is_empty() {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.event_encryption_keys (event_sequence, encryption_key_id) \
             SELECT $1, unnest($2::bigint[])"
        )))
        .bind(event.sequence)
        .bind(encryption_key_ids)
        .execute(&mut **tx)
        .await?;
    }

    fold_event_into_sync_projections_in_tx(tx, event, dispatcher, sync_projections).await
}

/// The sync-projection half of [`insert_event_and_update_sync_projections_in_tx`]:
/// folds `event`, already inserted on `tx`, into every one of
/// `sync_projections`. Split out so a batch written as a set
/// (docs/architecture.md §196) can insert its events first and fold them
/// after, in sequence order.
async fn fold_event_into_sync_projections_in_tx(
    tx: &mut Transaction<'_, Postgres>,
    event: &Event,
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    sync_projections: &[String],
) -> crate::error::Result<()> {
    let bounded_context = &event.bounded_context.name;
    let schema = schema_ident(bounded_context);
    for projection_name in sync_projections {
        // `Some(vec![])` - registered, but this event's type isn't
        // consumed - falls through to an empty loop below: zero instances
        // touched, `caught_up_to` still advancing after it (§9's "keyed /
        // multi-row Projections" pass). `None` - this instance doesn't
        // declare the projection - can't be folded here at all. If it
        // consumes this event the write is refused: committed, the
        // projection would skip the event for good (docs/architecture.md
        // §160).
        if dispatcher
            .default_state(bounded_context, projection_name)
            .is_none()
        {
            let consumes: bool = sqlx::query_scalar(sqlx::AssertSqlSafe(format!(
                "SELECT EXISTS (SELECT 1 FROM {schema}.projection_consumed_event_types \
                 WHERE projection_name = $1 AND event_type_name = $2)"
            )))
            .bind(projection_name)
            .bind(&event.event_type.name)
            .fetch_one(&mut **tx)
            .await?;
            if consumes {
                return Err(crate::event_store::Error::SyncProjectionNotDeclared(
                    projection_name.clone(),
                )
                .into());
            }
        }
        let keys = dispatcher
            .keys(bounded_context, projection_name, event)
            .unwrap_or_default();
        let default_state_json = dispatcher
            .default_state(bounded_context, projection_name)
            .unwrap_or_default();
        let owner_tag_key = dispatcher
            .owner_tag_key(bounded_context, projection_name)
            .flatten();

        for key in &keys {
            // `as_of_sequence` guard (issue #25's investigation
            // finding) - unreachable in practice on this particular path
            // (every call here shares the one transaction that also
            // holds `insert_event`'s own bounded-context `sequence` row
            // lock, already fully serializing concurrent instances for
            // the whole bc, per `insert_event_via_the_locked_path`'s own
            // doc comment), kept anyway so this call site stays
            // structurally identical to the two genuinely-concurrent
            // ones below rather than being the one exception mid-fix.
            let (as_of_sequence, current_state) = get_or_create_projection_state_for_update(
                &mut **tx,
                &schema,
                projection_name,
                key,
                &default_state_json,
            )
            .await?;
            if as_of_sequence >= event.sequence {
                continue;
            }

            let new_state = match dispatcher.project(
                bounded_context,
                projection_name,
                &current_state,
                event,
                key,
            ) {
                Some(result) => result?,
                None => current_state,
            };

            apply_projection_fold_update(
                &mut **tx,
                &schema,
                "projection_state",
                "",
                projection_name,
                key,
                &new_state,
                owner_tag_key,
                event,
            )
            .await?;
        }

        sqlx::query(sqlx::AssertSqlSafe(format!(
            "UPDATE {schema}.projections SET caught_up_to = $1 WHERE name = $2"
        )))
        .bind(event.sequence)
        .bind(projection_name)
        .execute(&mut **tx)
        .await?;
    }

    Ok(())
}

/// The `dedupe_partition_key`/`dedupe_sequence` pair from
/// specs/skilj.allium's own `SubmitExternalEvent` trigger
/// (`rule CreateExternalEvent`, [docs/architecture.md §39](../../../docs/architecture.md#external-message-dedup-create-external-event)) - always
/// supplied together or not at all. That "both or neither" `requires`
/// guard in the spec is satisfied structurally here, not by a separate
/// runtime check: there is no way to construct one of these fields
/// without the other through this type (or, at the REST wire boundary,
/// through `ExternalEventRequest`'s own `dedupe: Option<DedupeRequest>`
/// shape) - a caller supplying exactly one on the wire fails ordinary
/// JSON deserialization before this type is ever built, the same
/// "malformed request, not this crate's rejection to model" register
/// any other structurally-invalid request body already gets.
#[derive(Debug, Clone, Copy)]
pub struct DedupeCursor<'a> {
    /// Names the partition, shard, or stream this message came from -
    /// e.g. `"{topic}:{partition}"` for Kafka, a shard id for Kinesis.
    pub partition_key: &'a str,
    /// This message's own position within `partition_key` - must be
    /// strictly increasing per partition for the caller's own external
    /// source, the property this whole mechanism relies on and cannot
    /// verify itself (see `highest_dedupe_sequence`'s own doc comment).
    pub sequence: i64,
}

/// How `create_and_insert_external_event` recognises a redelivery -
/// specs/skilj.allium's `rule CreateExternalEvent` takes either the
/// dedupe pair or an `idempotency_key`, never both, and an enum makes
/// "both" unrepresentable the way [`DedupeCursor`] makes "only one of the
/// pair" unrepresentable.
#[derive(Debug, Clone, Copy)]
#[non_exhaustive]
pub enum ExternalEventDedupe<'a> {
    /// The per-partition watermark (docs/architecture.md §39): for a
    /// source that replays a partition in order from a committed position.
    Watermark(DedupeCursor<'a>),
    /// One record per message, in `external_message_keys`
    /// (docs/architecture.md §175): for a source that redelivers a message
    /// after later ones - NATS JetStream, AMQP - where a watermark would
    /// drop the redelivery as already seen.
    Key(&'a str),
}

/// What `create_and_insert_external_event` settles on - either a real
/// insert (`Created`, already persisted by the time this returns) or a
/// redelivery this rule recognises and accepts without creating anything
/// (`Redelivered`). Not `SubmitCommandOutcome`'s two-way split
/// (`Accepted`/`Deduplicated`) reused, deliberately: a genuine business
/// rejection has no equivalent here (`create_external_event`'s own
/// failure modes - `TokenNotActive`, `ExternalCreationNotAllowed`, a bad
/// payload - are real errors, returned as `Err`, not a third outcome
/// variant), and calling this case "Deduplicated" would invite comparing
/// it to `SubmitCommandOutcome::Deduplicated`, which returns the
/// original outcome's own triggered sequences - this outcome carries
/// nothing, on purpose, since a watermark remembers only the highest
/// sequence seen, not which event any particular past message produced.
/// See specs/skilj.allium's own `ExternalEventIngestion.ARedeliveryProducesNoEventAndNoOutcome`.
///
/// A key hit (`ExternalEventDedupe::Key`) does know which event the
/// message became, since its record names it, and says so in `sequence`;
/// a watermark hit leaves it `None`.
#[derive(Debug)]
#[non_exhaustive]
pub enum CreateExternalEventOutcome {
    Created(Box<Event>),
    Redelivered { sequence: Option<i64> },
}

/// `highest_dedupe_sequence(adapter, dedupe_partition_key)` from
/// specs/skilj.allium's own `rule CreateExternalEvent` - a black box in
/// the same register as `next_sequence`/`recorded_acceptance`: durable
/// state this library owns, whose storage shape the spec doesn't reach
/// into. `None` when nothing has been recorded yet for this
/// `(adapter_id, partition_key)` pair - the spec's own "or when the
/// partition key is null" clause is handled by the caller never calling
/// this at all when `dedupe` is `None`, not by this function.
///
/// Must be called after the bounded context's own `sequence` row lock is
/// already held (`next_sequence`, inside `create_and_insert_external_event`'s
/// own transaction) - the identical "no lock of its own, rides on the
/// one already held" register `lookup_idempotency_key` already uses, for
/// the same reason: every write into this bounded context is already
/// serialised by that lock, so a plain, unlocked `SELECT` here is
/// race-free.
async fn highest_dedupe_sequence<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    schema: &str,
    adapter_id: &str,
    partition_key: &str,
) -> crate::error::Result<Option<i64>> {
    let row: Option<(i64,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT last_sequence FROM {schema}.external_message_cursors \
         WHERE adapter_id = $1 AND partition_key = $2"
    )))
    .bind(adapter_id)
    .bind(partition_key)
    .fetch_optional(executor)
    .await?;
    Ok(row.map(|(seq,)| seq))
}

/// `recorded_external_event(adapter, idempotency_key)` from
/// specs/skilj.allium's own `rule CreateExternalEvent`: the sequence of
/// the event this adapter created for `key`, or `None`. Same locking
/// story as `highest_dedupe_sequence`: called with the bounded context's
/// `sequence` row lock already held, so a plain `SELECT` is race-free.
async fn recorded_external_event<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    schema: &str,
    adapter_id: &str,
    key: &str,
) -> crate::error::Result<Option<i64>> {
    let row: Option<(i64,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT event_sequence FROM {schema}.external_message_keys \
         WHERE adapter_id = $1 AND message_key = $2"
    )))
    .bind(adapter_id)
    .bind(key)
    .fetch_optional(executor)
    .await?;
    Ok(row.map(|(seq,)| seq))
}

/// Records `key` against the event it created, in the event's own
/// transaction. A plain insert, like `insert_idempotency_key`: the
/// sequence lock rules out a concurrent duplicate getting this far.
async fn record_external_message_key<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    schema: &str,
    adapter_id: &str,
    key: &str,
    event_sequence: i64,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.external_message_keys \
         (adapter_id, message_key, event_sequence, created_at) VALUES ($1, $2, $3, $4)"
    )))
    .bind(adapter_id)
    .bind(key)
    .bind(event_sequence)
    .bind(now)
    .execute(executor)
    .await?;
    Ok(())
}

/// Records `sequence` as the new watermark for `(adapter_id,
/// partition_key)`, inside the same transaction as the `Event` it
/// stands for - a watermark advances exactly when the event it
/// represents is durable, never before and never without it (see
/// `create_and_insert_external_event`'s own doc comment). `ON CONFLICT
/// ... DO UPDATE`, not a plain insert the way `insert_idempotency_key`
/// is - unlike that table, a given `(adapter_id, partition_key)` pair is
/// expected to be written many times over its life, once per message
/// from a real partition, not once ever.
async fn advance_dedupe_watermark<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    schema: &str,
    adapter_id: &str,
    partition_key: &str,
    sequence: i64,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.external_message_cursors \
         (adapter_id, partition_key, last_sequence, updated_at) \
         VALUES ($1, $2, $3, $4) \
         ON CONFLICT (adapter_id, partition_key) \
         DO UPDATE SET last_sequence = EXCLUDED.last_sequence, updated_at = EXCLUDED.updated_at"
    )))
    .bind(adapter_id)
    .bind(partition_key)
    .bind(sequence)
    .bind(now)
    .execute(executor)
    .await?;
    Ok(())
}

/// `CreateExternalEvent`'s own atomic whole: `next_sequence`'s row lock,
/// `event_store::create_external_event`'s pure construction (which needs
/// that lock's own allocated sequence baked into the `Event` it builds),
/// and the insert itself, all inside one transaction - `skilj-rest`'s
/// `post_events_external` handler used to run these three steps
/// unlocked/separately-transacted; a rejection from
/// `create_external_event` (`TokenNotActive`/`ExternalCreationNotAllowed`)
/// after `next_sequence` had already run on the bare pool used to burn a
/// sequence number for an event that was never written -
/// `SequenceIsGaplessPerBoundedContext`'s actual bug. Here, that same
/// rejection instead rolls `tx` back before it ever commits, so the
/// allocation never happened as far as any other reader can tell.
/// `resolve_encryption_keys` still runs on `pool`, before `tx` opens -
/// deliberately, not a gap: see the note above the rules in
/// specs/skilj.allium for why `EncryptionKey` provisioning is resolved
/// before a write's own transaction rather than inside it (real work -
/// a master-key wrap, a round trip - that shouldn't extend how long a
/// row lock like `next_sequence`'s own is held). Not callable from
/// anywhere but `skilj-rest` today (no
/// GraphQL surface offers `CreateExternalEvent`), but lives here rather
/// than in that crate per docs/architecture.md §3.1/§3.2: `skilj-core`
/// is the only crate that owns the database driver, so no other crate
/// ever opens a `Transaction` itself.
///
/// **`dedupe`** ([docs/architecture.md §39](../../../docs/architecture.md#external-message-dedup-create-external-event), specs/skilj.allium's own
/// `rule CreateExternalEvent`): `None` reproduces every existing
/// caller's own behaviour exactly, byte for byte - no lookup, no write
/// to `external_message_cursors`, an event created every single time,
/// the same "omitting it changes nothing" guarantee `submit_command`'s
/// own `idempotency_key: None` already gives (see
/// `ExternalEventIngestion.OmittingTheDedupePairChangesNothing`).
/// `Some(cursor)`: checked against `highest_dedupe_sequence` right after
/// `next_sequence`'s own lock is acquired - the earliest point that's
/// race-free, mirroring exactly where `submit_command`'s own idempotency
/// check runs relative to that same lock. A watermark hit rolls `tx`
/// back (dropped, nothing else was written) and returns
/// `CreateExternalEventOutcome::Redelivered` without ever calling
/// `event_store::create_external_event` at all; a miss proceeds exactly
/// as `None` would, plus one more write in the same transaction -
/// `advance_dedupe_watermark` - before `tx.commit()`.
///
/// `Some(ExternalEventDedupe::Key(key))` is checked at the same point
/// against `external_message_keys` instead (docs/architecture.md §175): a
/// hit is `Redelivered` with the sequence of the event the key created,
/// a miss records the key against the new event before the commit.
#[allow(clippy::too_many_arguments)]
#[tracing::instrument(skip_all)]
pub async fn create_and_insert_external_event(
    pool: &Pool,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    adapter: &ExternalEventToken,
    payload: String,
    source_content: String,
    source_context: Option<String>,
    correlation_id: Option<String>,
    causation_id: Option<String>,
    dedupe: Option<ExternalEventDedupe<'_>>,
    now: DateTime<Utc>,
    key_service: Option<&KeyService>,
    blind: &crate::blind::BlindIndex,
) -> crate::error::Result<CreateExternalEventOutcome> {
    // Every `requires` first, as the spec orders them: before any key is
    // provisioned, the sequence lock taken, or a redelivery recognised
    // (docs/architecture.md §141).
    crate::event_store::check_create_external_event(
        adapter,
        &payload,
        correlation_id.as_deref(),
        causation_id.as_deref(),
        blind,
    )?;
    let bounded_context_name = adapter.event_type.bounded_context.name.clone();
    let schema = schema_ident(&bounded_context_name);

    let mut resolved = std::collections::HashMap::new();
    resolve_encryption_keys(
        pool,
        &bounded_context_name,
        &adapter.event_type.sensitive_fields,
        &payload,
        key_service,
        &mut resolved,
    )
    .await?;

    let mut tx = pool.begin().await?;
    let next_seq = next_sequence(&mut *tx, &bounded_context_name).await?;
    // docs/architecture.md §209: tags are derived below, under the lock a
    // rotation holds - of the generation stored now.
    refresh_blind_generations(&mut tx, &bounded_context_name, blind).await?;

    // On a hit: implicit rollback - nothing else was written, the same
    // "a hit is a cached prior answer, not a new decision, tx is simply
    // dropped" treatment `submit_command`'s own idempotency-key check
    // already uses.
    match &dedupe {
        Some(ExternalEventDedupe::Watermark(cursor)) => {
            let watermark =
                highest_dedupe_sequence(&mut *tx, &schema, &adapter.id, cursor.partition_key)
                    .await?;
            if watermark.is_some_and(|w| cursor.sequence <= w) {
                return Ok(CreateExternalEventOutcome::Redelivered { sequence: None });
            }
        }
        Some(ExternalEventDedupe::Key(key)) => {
            if let Some(sequence) =
                recorded_external_event(&mut *tx, &schema, &adapter.id, key).await?
            {
                return Ok(CreateExternalEventOutcome::Redelivered {
                    sequence: Some(sequence),
                });
            }
        }
        None => {}
    }

    let event = crate::event_store::create_external_event(
        adapter,
        payload,
        source_content,
        source_context,
        correlation_id,
        causation_id,
        next_seq,
        now,
        |subject_key, subject_value| {
            let (key, _, data_key) = resolved
                .get(&(subject_key.to_string(), subject_value.to_string()))
                .expect(
                    "resolve_encryption_keys pre-resolved every subject sensitive_field_subjects \
                     named",
                );
            (key.clone(), data_key.clone())
        },
        blind,
    )?;
    let encryption_key_ids = encryption_key_ids(&event.encryption_keys, &resolved);
    // Fetched only now - after `next_sequence` above already took this
    // bounded context's own lock - see `insert_event_and_update_sync_projections_in_tx`'s
    // own doc comment on why that ordering, not "as early as possible", is
    // what keeps this read race-free against `promote_projection_rebuild`.
    let sync_projections = sync_projection_names(&mut tx, &bounded_context_name).await?;
    insert_event_and_update_sync_projections_in_tx(
        &mut tx,
        &event,
        None,
        projection_dispatcher,
        &encryption_key_ids,
        &sync_projections,
    )
    .await?;
    match &dedupe {
        Some(ExternalEventDedupe::Watermark(cursor)) => {
            advance_dedupe_watermark(
                &mut *tx,
                &schema,
                &adapter.id,
                cursor.partition_key,
                cursor.sequence,
                now,
            )
            .await?;
        }
        Some(ExternalEventDedupe::Key(key)) => {
            record_external_message_key(&mut *tx, &schema, &adapter.id, key, event.sequence, now)
                .await?;
        }
        None => {}
    }
    tx.commit().await?;
    broadcaster.publish(&event);
    record_event_appended(&event);
    notify_event_appended(pool, &event, broadcaster.instance_id()).await;
    event_cache.append(&event).await;

    Ok(CreateExternalEventOutcome::Created(Box::new(event)))
}

/// The dedupe cursor or key of one item of
/// [`create_and_insert_external_events`]: an owned
/// [`ExternalEventDedupe`].
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum ExternalEventBatchDedupe {
    /// See [`ExternalEventDedupe::Watermark`].
    Watermark {
        /// The source's partition.
        partition_key: String,
        /// The message's position in it.
        sequence: i64,
    },
    /// See [`ExternalEventDedupe::Key`].
    Key(String),
}

impl ExternalEventBatchDedupe {
    fn as_dedupe(&self) -> ExternalEventDedupe<'_> {
        match self {
            ExternalEventBatchDedupe::Watermark {
                partition_key,
                sequence,
            } => ExternalEventDedupe::Watermark(DedupeCursor {
                partition_key,
                sequence: *sequence,
            }),
            ExternalEventBatchDedupe::Key(key) => ExternalEventDedupe::Key(key),
        }
    }
}

/// One external event of [`create_and_insert_external_events`]: what
/// [`create_and_insert_external_event`] takes for one event, apart from
/// the token, which the batch shares.
#[derive(Debug, Clone)]
pub struct ExternalEventBatchItem {
    /// The payload, as JSON.
    pub payload: String,
    /// The message as the source sent it.
    pub source_content: String,
    /// Where it came from, if the adapter says.
    pub source_context: Option<String>,
    /// The caller's correlation id, or `None` to have one generated.
    pub correlation_id: Option<String>,
    /// The caller's causation id, if any.
    pub causation_id: Option<String>,
    /// The cursor or key that recognises a redelivery, if any.
    pub dedupe: Option<ExternalEventBatchDedupe>,
}

/// `rule CreateExternalEventBatch` (docs/architecture.md §227): several
/// external events through one token, created or recognised as
/// redeliveries in the order given, each with the outcome
/// [`create_and_insert_external_event`] would give it alone, right after
/// the one before it. One result per item, in order.
///
/// One transaction takes the bounded context's sequence lock once and
/// commits once for the whole batch. Each item runs in its own savepoint:
/// an item that fails - its payload off the schema, an error inserting it
/// - is rolled back alone, sequence number included, and the items after
/// it still run - unless `stop_at_first_failure`, when every item after
/// the first that fails answers [`crate::error::Error::NotProcessed`] and
/// is not processed, so a source that relies on its order (a dedupe
/// watermark, a partition's sequence) can send them again after dealing
/// with the failed one. Because they share the transaction, an item's dedupe
/// check sees the watermarks and keys recorded by the items before it, so
/// a batch that repeats a message answers the repeat as redelivered. An
/// error taking the lock or committing fails every item.
#[allow(clippy::too_many_arguments)]
#[tracing::instrument(skip_all, fields(events = items.len()))]
pub async fn create_and_insert_external_events(
    pool: &Pool,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    adapter: &ExternalEventToken,
    items: Vec<ExternalEventBatchItem>,
    key_service: Option<&KeyService>,
    blind: &crate::blind::BlindIndex,
    stop_at_first_failure: bool,
) -> Vec<crate::error::Result<CreateExternalEventOutcome>> {
    let bounded_context_name = adapter.event_type.bounded_context.name.clone();
    let schema = schema_ident(&bounded_context_name);

    // Every `requires`, and every encryption key, before the lock - as
    // `create_and_insert_external_event` does for one (§141).
    let mut results: Vec<Option<crate::error::Result<CreateExternalEventOutcome>>> =
        Vec::with_capacity(items.len());
    let mut resolved = std::collections::HashMap::new();
    let mut failed = false;
    for item in &items {
        if failed && stop_at_first_failure {
            results.push(Some(Err(crate::error::Error::NotProcessed)));
            continue;
        }
        let checked = crate::event_store::check_create_external_event(
            adapter,
            &item.payload,
            item.correlation_id.as_deref(),
            item.causation_id.as_deref(),
            blind,
        );
        let checked = match checked {
            Ok(_) => {
                resolve_encryption_keys(
                    pool,
                    &bounded_context_name,
                    &adapter.event_type.sensitive_fields,
                    &item.payload,
                    key_service,
                    &mut resolved,
                )
                .await
            }
            Err(e) => Err(e),
        };
        failed |= checked.is_err();
        results.push(checked.err().map(Err));
    }
    if results.iter().all(Option::is_some) {
        return results.into_iter().flatten().collect();
    }

    let created = async {
        let mut tx = pool.begin().await?;
        lock_bounded_context_sequence(&mut tx, &bounded_context_name).await?;
        // docs/architecture.md §209: tags are derived below, under the lock
        // a rotation holds - of the generation stored now.
        refresh_blind_generations(&mut tx, &bounded_context_name, blind).await?;
        // After the lock - see `create_and_insert_external_event`.
        let sync_projections = sync_projection_names(&mut tx, &bounded_context_name).await?;
        let mut outcomes = Vec::new();
        let mut failed = false;
        for (item, result) in items.into_iter().zip(&results) {
            if result.is_some() {
                continue;
            }
            if failed && stop_at_first_failure {
                outcomes.push(Err(crate::error::Error::NotProcessed));
                continue;
            }
            // Each item its own time, as if sent alone.
            let now = Utc::now();
            let dedupe = item.dedupe.clone();
            let mut savepoint = tx.begin().await?;
            let outcome = insert_external_event_in_tx(
                &mut savepoint,
                &schema,
                projection_dispatcher,
                adapter,
                item,
                dedupe.as_ref().map(ExternalEventBatchDedupe::as_dedupe),
                now,
                &resolved,
                &sync_projections,
                blind,
            )
            .await;
            match &outcome {
                Ok(CreateExternalEventOutcome::Created(_)) => savepoint.commit().await?,
                // A redelivery wrote nothing; a failure is undone alone.
                // Awaited, not left to `Drop`: the next item reuses the
                // connection.
                _ => savepoint.rollback().await?,
            }
            failed |= outcome.is_err();
            outcomes.push(outcome);
        }
        tx.commit().await?;
        Ok::<_, crate::error::Error>(outcomes)
    }
    .await;

    match created {
        Ok(outcomes) => {
            let events: Vec<&Event> = outcomes
                .iter()
                .filter_map(|outcome| match outcome {
                    Ok(CreateExternalEventOutcome::Created(event)) => Some(event.as_ref()),
                    _ => None,
                })
                .collect();
            for event in &events {
                broadcaster.publish(event);
                record_event_appended(event);
                event_cache.append(event).await;
            }
            notify_events_appended(pool, &events, broadcaster.instance_id()).await;
            let mut outcomes = outcomes.into_iter();
            results
                .into_iter()
                .map(|result| {
                    result.unwrap_or_else(|| outcomes.next().expect("one outcome per item"))
                })
                .collect()
        }
        // Nothing in the transaction committed: every item that reached
        // it gets the failure. `Error` isn't `Clone`.
        Err(e) => results
            .into_iter()
            .map(|result| result.unwrap_or_else(|| Err(crate::error::Error::batch_failed(&e))))
            .collect(),
    }
}

/// One item of [`create_and_insert_external_events`], on the batch's
/// transaction (a savepoint of it), which already holds the sequence lock:
/// the dedupe check, the sequence number, the event, its insert and sync
/// projections, and the watermark or key - what
/// `create_and_insert_external_event` does for one event under the lock.
#[allow(clippy::too_many_arguments)]
async fn insert_external_event_in_tx(
    tx: &mut Transaction<'_, Postgres>,
    schema: &str,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    adapter: &ExternalEventToken,
    item: ExternalEventBatchItem,
    dedupe: Option<ExternalEventDedupe<'_>>,
    now: DateTime<Utc>,
    resolved: &std::collections::HashMap<(String, String), (EncryptionKey, i64, DataKey)>,
    sync_projections: &[String],
    blind: &crate::blind::BlindIndex,
) -> crate::error::Result<CreateExternalEventOutcome> {
    match &dedupe {
        Some(ExternalEventDedupe::Watermark(cursor)) => {
            let watermark =
                highest_dedupe_sequence(&mut **tx, schema, &adapter.id, cursor.partition_key)
                    .await?;
            if watermark.is_some_and(|w| cursor.sequence <= w) {
                return Ok(CreateExternalEventOutcome::Redelivered { sequence: None });
            }
        }
        Some(ExternalEventDedupe::Key(key)) => {
            if let Some(sequence) =
                recorded_external_event(&mut **tx, schema, &adapter.id, key).await?
            {
                return Ok(CreateExternalEventOutcome::Redelivered {
                    sequence: Some(sequence),
                });
            }
        }
        None => {}
    }

    let next_seq = next_sequence(&mut **tx, &adapter.event_type.bounded_context.name).await?;
    let event = crate::event_store::create_external_event(
        adapter,
        item.payload,
        item.source_content,
        item.source_context,
        item.correlation_id,
        item.causation_id,
        next_seq,
        now,
        |subject_key, subject_value| {
            let (key, _, data_key) = resolved
                .get(&(subject_key.to_string(), subject_value.to_string()))
                .expect(
                    "resolve_encryption_keys pre-resolved every subject sensitive_field_subjects \
                     named",
                );
            (key.clone(), data_key.clone())
        },
        blind,
    )?;
    let encryption_key_ids = encryption_key_ids(&event.encryption_keys, resolved);
    insert_event_and_update_sync_projections_in_tx(
        tx,
        &event,
        None,
        projection_dispatcher,
        &encryption_key_ids,
        sync_projections,
    )
    .await?;
    match &dedupe {
        Some(ExternalEventDedupe::Watermark(cursor)) => {
            advance_dedupe_watermark(
                &mut **tx,
                schema,
                &adapter.id,
                cursor.partition_key,
                cursor.sequence,
                now,
            )
            .await?;
        }
        Some(ExternalEventDedupe::Key(key)) => {
            record_external_message_key(&mut **tx, schema, &adapter.id, key, event.sequence, now)
                .await?;
        }
        None => {}
    }
    Ok(CreateExternalEventOutcome::Created(Box::new(event)))
}

/// `CreateDirectEvent`'s own twin of `create_and_insert_external_event`
/// above - same reasoning, same fix, only the adapter type and the
/// absent `source_content`/`source_context` differ.
#[allow(clippy::too_many_arguments)]
#[tracing::instrument(skip_all)]
pub async fn create_and_insert_direct_event(
    pool: &Pool,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    adapter: &DirectCreationToken,
    payload: String,
    correlation_id: Option<String>,
    causation_id: Option<String>,
    now: DateTime<Utc>,
    key_service: Option<&KeyService>,
    blind: &crate::blind::BlindIndex,
) -> crate::error::Result<Event> {
    // See `create_and_insert_external_event`'s identical check.
    crate::event_store::check_create_direct_event(
        adapter,
        &payload,
        correlation_id.as_deref(),
        causation_id.as_deref(),
        blind,
    )?;
    let bounded_context_name = adapter.event_type.bounded_context.name.clone();

    let mut resolved = std::collections::HashMap::new();
    resolve_encryption_keys(
        pool,
        &bounded_context_name,
        &adapter.event_type.sensitive_fields,
        &payload,
        key_service,
        &mut resolved,
    )
    .await?;

    let mut tx = pool.begin().await?;
    let next_seq = next_sequence(&mut *tx, &bounded_context_name).await?;
    // docs/architecture.md §209: tags are derived below, under the lock a
    // rotation holds - of the generation stored now.
    refresh_blind_generations(&mut tx, &bounded_context_name, blind).await?;
    let event = crate::event_store::create_direct_event(
        adapter,
        payload,
        correlation_id,
        causation_id,
        next_seq,
        now,
        |subject_key, subject_value| {
            let (key, _, data_key) = resolved
                .get(&(subject_key.to_string(), subject_value.to_string()))
                .expect(
                    "resolve_encryption_keys pre-resolved every subject sensitive_field_subjects \
                     named",
                );
            (key.clone(), data_key.clone())
        },
        blind,
    )?;
    let encryption_key_ids = encryption_key_ids(&event.encryption_keys, &resolved);
    // Fetched only now - after `next_sequence` above already took this
    // bounded context's own lock - see `insert_event_and_update_sync_projections_in_tx`'s
    // own doc comment on why that ordering, not "as early as possible", is
    // what keeps this read race-free against `promote_projection_rebuild`.
    let sync_projections = sync_projection_names(&mut tx, &bounded_context_name).await?;
    insert_event_and_update_sync_projections_in_tx(
        &mut tx,
        &event,
        None,
        projection_dispatcher,
        &encryption_key_ids,
        &sync_projections,
    )
    .await?;
    tx.commit().await?;
    broadcaster.publish(&event);
    record_event_appended(&event);
    notify_event_appended(pool, &event, broadcaster.instance_id()).await;
    event_cache.append(&event).await;

    Ok(event)
}

/// What `submit_command` below settles on - either governs a real insert
/// (`Accepted`, already persisted by the time this returns) or a
/// legitimate business rejection (`Rejected`, nothing persisted at all).
/// `ProcessCommand`'s own two `CommandDecision` outcomes, but carrying
/// the *actual* result - which may differ from the caller's own
/// optimistic `dispatch` call if a DCB conflict forced a retry, see
/// `submit_command`'s own doc comment.
#[derive(Debug)]
#[non_exhaustive]
pub enum SubmitCommandOutcome {
    Accepted {
        // Boxed for the same reason `EventOrigin::CommandTriggered`'s own
        // `command` field is - `Command` is large enough next to
        // `Rejected`'s two `String`s that clippy's `large_enum_variant`
        // flags it otherwise.
        command: Box<Command>,
        events: Vec<Event>,
    },
    Rejected {
        reason: String,
        kind: String,
        // issue #7's DCB conflict visualizer: the tag-scoped
        // event set `decide()` actually evaluated against for *this*
        // rejection - the caller-supplied `matching_events` parameter
        // below for an ordinary rejection, or the freshly-recomputed
        // set from this function's own DCB-conflict redispatch branch
        // if that's what produced it (never the caller's now-stale
        // pre-lock one in that case) - see this function's own doc
        // comment.
        matching_events: Vec<Event>,
    },
    /// A duplicate submission bearing an `idempotency_key` that already
    /// produced a real `Accepted` outcome (issue #12) - not a
    /// new decision, the *original* one, verbatim. `decide()` never ran
    /// again; no event was inserted again. Rejected outcomes are never
    /// deduplicated - they have zero side effects, so a duplicate one is
    /// simply re-decided fresh, correctly, every time (see
    /// `submit_command`'s own doc comment for why).
    Deduplicated { triggered_event_sequences: Vec<i64> },
}

/// A `submit_command` call's own snapshot-acceleration context
/// ([docs/architecture.md §19](../../../docs/architecture.md#optional-snapshotting-matching-events)) - `Some` when the caller took the
/// snapshot-accelerated path (`CommandDispatcher::dispatch_from_snapshot`)
/// instead of the ordinary one (`dispatch`) for its own `initial_decision`.
/// `state_json` is handed to `dispatch_from_snapshot` again on a
/// DCB-conflict redispatch (made fresh, here, exactly like the ordinary
/// path's own `dispatch` re-call); `as_of_sequence` is the snapshot's
/// own high-water mark - the floor `original_highest` needs when
/// `bounded_context_events` (the caller's own `events_since_snapshot`)
/// is empty, since a plain `.unwrap_or(-1)` there would wrongly treat
/// "nothing changed since the snapshot" as "nothing has ever happened".
///
/// **Known limitation, narrow and audit-only**: `Command.consistency_boundary`
/// can under-report as `None` for a snapshot-accelerated command whose
/// own `events_since_snapshot` is empty, even though the snapshot's own
/// folded prefix represents real prior history -
/// `consistency_boundary_and_matching_events` has no way to know about
/// `as_of_sequence`, only about `bounded_context_events`. This never
/// affects `decide_from_snapshot`'s own inputs or the decision it
/// produces - only that one audit field - so it's left as a documented
/// gap for this pass rather than widening `process_command`'s own
/// signature too.
pub struct SnapshotContext<'a> {
    pub state_json: &'a str,
    pub as_of_sequence: i64,
}

/// The shared "locked half" of `ProcessCommand` - `skilj-rest`'s
/// `post_commands_trigger` and `skilj-graphql`'s `submitCommand` both
/// delegate to this once authorisation is done and `initial_decision` -
/// `dispatch`'s own first, optimistic, unlocked call against
/// `bounded_context_events` - is already in hand. Implements the
/// optimistic-then-locked pattern the note above the rules in
/// specs/skilj.allium describes: "Only the final re-check and insert
/// need the lock; reading matching events and running decide()
/// beforehand does not."
///
/// Opens one transaction and locks `bounded_context`'s own `sequence`
/// row up front - `SELECT ... FOR UPDATE`, peeking its current value
/// rather than `next_sequence`'s own increment-and-return, since how
/// many sequence numbers this submission ends up needing isn't known
/// until the decision that finally governs it is. If that peek shows
/// more has been committed than `bounded_context_events` (the caller's
/// own optimistic read - already tag-scoped to `consistency_tags` by
/// every real call site, [docs/architecture.md §19](../../../docs/architecture.md#optional-snapshotting-matching-events)'s "Problem 1" fix)
/// already reflected, and at least one of those new arrivals matches
/// `consistency_tags`, that is the DCB conflict this lock exists to
/// catch (see `DynamicConsistencyBoundaryHonoured`):
/// `dispatch` is called again, now with a `matching_events` set that
/// includes the new arrival, and the fresh decision it returns supersedes
/// `initial_decision`. At most one such retry is ever needed - once the
/// lock is held, nothing else can commit to this bounded context until
/// this transaction ends (see the note above the rules: "no concurrent
/// committer for the same bounded context can be interleaved while the
/// row is locked"), so there is nothing further this call could miss.
///
/// Whichever decision ends up governing, `event_store::process_command`,
/// `insert_command`, and `insert_event_and_update_sync_projections_in_tx`
/// (once per triggered event) all run inside that same transaction and
/// share its one commit; a rejection (initial or retried) instead leaves
/// `tx` uncommitted - dropped with nothing but the read-only peek lock
/// ever taken, the same implicit-rollback-on-drop every early `?` return
/// elsewhere in this module already relies on. Either way,
/// `SequenceIsGaplessPerBoundedContext` holds for real: any failure
/// anywhere in this function (a rejection, an unregistered event type, a
/// database error) rolls the whole transaction back, sequence allocation
/// included, rather than burning a sequence number on a write that never
/// lands - the actual bug this function exists to close.
#[allow(clippy::too_many_arguments)]
#[tracing::instrument(
    skip_all,
    fields(
        bounded_context = %command_type.bounded_context.name,
        command_type = %command_type.name,
    )
)]
pub async fn submit_command(
    pool: &Pool,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    command_type: &CommandType,
    payload: &str,
    client_id: &str,
    correlation_id: Option<&str>,
    causation_id: Option<&str>,
    bounded_context_events: &[Event],
    consistency_tags: &[Tag],
    matching_events: &[Event],
    initial_decision: crate::shared::CommandDecision,
    key_service: Option<&KeyService>,
    now: DateTime<Utc>,
    snapshot: Option<SnapshotContext<'_>>,
    snapshot_states: &[crate::plugin::SnapshotState],
    idempotency_key: Option<&str>,
    covered_through: Option<i64>,
    context: &crate::plugin::DecisionContext,
) -> crate::error::Result<SubmitCommandOutcome> {
    let bounded_context_name = command_type.bounded_context.name.clone();

    // issue #32: a pre-lock warm-up for the common, no-DCB-conflict
    // path - mirrors `create_and_insert_external_event`/
    // `create_and_insert_direct_event`'s own "resolve encryption keys
    // before opening the transaction" shape, extended here to event-type
    // lookups too. See `warm_up_event_types_and_encryption_keys`'s own
    // doc comment for why this is always safe, never just an
    // optimisation this function's own correctness depends on.
    let (event_types_by_name, resolved) = warm_up_event_types_and_encryption_keys(
        pool,
        &bounded_context_name,
        command_type,
        payload,
        &initial_decision,
        key_service,
    )
    .await?;

    let mut tx = pool.begin().await?;
    let locked_highest = lock_bounded_context_sequence(&mut tx, &bounded_context_name).await?;
    // Fetched once for the whole submission, not once per event (
    // issue #32) - and only now, after the lock above is already held,
    // which is what keeps this read race-free against
    // `promote_projection_rebuild` (see
    // `insert_event_and_update_sync_projections_in_tx`'s own doc comment).
    let sync_projections = sync_projection_names(&mut tx, &bounded_context_name).await?;

    let outcome = submit_one_command_in_tx(
        &mut tx,
        dispatcher,
        projection_dispatcher,
        command_type,
        payload,
        client_id,
        correlation_id,
        causation_id,
        bounded_context_events,
        consistency_tags,
        matching_events,
        initial_decision,
        key_service,
        now,
        snapshot,
        snapshot_states,
        idempotency_key,
        locked_highest,
        &sync_projections,
        &[],
        event_types_by_name,
        resolved,
        covered_through,
        context,
    )
    .await?;

    tx.commit().await?;
    broadcast_appended_events(pool, broadcaster, event_cache, &outcome).await;

    Ok(outcome)
}

/// The pre-lock warm-up `submit_command`/`command_batcher::CommandBatcher::submit`
/// both run before ever opening a transaction: every `EventType` an
/// accepted `initial_decision`'s own event_specs names, and every
/// `EncryptionKey` those events' (and the command's own) sensitive
/// fields need. A no-op (both maps come back empty) for a `Rejected`
/// `initial_decision` - nothing to warm up for a command that was never
/// going to write anything.
///
/// **Always safe, never a correctness dependency**: `submit_one_command_in_tx`'s
/// own post-lock code re-runs the identical resolution unconditionally
/// against whatever `event_specs` actually governs by the time it runs
/// (the redispatched ones, if a DCB conflict forced a retry) - its
/// `Entry::Vacant`/`resolved.contains_key` guards make every call here a
/// no-op the second time, and tolerate this warm-up being partial, stale,
/// or skipped entirely just as well as they tolerate it being complete.
/// This function exists purely to shorten the bounded-context lock's own
/// hold span (`submit_command`) or to move that work fully in parallel,
/// before a request ever joins a shared batch queue at all
/// (`CommandBatcher::submit`) - not to change what's correct.
pub async fn warm_up_event_types_and_encryption_keys(
    pool: &Pool,
    bounded_context_name: &str,
    command_type: &CommandType,
    payload: &str,
    initial_decision: &crate::shared::CommandDecision,
    key_service: Option<&KeyService>,
) -> crate::error::Result<(
    std::collections::HashMap<String, EventType>,
    std::collections::HashMap<(String, String), (EncryptionKey, i64, DataKey)>,
)> {
    let mut event_types_by_name: std::collections::HashMap<String, EventType> =
        std::collections::HashMap::new();
    let mut resolved = std::collections::HashMap::new();
    if let crate::shared::CommandDecision::Accepted { events } = initial_decision {
        for spec in events {
            if let std::collections::hash_map::Entry::Vacant(entry) =
                event_types_by_name.entry(spec.event_type.clone())
            {
                // `command_type` already carries the bounded context's
                // row, read moments ago (docs/architecture.md §196).
                if let Some(et) =
                    get_event_type_with_bc(pool, &command_type.bounded_context, &spec.event_type)
                        .await?
                {
                    entry.insert(et);
                }
            }
        }
        resolve_encryption_keys(
            pool,
            bounded_context_name,
            &command_type.sensitive_fields,
            payload,
            key_service,
            &mut resolved,
        )
        .await?;
        for spec in events {
            if let Some(event_type) = event_types_by_name.get(&spec.event_type) {
                let spec_payload = spec.payload.to_string();
                resolve_encryption_keys(
                    pool,
                    bounded_context_name,
                    &event_type.sensitive_fields,
                    &spec_payload,
                    key_service,
                    &mut resolved,
                )
                .await?;
            }
        }
    }
    Ok((event_types_by_name, resolved))
}

/// The `SELECT ... FOR UPDATE` peek `submit_command`'s own doc comment
/// describes, pulled out so `submit_command_batch`'s leader can take it
/// exactly once per batch too, instead of once per command - the actual
/// mechanism this whole pass (issue #32, round two) exists to
/// amortise across as many concurrently-arriving commands as possible.
async fn lock_bounded_context_sequence(
    tx: &mut Transaction<'_, Postgres>,
    bounded_context: &str,
) -> crate::error::Result<i64> {
    let schema = schema_ident(bounded_context);
    let (locked_highest,): (i64,) = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT next_value FROM {schema}.sequence FOR UPDATE"
    )))
    .fetch_one(&mut **tx)
    .await?;
    Ok(locked_highest)
}

/// `EventSubscription`'s own real-time delivery - after the commit, not
/// before, the same rule `insert_event_and_update_sync_projections`
/// itself already follows. Shared by `submit_command`'s own single-request
/// path and `command_batcher::CommandBatcher`'s batched one - both commit
/// once, then need every event that commit produced broadcast exactly
/// this way; a no-op for `Rejected`/`Deduplicated` outcomes, which
/// produced nothing to broadcast.
pub async fn broadcast_appended_events(
    pool: &Pool,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    outcome: &SubmitCommandOutcome,
) {
    broadcast_appended_batch(pool, broadcaster, event_cache, std::iter::once(outcome)).await;
}

/// [`broadcast_appended_events`] for every outcome of a committed batch at
/// once: each event is published and cached as before, and the other
/// instances are notified of all of them in one statement rather than one
/// round trip per event, which the batch's callers used to wait out
/// before getting their answers (docs/architecture.md §196).
pub async fn broadcast_appended_batch<'a>(
    pool: &Pool,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    outcomes: impl IntoIterator<Item = &'a SubmitCommandOutcome>,
) {
    let events: Vec<&Event> = outcomes
        .into_iter()
        .flat_map(|outcome| match outcome {
            SubmitCommandOutcome::Accepted { events, .. } => events.as_slice(),
            _ => &[],
        })
        .collect();
    for event in &events {
        broadcaster.publish(event);
        record_event_appended(event);
        event_cache.append(event).await;
    }
    notify_events_appended(pool, &events, broadcaster.instance_id()).await;
}

/// Where a command's re-check under the lock starts: where its optimistic
/// read is complete through, when the caller knows that, else the highest
/// event the read holds (or the snapshot's position, when it holds none) -
/// the larger of the two, since a read from Postgres can hold an event
/// above the position it reports (docs/architecture.md §178).
fn recheck_from(
    bounded_context_events: &[Event],
    snapshot_as_of: Option<i64>,
    covered_through: Option<i64>,
) -> i64 {
    let original_highest = bounded_context_events
        .iter()
        .map(|e| e.sequence)
        .max()
        .unwrap_or_else(|| snapshot_as_of.unwrap_or(-1));
    covered_through.map_or(original_highest, |c| c.max(original_highest))
}

/// The re-checks of every command in `batch` whose read is older than
/// the lock, as one tag query (docs/architecture.md §196): over the union
/// of their consistency tags, from the lowest position any of them starts
/// at, up to `locked_highest`. Each command then keeps its own part in
/// memory - the events past its own position matching its own tags -
/// which is exactly what its own query would have returned, through the
/// same tag index. `None` when no command needs a re-check. A command
/// whose query reads nothing needs none (docs/architecture.md §201), and
/// its tags would only widen the query.
///
/// The tag list is padded, repeating its last tag, to a power of two: the
/// query's text has one `OR` term per tag, and a batch's union varies in
/// size, so unpadded it would be a new prepared statement for nearly
/// every batch.
async fn batch_recheck_delta(
    conn: &mut sqlx::PgConnection,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    batch: &[BatchedCommand],
    locked_highest: i64,
) -> crate::error::Result<Option<Vec<Event>>> {
    let mut from: Option<i64> = None;
    let mut tags: Vec<Tag> = Vec::new();
    for item in batch {
        let covered = recheck_from(
            &item.bounded_context_events,
            item.snapshot.as_ref().map(|s| s.as_of_sequence),
            item.covered_through,
        );
        if covered >= locked_highest
            || item.consistency_tags.is_empty()
            || crate::event_store::query_reads_nothing(&command_consistency_query(
                dispatcher,
                &item.command_type,
                &item.payload,
            )?)
        {
            continue;
        }
        from = Some(from.map_or(covered, |f| f.min(covered)));
        for tag in &item.consistency_tags {
            if !tags.contains(tag) {
                tags.push(tag.clone());
            }
        }
    }
    let (Some(from), Some(first)) = (from, batch.first()) else {
        return Ok(None);
    };
    let padded = tags.len().next_power_of_two();
    let last = tags
        .last()
        .cloned()
        .expect("a command needing a re-check has tags");
    tags.resize(padded, last);
    let mut known = std::collections::HashMap::new();
    for item in batch {
        for (name, event_type) in &item.event_types_by_name {
            known
                .entry(name.clone())
                .or_insert_with(|| event_type.clone());
        }
    }
    let started = std::time::Instant::now();
    let mut events = list_events_for_bounded_context_matching_tags_with_bc(
        conn,
        &first.command_type.bounded_context,
        &tags,
        Some(from),
        Some(&known),
        None,
    )
    .await?;
    events.retain(|e| e.sequence <= locked_highest);
    tracing::debug!(
        bounded_context = %first.command_type.bounded_context.name,
        delta_query_us = started.elapsed().as_micros(),
        delta_rows = events.len(),
        "command decide delta query"
    );
    Ok(Some(events))
}

/// The highest position any of `states` holds its value's events
/// through: a snapshot item's part of a command's consistency boundary
/// (docs/architecture.md §202). `None` when there are no states, or none
/// holds an event.
fn states_boundary(states: &[crate::plugin::SnapshotState]) -> Option<i64> {
    states
        .iter()
        .map(|state| state.folded_through)
        .filter(|position| *position >= 0)
        .max()
}

/// Idempotency keys claimed by commands earlier in the same batch, by
/// `(command type, client id, key)`, with the sequences their events got
/// - see [`decide_command_in_tx`].
type BatchIdempotencyKeys = std::collections::HashMap<(String, String, String), Vec<i64>>;

/// What [`decide_command_in_tx`] settles on for a command whose decision
/// was `Accepted` - everything [`finish_accepted_command_in_tx`] needs to
/// actually write it, once sequence numbers are available. Kept as its
/// own struct, rather than inlining decide's tail into finish, is what
/// lets `commit_command_batch`'s own loop insert a [`SequencePool`] draw
/// in between the two calls.
struct AcceptedDecision {
    event_specs: Vec<crate::shared::EventSpec>,
    /// The command's consistency boundary: the highest sequence among the
    /// events its final decision saw that match its consistency tags
    /// (docs/architecture.md §196).
    consistency_boundary: Option<i64>,
    /// The command type's own query, derived from the payload - recorded
    /// on the command (docs/architecture.md §198).
    consistency_query: Vec<QueryItem>,
    event_types_by_name: std::collections::HashMap<String, EventType>,
    /// What the command's events' blind tags are hashed with - the
    /// dispatcher's, carried to where they're derived.
    blind: crate::blind::BlindIndex,
}

/// [`decide_command_in_tx`]'s own return type - either a terminal outcome
/// (`Rejected`/`Deduplicated`) that never needs a sequence number at all,
/// or an [`AcceptedDecision`] still needing [`finish_accepted_command_in_tx`]
/// to actually persist it.
enum DecideOutcome {
    Terminal(SubmitCommandOutcome),
    Accepted(AcceptedDecision),
}

/// The read-only, no-sequence-number-needed half of what used to be one
/// `submit_one_command_in_tx` - split out (issue #32, round
/// three: shrinking a batch's own per-command round trips further, after
/// round two's group commit already amortised the lock acquisition
/// itself) so `commit_command_batch`'s loop can run this directly
/// against the *leader's own* `tx`, not a per-command `SAVEPOINT`. That
/// matters for exactly one reason: it lets a [`SequencePool`] reservation -
/// acquired against that same `tx`, in the gap between this call and
/// [`finish_accepted_command_in_tx`]'s own `SAVEPOINT` - survive a later
/// command's real failure instead of being rolled back with it, which is
/// what makes pooling sequence numbers across several commands safe at
/// all. See `SequencePool`'s own doc comment for the full reasoning.
///
/// Never touches `next_sequence_batch`, `resolve_encryption_keys`,
/// `process_command`, or any insert - everything here is either a pure
/// function or a read on `conn` - the lock holder's own connection, never
/// a second pooled one (docs/architecture.md §117) - so running it
/// directly on a long-lived `tx` shared by many commands, rather than
/// inside its own disposable transaction, changes nothing about what it
/// can safely see or do. A decider error is a Rust `Err` and stays
/// per-command; a failing read means the connection itself is in
/// trouble, which fails the batch - see `commit_command_batch`'s own
/// comment.
///
/// `event_types_by_name` arrives already warmed up (see
/// `warm_up_event_types_and_encryption_keys`) and is grown in place for
/// whatever a redispatch still needs - identical to how `submit_command`
/// itself used to do this inline.
#[allow(clippy::too_many_arguments)]
async fn decide_command_in_tx(
    conn: &mut sqlx::PgConnection,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    command_type: &CommandType,
    payload: &str,
    client_id: &str,
    bounded_context_events: &[Event],
    consistency_tags: &[Tag],
    matching_events: &[Event],
    initial_decision: crate::shared::CommandDecision,
    snapshot: Option<SnapshotContext<'_>>,
    snapshot_states: &[crate::plugin::SnapshotState],
    idempotency_key: Option<&str>,
    locked_highest: i64,
    extra_committed_events: &[Event],
    mut event_types_by_name: std::collections::HashMap<String, EventType>,
    covered_through: Option<i64>,
    batch_idempotency_keys: Option<&BatchIdempotencyKeys>,
    batch_delta: Option<&[Event]>,
    slow: Option<&crate::slow_command::SlowCommandWarnings>,
    context: &crate::plugin::DecisionContext,
) -> crate::error::Result<DecideOutcome> {
    let bounded_context_name = command_type.bounded_context.name.clone();
    let schema = schema_ident(&bounded_context_name);

    // issue #12: a cached prior answer, not a new decision -
    // checked as early as possible, right after the lock that makes this
    // race-free (see `lookup_idempotency_key`'s own doc comment).
    // `initial_decision`/the redispatch logic below never runs on a hit -
    // nothing is written, and this command never reaches
    // `finish_accepted_command_in_tx` at all.
    //
    // Read on the lock holder's own connection (docs/architecture.md
    // §117), so it also sees a key an earlier command in the same,
    // still-uncommitted batch claimed: that command's savepoint was
    // released into this same transaction.
    if let Some(key) = idempotency_key {
        // A key an earlier command in this batch claimed, when the batch
        // decides everything before writing anything (docs/architecture.md
        // §196) - not in the table yet.
        let claimed = batch_idempotency_keys.and_then(|claimed| {
            claimed
                .get(&(
                    command_type.name.clone(),
                    client_id.to_string(),
                    key.to_string(),
                ))
                .cloned()
        });
        let triggered = match claimed {
            Some(sequences) => Some(sequences),
            None => {
                lookup_idempotency_key(&mut *conn, &schema, &command_type.name, client_id, key)
                    .await?
            }
        };
        if let Some(triggered_event_sequences) = triggered {
            return Ok(DecideOutcome::Terminal(
                SubmitCommandOutcome::Deduplicated {
                    triggered_event_sequences,
                },
            ));
        }
    }

    // docs/architecture.md §209: the command's tags, and the history read
    // with them, were derived before the lock. If a key rotation of this
    // bounded context committed since, they are of the old generation and
    // match nothing stored: derive them again now that nothing can rotate,
    // and send the command round once more if they changed. Compared per
    // command, not per refresh - an earlier command, in this batch or on
    // another task, may have refreshed the generations already. A query's
    // blind keys are among the command's own tags (`build()` checks it), so
    // these cover it too.
    let blind = dispatcher.blind_index();
    if blind.declares_any(&bounded_context_name) {
        refresh_blind_generations(&mut *conn, &bounded_context_name, &blind).await?;
        let current = crate::event_store::derive_tags(
            &command_type.tag_mappings,
            payload,
            &blind,
            &bounded_context_name,
        )?;
        if current != consistency_tags {
            return Err(crate::blind::Error::Rotated {
                bounded_context: bounded_context_name,
            }
            .into());
        }
    }

    let mut final_decision = initial_decision;
    // docs/architecture.md §198: what the command reads and conflicts on.
    // Without a query of its own, one item per consistency tag - every
    // event carrying any of them, as before.
    let consistency_query = command_consistency_query(dispatcher, command_type, payload)?;
    let query = crate::event_store::effective_query(&consistency_query, consistency_tags);
    // docs/architecture.md §196: no copy of the history unless a conflict
    // below needs an extended one. The boundary is a plain maximum, raised
    // by the delta's.
    let mut consistency_boundary =
        crate::event_store::query_boundary(&query, bounded_context_events)
            .max(states_boundary(snapshot_states));
    // issue #7: `None` is the caller's own pre-lock set,
    // replaced below only if a DCB conflict forced a redispatch -
    // whichever one actually produced `final_decision` is the one a
    // rejection reports (see `SubmitCommandOutcome::Rejected`'s own doc
    // comment). Copied only for a rejection.
    let mut final_matching_events: Option<Vec<Event>> = None;

    // Something committed between the caller's own optimistic read and
    // this lock - either before the lock (`locked_highest >
    // original_highest`, queried up to `locked_highest`) or by an earlier
    // command in this same batch (`extra_committed_events`, kept in
    // memory so a batch doesn't query once per command for it). Only a
    // match on our own consistency_tags is an actual DCB conflict; see
    // docs/architecture.md §19's "Problem 1" fix for why the query is
    // tag-indexed rather than an unfiltered range scan.
    //
    // It starts where the optimistic read is complete through, when the
    // caller knows that, else at the highest event the read holds. Not
    // just the latter: for a tag with no recent events that is far back,
    // and the query below walked the bounded context's history from there
    // for every command, under the lock (docs/architecture.md §178). The
    // larger of the two: a read from Postgres can hold an event above the
    // position it reports (it saw a later commit), and nothing it holds
    // must come back as new.
    let covered = recheck_from(
        bounded_context_events,
        snapshot.as_ref().map(|s| s.as_of_sequence),
        covered_through,
    );
    // The batch's tag query is over the commands' consistency tags, from
    // the command type as stored. It holds every event matching an item
    // only when the item has one of those tags: an event matching the item
    // carries all of the item's tags. An item with no tags, or with tags
    // the stored type no longer maps - a newer instance re-registered it
    // during a rolling deploy, or an admin did - isn't covered, and such a
    // command re-checks with a query of its own (docs/architecture.md
    // §200).
    let batch_delta = batch_delta.filter(|_| {
        query
            .iter()
            .all(|item| item.tags.iter().any(|tag| consistency_tags.contains(tag)))
    });
    let mut delta = if let Some(batch_delta) = batch_delta {
        // docs/architecture.md §196: the batch read every command's
        // re-check range in one query, over all their tags - this
        // command's part of it.
        batch_delta
            .iter()
            .filter(|e| {
                e.sequence > covered
                    && e.sequence <= locked_highest
                    && crate::event_store::query_matches(&query, e)
            })
            .cloned()
            .collect()
    } else if crate::event_store::query_reads_nothing(&consistency_query) {
        // docs/architecture.md §201: no event can match, so none conflicts.
        Vec::new()
    } else if locked_highest > covered && !consistency_query.is_empty() {
        // Every event matching any item counts, however many matches the
        // item keeps: a newer one displaces the oldest the command
        // decided on.
        let every_match: Vec<QueryItem> = query
            .iter()
            .map(|item| QueryItem {
                latest: None,
                ..item.clone()
            })
            .collect();
        let mut result = list_events_matching_query_with_bc(
            &mut *conn,
            &command_type.bounded_context,
            &every_match,
            Some(covered),
            Some(&event_types_by_name),
        )
        .await?;
        result.retain(|e| e.sequence <= locked_highest);
        result
    } else if locked_highest > covered {
        // `command_type.bounded_context` is already this exact row -
        // every command a `CommandBatcher` batch ever holds shares one
        // bounded context (the queue is keyed on it), so there is never
        // a fresher copy to fetch here. See
        // `list_events_for_bounded_context_matching_tags_with_bc`'s own
        // doc comment for why re-fetching it per command was pure
        // round-trip waste inside the batch leader's held lock.
        //
        // Timed separately (issue #32, round four investigation)
        // - `commit_command_batch`'s own per-batch `decide_us` total was
        // far higher than CPU-only decide work should cost; this pins
        // down whether this specific query, firing whenever a busy
        // batch's fixed `locked_highest` has outrun some individual
        // command's own pre-lock snapshot (which real concurrent load
        // makes the common case, not the rare-conflict case this branch
        // was written for), is where that time actually goes.
        let delta_query_started = std::time::Instant::now();
        let mut result = list_events_for_bounded_context_matching_tags_with_bc(
            &mut *conn,
            &command_type.bounded_context,
            consistency_tags,
            Some(covered),
            Some(&event_types_by_name),
            None,
        )
        .await?;
        // On the lock holder's own connection this also returns what an
        // earlier command in this batch inserted (above `locked_highest`);
        // those come from `extra_committed_events` below instead.
        result.retain(|e| e.sequence <= locked_highest);
        // `debug`: one line per command was `info` (docs/architecture.md §178).
        tracing::debug!(
            bounded_context = %bounded_context_name,
            delta_query_us = delta_query_started.elapsed().as_micros(),
            delta_rows = result.len(),
            "command decide delta query"
        );
        result
    } else {
        Vec::new()
    };
    delta.extend(
        extra_committed_events
            .iter()
            .filter(|e| e.sequence > covered && crate::event_store::query_matches(&query, e))
            .cloned(),
    );

    if !delta.is_empty() {
        let mut extended = Vec::with_capacity(bounded_context_events.len() + delta.len());
        extended.extend_from_slice(bounded_context_events);
        extended.extend(delta);
        extended.sort_by_key(|e| e.sequence);
        // The query selects again over the extended history: a newer
        // match displaces an item's oldest kept one when it keeps a count.
        // A snapshot item's new events are folded into its state instead
        // (docs/architecture.md §202).
        let redispatch_matching_events = crate::event_store::select_matching_events(
            &decided_on(&consistency_query, consistency_tags),
            &extended,
        );
        let mut redispatch_states = snapshot_states.to_vec();
        if !redispatch_states.is_empty() {
            let snapshots = dispatcher
                .snapshots()
                .ok_or_else(|| unregistered_snapshot(&redispatch_states[0].snapshot))?;
            fold_into_snapshot_states(
                snapshots,
                &bounded_context_name,
                &consistency_query,
                &mut redispatch_states,
                &extended,
            )?;
        }
        consistency_boundary = crate::event_store::query_boundary(&query, &extended)
            .max(states_boundary(&redispatch_states));
        // docs/architecture.md §19: a snapshot-accelerated initial
        // decision redispatches through `dispatch_from_snapshot`
        // again too, not the ordinary `dispatch` - the snapshot's
        // own folded prefix (`snapshot.state_json`) still represents
        // real history `redispatch_matching_events` alone doesn't
        // (it's the tag-indexed delta since the snapshot, same as
        // `bounded_context_events` already was); calling the
        // ordinary path here would silently drop everything the
        // snapshot had already folded.
        let redecide_started = std::time::Instant::now();
        final_decision = match &snapshot {
            Some(ctx) => match dispatcher.dispatch_from_snapshot(
                &bounded_context_name,
                &command_type.name,
                payload,
                ctx.state_json,
                &redispatch_matching_events,
                context,
            ) {
                None => return Err(crate::error::Error::NoDeciderRegistered),
                Some(Err(e)) => return Err(e),
                Some(Ok(d)) => d,
            },
            None => match dispatcher.dispatch_with(
                &bounded_context_name,
                &command_type.name,
                payload,
                &redispatch_matching_events,
                &redispatch_states,
                context,
            ) {
                None => return Err(crate::error::Error::NoDeciderRegistered),
                Some(Err(e)) => return Err(e),
                Some(Ok(d)) => d,
            },
        };
        // docs/architecture.md §203: this one holds up every other
        // command in the bounded context.
        let redecide_time = redecide_started.elapsed();
        tracing::debug!(
            bounded_context = %bounded_context_name,
            command_type = %command_type.name,
            events_decided_on = redispatch_matching_events.len(),
            decide_us = redecide_time.as_micros(),
            "command decide under lock"
        );
        if let Some(slow) = slow {
            slow.note_decide(
                command_type,
                redecide_time,
                redispatch_matching_events.len(),
                true,
            );
        }
        final_matching_events = Some(redispatch_matching_events);
    }

    let event_specs = match final_decision {
        crate::shared::CommandDecision::Rejected { reason, kind } => {
            COMMANDS_PROCESSED.add(
                1,
                &[
                    KeyValue::new("bounded_context", command_type.bounded_context.name.clone()),
                    KeyValue::new("command_type", command_type.name.clone()),
                    KeyValue::new("outcome", "rejected"),
                ],
            );
            return Ok(DecideOutcome::Terminal(SubmitCommandOutcome::Rejected {
                reason,
                kind,
                matching_events: final_matching_events.unwrap_or_else(|| matching_events.to_vec()),
            }));
        }
        crate::shared::CommandDecision::Accepted { events } => events,
    };

    // process_command's own resolve_event_type stays a plain sync closure
    // (decide() and everything downstream is I/O-free per §1.1) - every
    // EventType lookup this call will need happens against the *final*
    // event_specs (the redispatched ones, if a retry happened above).
    // `event_types_by_name` arrived already warmed up for `initial_decision`'s
    // own specs; this loop is what a redispatch's different specs still
    // need, and its `Entry::Vacant` guard means it costs nothing extra
    // when nothing changed.
    for spec in &event_specs {
        if let std::collections::hash_map::Entry::Vacant(entry) =
            event_types_by_name.entry(spec.event_type.clone())
        {
            if let Some(et) =
                get_event_type_with_bc(&mut *conn, &command_type.bounded_context, &spec.event_type)
                    .await?
            {
                entry.insert(et);
            }
        }
    }

    Ok(DecideOutcome::Accepted(AcceptedDecision {
        event_specs,
        consistency_boundary,
        consistency_query,
        event_types_by_name,
        blind: dispatcher.blind_index(),
    }))
}

/// protect_sensitive_fields' own pre-resolution step, for the command's
/// own payload *and* every final event spec's - see
/// `resolve_encryption_keys`'s own doc comment. `resolved` arrived already
/// warmed up, before the lock, for `initial_decision`'s own payloads;
/// what's left is only what a redispatch newly needs. That is provisioned
/// on `conn`, the lock holder's own connection, not the pool
/// (docs/architecture.md §117): this transaction holds the bounded
/// context's `sequence` lock, and every other writer to it waits on that
/// lock holding a pooled connection.
///
/// Every distinct `(subject_key, subject_value)` still needed is gathered
/// up front and deduped (against itself and `resolved`), so no subject is
/// provisioned twice.
async fn provision_missing_encryption_keys(
    conn: &mut sqlx::PgConnection,
    command_type: &CommandType,
    payload: &str,
    event_specs: &[crate::shared::EventSpec],
    event_types_by_name: &std::collections::HashMap<String, EventType>,
    resolved: &mut std::collections::HashMap<(String, String), (EncryptionKey, i64, DataKey)>,
    key_service: Option<&KeyService>,
) -> crate::error::Result<()> {
    let needed_subjects = missing_encryption_subjects(
        command_type,
        payload,
        event_specs,
        event_types_by_name,
        resolved,
    );
    provision_encryption_subjects(conn, command_type, needed_subjects, resolved, key_service).await
}

/// The `(subject_key, subject_value)` pairs `command_type`'s payload and
/// `event_specs` need a key for that `resolved` doesn't have yet - what
/// [`provision_missing_encryption_keys`] provisions.
fn missing_encryption_subjects(
    command_type: &CommandType,
    payload: &str,
    event_specs: &[crate::shared::EventSpec],
    event_types_by_name: &std::collections::HashMap<String, EventType>,
    resolved: &std::collections::HashMap<(String, String), (EncryptionKey, i64, DataKey)>,
) -> Vec<(String, String)> {
    let mut needed_subjects: Vec<(String, String)> =
        crate::event_store::sensitive_field_subjects(&command_type.sensitive_fields, payload);
    for spec in event_specs {
        if let Some(event_type) = event_types_by_name.get(&spec.event_type) {
            needed_subjects.extend(crate::event_store::sensitive_field_subjects(
                &event_type.sensitive_fields,
                &spec.payload.to_string(),
            ));
        }
    }
    needed_subjects.retain(|pair| !resolved.contains_key(pair));
    needed_subjects.sort();
    needed_subjects.dedup();
    needed_subjects
}

/// Provisions a key for each of `needed_subjects` on `conn` into `resolved`.
async fn provision_encryption_subjects(
    conn: &mut sqlx::PgConnection,
    command_type: &CommandType,
    needed_subjects: Vec<(String, String)>,
    resolved: &mut std::collections::HashMap<(String, String), (EncryptionKey, i64, DataKey)>,
    key_service: Option<&KeyService>,
) -> crate::error::Result<()> {
    if !needed_subjects.is_empty() {
        let key_service = key_service.ok_or(encryption::Error::MasterKeyNotConfigured)?;
        for subject in needed_subjects {
            let provisioned = get_or_create_encryption_key_on(
                &mut *conn,
                command_type.bounded_context.clone(),
                &subject.0,
                &subject.1,
                key_service,
            )
            .await?;
            resolved.insert(subject, provisioned);
        }
    }
    Ok(())
}

/// The write half of what used to be one `submit_one_command_in_tx` -
/// everything [`decide_command_in_tx`] couldn't do without real sequence
/// numbers in hand. `sequences` is exactly `decided.event_specs.len()`
/// numbers, already allocated by the caller (a plain `next_sequence_batch`
/// call for `submit_command`'s own batch-of-one path, a shared
/// [`SequencePool`] draw for `commit_command_batch`'s multi-command one) -
/// this function itself never touches `{schema}.sequence` at all.
#[allow(clippy::too_many_arguments)]
async fn finish_accepted_command_in_tx(
    tx: &mut Transaction<'_, Postgres>,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    command_type: &CommandType,
    payload: &str,
    client_id: &str,
    correlation_id: Option<&str>,
    causation_id: Option<&str>,
    key_service: Option<&KeyService>,
    now: DateTime<Utc>,
    idempotency_key: Option<&str>,
    sync_projections: &[String],
    sequences: Vec<i64>,
    decided: AcceptedDecision,
    mut resolved: std::collections::HashMap<(String, String), (EncryptionKey, i64, DataKey)>,
) -> crate::error::Result<SubmitCommandOutcome> {
    let bounded_context_name = command_type.bounded_context.name.clone();
    let schema = schema_ident(&bounded_context_name);
    let AcceptedDecision {
        event_specs,
        consistency_boundary,
        consistency_query,
        event_types_by_name,
        blind,
    } = decided;
    let mut sequences = sequences.into_iter();

    provision_missing_encryption_keys(
        tx,
        command_type,
        payload,
        &event_specs,
        &event_types_by_name,
        &mut resolved,
        key_service,
    )
    .await?;

    let result = crate::event_store::process_command_at_boundary(
        crate::shared::generate_token_id(),
        command_type,
        payload,
        client_id,
        correlation_id,
        causation_id,
        consistency_query,
        consistency_boundary,
        crate::shared::CommandDecision::Accepted {
            events: event_specs,
        },
        |name| event_types_by_name.get(name).cloned(),
        || {
            sequences.next().expect(
                "process_command called next_sequence more times than there are accepted events",
            )
        },
        now,
        |subject_key, subject_value| {
            let (key, _, data_key) = resolved
                .get(&(subject_key.to_string(), subject_value.to_string()))
                .expect(
                    "resolve_encryption_keys pre-resolved every subject sensitive_field_subjects \
                     named",
                );
            (key.clone(), data_key.clone())
        },
        &blind,
    )?;

    // Command and every one of its triggered events, in the one
    // (savepoint-scoped, in the batched path) transaction `tx` has held
    // since the lock above - DynamicConsistencyBoundaryHonoured's actual
    // enforcement: a failure partway through this loop rolls the command
    // insert back too, rather than leaving a persisted Command with only
    // some of its events.
    let command_key_ids = encryption_key_ids(&result.command.encryption_keys, &resolved);
    let command_id = insert_command(tx, &result.command, &command_key_ids).await?;
    for event in &result.events {
        let event_key_ids = encryption_key_ids(&event.encryption_keys, &resolved);
        insert_event_and_update_sync_projections_in_tx(
            tx,
            event,
            Some(command_id),
            projection_dispatcher,
            &event_key_ids,
            sync_projections,
        )
        .await?;
    }

    if let Some(key) = idempotency_key {
        let triggered_event_sequences: Vec<i64> =
            result.events.iter().map(|e| e.sequence).collect();
        insert_idempotency_key(
            &mut **tx,
            &schema,
            &command_type.name,
            client_id,
            key,
            &triggered_event_sequences,
            now,
        )
        .await?;
    }

    COMMANDS_PROCESSED.add(
        1,
        &[
            KeyValue::new("bounded_context", command_type.bounded_context.name.clone()),
            KeyValue::new("command_type", command_type.name.clone()),
            KeyValue::new("outcome", "accepted"),
        ],
    );

    Ok(SubmitCommandOutcome::Accepted {
        command: Box::new(result.command),
        events: result.events,
    })
}

/// `submit_command`'s own batch-of-one composition of [`decide_command_in_tx`]
/// and [`finish_accepted_command_in_tx`], with a plain per-call
/// `next_sequence_batch` in between. Unlike `commit_command_batch`'s own
/// loop, there is only ever one command here, so there is nothing to
/// pool sequence numbers *across* - both halves run on the same flat
/// `tx` `submit_command` opened, with no per-command `SAVEPOINT` layered
/// on top of it at all, so a real failure in either half rolls back that
/// one, whole transaction, exactly as before this function was split in
/// two.
#[allow(clippy::too_many_arguments)]
async fn submit_one_command_in_tx(
    tx: &mut Transaction<'_, Postgres>,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    command_type: &CommandType,
    payload: &str,
    client_id: &str,
    correlation_id: Option<&str>,
    causation_id: Option<&str>,
    bounded_context_events: &[Event],
    consistency_tags: &[Tag],
    matching_events: &[Event],
    initial_decision: crate::shared::CommandDecision,
    key_service: Option<&KeyService>,
    now: DateTime<Utc>,
    snapshot: Option<SnapshotContext<'_>>,
    snapshot_states: &[crate::plugin::SnapshotState],
    idempotency_key: Option<&str>,
    locked_highest: i64,
    sync_projections: &[String],
    extra_committed_events: &[Event],
    event_types_by_name: std::collections::HashMap<String, EventType>,
    resolved: std::collections::HashMap<(String, String), (EncryptionKey, i64, DataKey)>,
    covered_through: Option<i64>,
    context: &crate::plugin::DecisionContext,
) -> crate::error::Result<SubmitCommandOutcome> {
    let bounded_context_name = command_type.bounded_context.name.clone();
    let decided = match decide_command_in_tx(
        tx,
        dispatcher,
        command_type,
        payload,
        client_id,
        bounded_context_events,
        consistency_tags,
        matching_events,
        initial_decision,
        snapshot,
        snapshot_states,
        idempotency_key,
        locked_highest,
        extra_committed_events,
        event_types_by_name,
        covered_through,
        None,
        None,
        None,
        context,
    )
    .await?
    {
        DecideOutcome::Terminal(outcome) => return Ok(outcome),
        DecideOutcome::Accepted(decided) => decided,
    };

    // Allocated inside `tx`, after the lock above, in one round trip for
    // every event this command decided - `next_sequence_batch`, not
    // `event_specs.len()` separate `next_sequence` calls (issue
    // #32). A failure anywhere below (an unregistered event type,
    // encryption resolution, the inserts themselves) rolls the whole
    // allocation back with the rest of this command's own work - the
    // whole transaction, since this path has no per-command `SAVEPOINT`
    // of its own.
    let sequences = next_sequence_batch(
        &mut **tx,
        &bounded_context_name,
        decided.event_specs.len() as i64,
    )
    .await?;

    finish_accepted_command_in_tx(
        tx,
        projection_dispatcher,
        command_type,
        payload,
        client_id,
        correlation_id,
        causation_id,
        key_service,
        now,
        idempotency_key,
        sync_projections,
        sequences,
        decided,
        resolved,
    )
    .await
}

/// The owned equivalent of [`SnapshotContext`] - that type borrows
/// `state_json`, fine for a caller whose own stack frame outlives the
/// call it's passed into, but a [`BatchedCommand`] has to survive being
/// handed to a *different* task (`command_batcher::CommandBatcher`'s
/// batch leader, which may be a different concurrently-running request's
/// own task entirely) - see `BatchedCommand`'s own doc comment.
#[derive(Debug, Clone)]
pub struct OwnedSnapshotContext {
    pub state_json: String,
    pub as_of_sequence: i64,
}

/// One command's worth of everything `submit_one_command_in_tx` needs,
/// entirely owned rather than borrowed - what a request becomes once it
/// has to survive being queued for, and processed by, some other task
/// entirely (`command_batcher::CommandBatcher`'s batch leader is
/// whichever concurrently-submitting caller happened to arrive first;
/// every other command in its batch is, from the leader's own stack
/// frame's perspective, a different task's data). The shared collaborators
/// [`submit_command`]'s own signature also takes - `pool`, `dispatcher`,
/// `projection_dispatcher`, `key_service` - are deliberately
/// *not* part of this struct: within one process they are the same
/// `Arc`/reference for every command a `CommandBatcher` ever processes
/// (all ultimately sourced from the one `Skilj` instance), so the batch
/// leader already has its own copy and simply reuses it for every command
/// in the batch rather than each one carrying a redundant copy.
pub struct BatchedCommand {
    pub command_type: CommandType,
    pub payload: String,
    pub client_id: String,
    pub correlation_id: Option<String>,
    pub causation_id: Option<String>,
    pub bounded_context_events: Vec<Event>,
    /// See `ResolvedCommandSubmission::covered_through`; `None` for a
    /// caller that doesn't know it, whose re-check then starts from the
    /// highest event it does hold.
    pub covered_through: Option<i64>,
    pub consistency_tags: Vec<Tag>,
    pub matching_events: Vec<Event>,
    pub initial_decision: crate::shared::CommandDecision,
    pub now: DateTime<Utc>,
    pub snapshot: Option<OwnedSnapshotContext>,
    /// See `ResolvedCommandSubmission::snapshot_states`
    /// (docs/architecture.md §202).
    pub snapshot_states: Vec<crate::plugin::SnapshotState>,
    pub idempotency_key: Option<String>,
    /// Pre-lock-warmed by this command's own original caller, via
    /// `warm_up_event_types_and_encryption_keys`, before it ever joined a
    /// batch queue - see that function's own doc comment for why this is
    /// always safe and never a correctness dependency.
    pub event_types_by_name: std::collections::HashMap<String, EventType>,
    pub resolved: std::collections::HashMap<(String, String), (EncryptionKey, i64, DataKey)>,
}

/// What one command in a [`submit_command_batch`] call settles on - the
/// same [`SubmitCommandOutcome`] a standalone `submit_command` call would
/// have produced for it, had it run alone; `Err` only for a real failure
/// (an unregistered event type, a database error) that rolled back just
/// this one command's own savepoint, not its batch-mates'.
pub type BatchedCommandResult = crate::error::Result<SubmitCommandOutcome>;

/// What [`begin_command_batch_leader_tx`] hands to [`commit_command_batch`] -
/// see each of their own doc comments for why acquiring the lock and
/// running the batch are split into two functions at all (issue
/// #36).
pub struct CommandBatchLeaderTx {
    tx: Transaction<'static, Postgres>,
    bounded_context_name: String,
    locked_highest: i64,
    sync_projections: Vec<String>,
}

/// The lock-acquiring half of [`submit_command_batch`], pulled out
/// (issue #36) so `command_batcher::CommandBatcher::run_as_leader`
/// can await this - the one part of the batch's own processing whose
/// duration is meant to grow the batch, per this module's own doc comment
/// on the self-tuning design - *before* draining the queue, not after.
/// The previous, unsplit `submit_command_batch` made `run_as_leader` drain
/// first and lock second, which defeated that self-tuning window (a batch
/// almost never grew past whoever raced to become leader) and, worse,
/// meant that if this step alone hung, the caller had no chance to
/// give every already-queued follower a real answer, since draining
/// happened somewhere the caller no longer controlled once this
/// combined function was already inside it.
///
/// `idle_in_transaction_session_timeout`, when `Some`, is issued as a
/// `SET LOCAL` on this transaction's own connection right after opening
/// it, before the lock wait - a defense-in-depth backstop (issue
/// #36's own recommendation #3): if this transaction's connection ever
/// does stall indefinitely - a stuck decider, a hung downstream await,
/// anything that leaves it holding the bounded-context lock without
/// making forward progress - Postgres itself kills the idle session
/// after the timeout, releasing the lock so a later batch can proceed
/// instead of every writer to this bounded context queueing forever
/// behind a wedge no automatic mechanism ever clears. `SET LOCAL` scopes
/// the change to this one transaction; it's gone the moment `tx` commits,
/// rolls back, or (if the timeout itself fires) Postgres closes it, so it
/// never leaks onto whatever this pooled connection is handed to next.
///
/// What the timeout does and doesn't measure: Postgres's idle clock only
/// runs *between* statements on this session, and restarts after each
/// one - so it bounds the gap between two consecutive statements (one
/// command's in-memory decide, or a run of consecutive rejected commands
/// that issue none), never the whole batch. The blocked
/// `SELECT ... FOR UPDATE` lock wait is an *active* statement, so it is
/// not covered (nor meant to be): the timeout only protects the phase
/// after the lock is held.
pub async fn begin_command_batch_leader_tx(
    pool: &Pool,
    bounded_context_name: &str,
    idle_in_transaction_session_timeout: Option<std::time::Duration>,
) -> crate::error::Result<CommandBatchLeaderTx> {
    let mut tx = pool.begin().await?;
    // The timeout rides on the lock statement itself, as `set_config(...,
    // true)` - `SET LOCAL`'s function form - rather than a statement of
    // its own (docs/architecture.md §196). Evaluated as the row is read,
    // possibly before the lock wait ends, which changes nothing: the
    // timeout only counts time the session is idle, never a statement
    // waiting on a lock.
    let schema = schema_ident(bounded_context_name);
    let (locked_highest,): (i64,) = match idle_in_transaction_session_timeout {
        Some(timeout) => {
            sqlx::query_as(sqlx::AssertSqlSafe(format!(
                "SELECT next_value FROM {schema}.sequence \
                 WHERE set_config('idle_in_transaction_session_timeout', $1, true) IS NOT NULL \
                 FOR UPDATE"
            )))
            .bind(format!("{}ms", timeout.as_millis()))
            .fetch_one(&mut *tx)
            .await?
        }
        None => (lock_bounded_context_sequence(&mut tx, bounded_context_name).await?,),
    };
    let sync_projections = sync_projection_names(&mut tx, bounded_context_name).await?;
    Ok(CommandBatchLeaderTx {
        tx,
        bounded_context_name: bounded_context_name.to_string(),
        locked_highest,
        sync_projections,
    })
}

/// A prefetched, batch-local block of not-yet-consumed sequence numbers -
/// `commit_command_batch`'s own answer to `next_sequence_batch` being
/// called once per command instead of once per batch (issue #32,
/// round three). Reserves numbers in chunks against the *leader's own*
/// `tx`, never a per-command `SAVEPOINT` - specifically so a reservation
/// survives a later command's real failure instead of being rolled back
/// with it: today's per-command `next_sequence_batch` call is what
/// currently makes gapless sequencing safe for a command that fails
/// partway through (its own `SAVEPOINT` rollback un-reserves exactly what
/// it asked for); pooling numbers across several commands means a
/// command can end up holding numbers it never uses (a *later* command in
/// the same batch is the one that fails, or the pool simply over-reserved
/// as a heuristic), and those must still never be lost or duplicated.
///
/// `SequenceIsGaplessPerBoundedContext` stays honoured by two rules,
/// together: (1) a draw's numbers are only ever permanently discarded
/// ([`Self::confirm_last_draw`]) once the command that used them has
/// actually committed; (2) a draw that instead fails
/// ([`Self::return_last_draw`]) goes back onto the *front* of the queue,
/// in its original order, so it is the very next thing handed to
/// whichever command asks next - recycled, never wasted mid-batch. Only
/// genuinely unused numbers - ones nobody ever drew, or ones returned and
/// never redrawn because the batch ended first - are corrected back out
/// of `{schema}.sequence` in one shot ([`Self::shrink_back`]), right
/// before `tx.commit()`. Because every draw is either confirmed or
/// returned before the next one starts (this pool is only ever driven by
/// `commit_command_batch`'s own strictly sequential loop, never
/// concurrently), the persisted `next_value` this leaves behind is always
/// identical to what calling `next_sequence_batch` once per command,
/// inside each one's own `SAVEPOINT`, would have left - only the number
/// of round trips to get there differs.
struct SequencePool {
    reserved: std::collections::VecDeque<i64>,
    last_draw: Vec<i64>,
}

impl SequencePool {
    fn new() -> Self {
        Self {
            reserved: std::collections::VecDeque::new(),
            last_draw: Vec::new(),
        }
    }

    /// Pops `count` sequence numbers, refilling from `tx` first if the
    /// pool doesn't already have enough. `refill_hint` (`commit_command_batch`
    /// passes "how many commands are still left in this batch, this one
    /// included") sizes that refill generously so a run of small,
    /// single-event commands shares one round trip instead of paying for
    /// one each; `refill_hint.max(count)` guarantees the refill is always
    /// big enough for the command that triggered it, regardless of how
    /// small a hint the caller passed. Remembers exactly what it handed
    /// out as `last_draw`, so the caller can later call exactly one of
    /// [`Self::confirm_last_draw`] or [`Self::return_last_draw`] once
    /// that command's own outcome is known - never both, never neither.
    async fn take(
        &mut self,
        tx: &mut Transaction<'_, Postgres>,
        bounded_context: &str,
        count: i64,
        refill_hint: i64,
    ) -> crate::error::Result<Vec<i64>> {
        if (self.reserved.len() as i64) < count {
            let refill =
                next_sequence_batch(&mut **tx, bounded_context, refill_hint.max(count)).await?;
            self.reserved.extend(refill);
        }
        let drawn: Vec<i64> = (0..count)
            .map(|_| {
                self.reserved
                    .pop_front()
                    .expect("just topped up the pool to at least `count`")
            })
            .collect();
        self.last_draw = drawn.clone();
        Ok(drawn)
    }

    /// The command that drew `last_draw` committed successfully - those
    /// numbers are truly spent, never returned to the pool.
    fn confirm_last_draw(&mut self) {
        self.last_draw.clear();
    }

    /// The command that drew `last_draw` failed - those numbers were
    /// never actually used by any inserted event, so they go back onto
    /// the *front* of the queue (preserving their original order) for
    /// whichever command draws next, instead of being permanently lost.
    fn return_last_draw(&mut self) {
        for value in self.last_draw.drain(..).rev() {
            self.reserved.push_front(value);
        }
    }

    /// Gives back whatever's left reserved-but-never-confirmed once the
    /// batch's own loop is done - see this struct's own doc comment for
    /// why this one corrective `UPDATE`, run once per batch, is all
    /// `SequenceIsGaplessPerBoundedContext` needs, regardless of how many
    /// refills happened or how many draws were returned and re-drawn
    /// along the way.
    async fn shrink_back(
        self,
        tx: &mut Transaction<'_, Postgres>,
        bounded_context: &str,
    ) -> crate::error::Result<()> {
        debug_assert!(
            self.last_draw.is_empty(),
            "every draw must be confirmed or returned before shrink_back runs"
        );
        let leftover = self.reserved.len() as i64;
        if leftover > 0 {
            let schema = schema_ident(bounded_context);
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "UPDATE {schema}.sequence SET next_value = next_value - $1"
            )))
            .bind(leftover)
            .execute(&mut **tx)
            .await?;
        }
        Ok(())
    }
}

/// The batched form of the "locked half" of `ProcessCommand` -
/// `submit_command`'s own doc comment describes the single-command
/// shape this generalises. Takes the already-locked transaction
/// [`begin_command_batch_leader_tx`] produced and runs every command in
/// `batch`, *in order*, each inside its own nested transaction
/// (`tx.begin()`, which sqlx backs with a real Postgres `SAVEPOINT` for a
/// `Transaction` that is itself already inside one) - so one command's
/// real failure (as opposed to an ordinary `Rejected` decision, which is
/// never an `Err` at all) rolls back only its own work, `ROLLBACK TO
/// SAVEPOINT`, not the whole batch's. Every command that succeeds is
/// `RELEASE SAVEPOINT`d immediately, keeping its writes visible to
/// whichever command in the batch runs next (see `extra_committed_events`
/// below) without making them durable yet - that's still `tx.commit()`,
/// called exactly once, after the whole batch has been processed.
///
/// This is what makes batching commands from *different*, concurrently-
/// submitting callers into one lock acquisition possible at all
/// (issue #32, round two - see `command_batcher`'s own module
/// doc comment for the throughput problem this exists to close): the
/// lock `leader_tx` already holds is held for the combined work of every
/// command in `batch`, not re-acquired per command, so N commands that
/// would previously have queued for N separate lock acquisitions instead
/// share one.
///
/// `extra_committed_events` threading: `submit_one_command_in_tx`'s own
/// DCB-conflict redispatch check needs to see events *this same batch*
/// already produced, not just ones committed before the lock. This loop
/// accumulates every accepted command's own `events` in memory as it
/// goes and hands the running total to each subsequent command, so the
/// check needs no query of its own for them.
///
/// Returns one [`BatchedCommandResult`] per input command, same order,
/// only once `tx.commit()` has actually succeeded - nothing here is
/// reported back to any caller as durable before it truly is. A failure
/// committing at the end is returned as the outer `Err` instead - at that
/// point no per-command outcome is trustworthy (a failed commit could
/// mean anything committed or nothing did), so the caller
/// (`command_batcher::CommandBatcher`) is expected to treat every command
/// in the batch as failed identically, not to guess from whatever this
/// function got partway through computing.
#[tracing::instrument(skip_all, fields(batch_size = batch.len()))]
pub async fn commit_command_batch(
    leader_tx: CommandBatchLeaderTx,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    key_service: Option<&KeyService>,
    batch: Vec<BatchedCommand>,
    slow: Option<&crate::slow_command::SlowCommandWarnings>,
) -> crate::error::Result<Vec<BatchedCommandResult>> {
    let CommandBatchLeaderTx {
        mut tx,
        bounded_context_name,
        locked_highest,
        sync_projections,
    } = leader_tx;

    COMMAND_BATCH_SIZE.record(
        batch.len() as u64,
        &[KeyValue::new(
            "bounded_context",
            bounded_context_name.clone(),
        )],
    );
    // A plain log line alongside the histogram above - purely so a load
    // test can grep achieved batch sizes straight out of server logs
    // without standing up an OTLP receiver, per
    // docs/load-test-report-2026-09-18*.md's own "skipped OTel/Grafana"
    // reasoning. The histogram is the lasting instrument; this is the
    // zero-infra way to read it for one investigation.
    tracing::debug!(
        bounded_context = %bounded_context_name,
        batch_size = batch.len(),
        "command batch committed"
    );

    let batch_len = batch.len();
    // docs/architecture.md §196: decided and written as a set first, in a
    // savepoint. Anything failing there - a statement, or a sync
    // projection refusing an event - rolls the savepoint back and the
    // batch is replayed one command at a time, each in its own savepoint,
    // which isolates the failure to its command as before.
    let mut savepoint = AsSetSavepoint::default();
    let as_set = match write_command_batch_as_set(
        &mut tx,
        &mut savepoint,
        dispatcher,
        projection_dispatcher,
        key_service,
        &batch,
        locked_highest,
        &sync_projections,
        slow,
    )
    .await
    {
        Ok(written) => Some(written),
        Err(e) => {
            tracing::debug!(
                bounded_context = %bounded_context_name,
                batch_size = batch_len,
                error = %e,
                "command batch not written as a set - replaying it one command at a time"
            );
            if savepoint.open {
                sqlx::query(sqlx::AssertSqlSafe(format!(
                    "ROLLBACK TO SAVEPOINT {AS_SET_SAVEPOINT}"
                )))
                .execute(&mut *tx)
                .await?;
            }
            None
        }
    };
    let (results, timing) = match as_set {
        Some(written) => written,
        None => {
            commit_command_batch_per_command(
                &mut tx,
                dispatcher,
                projection_dispatcher,
                key_service,
                &bounded_context_name,
                locked_highest,
                &sync_projections,
                batch,
                slow,
            )
            .await?
        }
    };

    let commit_started = std::time::Instant::now();
    tx.commit().await?;
    let commit_elapsed = commit_started.elapsed();

    tracing::debug!(
        bounded_context = %bounded_context_name,
        batch_size = batch_len,
        as_set = timing.as_set,
        decide_us = timing.decide.as_micros(),
        sequence_us = timing.sequence.as_micros(),
        persist_us = timing.persist.as_micros(),
        commit_us = commit_elapsed.as_micros(),
        "command batch phase timing"
    );

    Ok(results)
}

/// Where a batch's time under the lock went, for `commit_command_batch`'s
/// one timing line per batch (issue #32, round four).
#[derive(Default)]
struct BatchPhaseTiming {
    /// Whether the batch was written as a set (docs/architecture.md §196)
    /// rather than one command at a time.
    as_set: bool,
    decide: std::time::Duration,
    sequence: std::time::Duration,
    persist: std::time::Duration,
}

/// The savepoint the set path writes under, so a failed write rolls back
/// to before it and the batch is replayed one command at a time.
const AS_SET_SAVEPOINT: &str = "skilj_batch_as_set";

/// Whether the set path has opened [`AS_SET_SAVEPOINT`] yet. It is opened
/// with the first write, in the same round trip, and never released:
/// `COMMIT` keeps what was written under it, and a batch that writes
/// nothing - every command rejected or deduplicated - never opens it
/// (docs/architecture.md §196).
#[derive(Default)]
struct AsSetSavepoint {
    open: bool,
}

impl AsSetSavepoint {
    /// `statement` - a plain statement with no parameters, or none - run in
    /// the same round trip as opening the savepoint, if it isn't open yet.
    async fn write(
        &mut self,
        tx: &mut Transaction<'_, Postgres>,
        statement: Option<String>,
    ) -> crate::error::Result<()> {
        let sql = match (self.open, statement) {
            (true, None) => return Ok(()),
            (true, Some(statement)) => statement,
            (false, None) => format!("SAVEPOINT {AS_SET_SAVEPOINT}"),
            (false, Some(statement)) => format!("SAVEPOINT {AS_SET_SAVEPOINT}; {statement}"),
        };
        sqlx::raw_sql(sqlx::AssertSqlSafe(sql))
            .execute(&mut **tx)
            .await?;
        self.open = true;
        Ok(())
    }
}

/// One accepted command of a batch written as a set, built in memory
/// before anything is written (docs/architecture.md §196).
struct PlannedCommand {
    /// Its position in the batch, where its result goes.
    index: usize,
    command: Command,
    events: Vec<Event>,
    command_key_ids: Vec<i64>,
    event_key_ids: Vec<Vec<i64>>,
    idempotency_key: Option<String>,
    now: DateTime<Utc>,
}

/// `commit_command_batch`'s set path (docs/architecture.md §196): decides
/// every command in `batch` first, in order, without writing anything
/// but the encryption keys a redispatch newly needs, then writes every
/// accepted command with a handful of multi-row statements instead of
/// several statements per command.
///
/// Deciding first needs nothing written: a later command sees an earlier
/// one's events through `extra_committed_events`, as in the per-command
/// path, and its idempotency key through `claimed` instead of the table.
/// The events get their sequence numbers in memory, from right after
/// `locked_highest` - the lock is held, so nothing else takes one - and
/// `{schema}.sequence` moves once by however many were used. A command
/// whose decision or construction fails takes none, so the sequence stays
/// gapless with no [`SequencePool`] to recycle draws.
///
/// `Err` means the batch couldn't be written this way; the caller rolls
/// back the savepoint `tx` is and replays the batch one command at a time.
/// A command's own failure to decide is not that: it is that command's
/// result, as it would be in the per-command path.
#[allow(clippy::too_many_arguments)]
async fn write_command_batch_as_set(
    tx: &mut Transaction<'_, Postgres>,
    savepoint: &mut AsSetSavepoint,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    key_service: Option<&KeyService>,
    batch: &[BatchedCommand],
    locked_highest: i64,
    sync_projections: &[String],
    slow: Option<&crate::slow_command::SlowCommandWarnings>,
) -> crate::error::Result<(Vec<BatchedCommandResult>, BatchPhaseTiming)> {
    let mut timing = BatchPhaseTiming {
        as_set: true,
        ..BatchPhaseTiming::default()
    };
    let mut results: Vec<Option<BatchedCommandResult>> = Vec::with_capacity(batch.len());
    let mut planned: Vec<PlannedCommand> = Vec::new();
    let mut extra_committed_events: Vec<Event> = Vec::new();
    let mut claimed: BatchIdempotencyKeys = std::collections::HashMap::new();
    let mut highest_assigned = locked_highest;

    let decide_started = std::time::Instant::now();
    let batch_delta = batch_recheck_delta(tx, dispatcher, batch, locked_highest).await?;
    for (index, item) in batch.iter().enumerate() {
        let context = crate::plugin::DecisionContext::at(item.now);
        let decided = decide_command_in_tx(
            tx,
            dispatcher,
            &item.command_type,
            &item.payload,
            &item.client_id,
            &item.bounded_context_events,
            &item.consistency_tags,
            &item.matching_events,
            item.initial_decision.clone(),
            item.snapshot.as_ref().map(|s| SnapshotContext {
                state_json: &s.state_json,
                as_of_sequence: s.as_of_sequence,
            }),
            &item.snapshot_states,
            item.idempotency_key.as_deref(),
            locked_highest,
            &extra_committed_events,
            item.event_types_by_name.clone(),
            item.covered_through,
            Some(&claimed),
            Some(batch_delta.as_deref().unwrap_or(&[])),
            slow,
            &context,
        )
        .await;
        let AcceptedDecision {
            event_specs,
            consistency_boundary,
            consistency_query,
            event_types_by_name,
            blind,
        } = match decided {
            Ok(DecideOutcome::Terminal(outcome)) => {
                results.push(Some(Ok(outcome)));
                continue;
            }
            Ok(DecideOutcome::Accepted(decided)) => decided,
            Err(e) => {
                results.push(Some(Err(e)));
                continue;
            }
        };

        let mut resolved = item.resolved.clone();
        let needed_subjects = missing_encryption_subjects(
            &item.command_type,
            &item.payload,
            &event_specs,
            &event_types_by_name,
            &resolved,
        );
        if !needed_subjects.is_empty() {
            savepoint.write(tx, None).await?;
            provision_encryption_subjects(
                tx,
                &item.command_type,
                needed_subjects,
                &mut resolved,
                key_service,
            )
            .await?;
        }

        let mut assigned = highest_assigned;
        let processed = crate::event_store::process_command_at_boundary(
            crate::shared::generate_token_id(),
            &item.command_type,
            &item.payload,
            &item.client_id,
            item.correlation_id.as_deref(),
            item.causation_id.as_deref(),
            consistency_query,
            consistency_boundary,
            crate::shared::CommandDecision::Accepted {
                events: event_specs,
            },
            |name| event_types_by_name.get(name).cloned(),
            || {
                assigned += 1;
                assigned
            },
            item.now,
            |subject_key, subject_value| {
                let (key, _, data_key) = resolved
                    .get(&(subject_key.to_string(), subject_value.to_string()))
                    .expect(
                        "provision_missing_encryption_keys resolved every subject \
                         sensitive_field_subjects named",
                    );
                (key.clone(), data_key.clone())
            },
            &blind,
        );
        let result = match processed {
            Ok(result) => result,
            Err(e) => {
                results.push(Some(Err(e)));
                continue;
            }
        };
        highest_assigned = assigned;

        if let Some(key) = &item.idempotency_key {
            claimed.insert(
                (
                    item.command_type.name.clone(),
                    item.client_id.clone(),
                    key.clone(),
                ),
                result.events.iter().map(|e| e.sequence).collect(),
            );
        }
        extra_committed_events.extend(result.events.iter().cloned());
        results.push(None);
        planned.push(PlannedCommand {
            index,
            command_key_ids: encryption_key_ids(&result.command.encryption_keys, &resolved),
            event_key_ids: result
                .events
                .iter()
                .map(|event| encryption_key_ids(&event.encryption_keys, &resolved))
                .collect(),
            command: result.command,
            events: result.events,
            idempotency_key: item.idempotency_key.clone(),
            now: item.now,
        });
    }
    timing.decide = decide_started.elapsed();

    let persist_started = std::time::Instant::now();
    if let Some(first) = batch.first() {
        write_planned_commands(
            tx,
            savepoint,
            &first.command_type.bounded_context.name,
            &planned,
            highest_assigned - locked_highest,
            projection_dispatcher,
            sync_projections,
        )
        .await?;
    }
    timing.persist = persist_started.elapsed();

    for planned in planned {
        COMMANDS_PROCESSED.add(
            1,
            &[
                KeyValue::new(
                    "bounded_context",
                    planned.command.bounded_context.name.clone(),
                ),
                KeyValue::new("command_type", planned.command.command_type.name.clone()),
                KeyValue::new("outcome", "accepted"),
            ],
        );
        results[planned.index] = Some(Ok(SubmitCommandOutcome::Accepted {
            command: Box::new(planned.command),
            events: planned.events,
        }));
    }
    Ok((
        results
            .into_iter()
            .map(|result| result.expect("every accepted command was written above"))
            .collect(),
        timing,
    ))
}

/// Writes every command `write_command_batch_as_set` planned: the
/// sequence, then one multi-row `INSERT` each for the commands, their
/// events, both encryption-key link tables and the idempotency keys,
/// then the sync projections, event by event in sequence order. A few
/// round trips per batch, where the per-command path makes several per
/// command (docs/architecture.md §196).
async fn write_planned_commands(
    tx: &mut Transaction<'_, Postgres>,
    savepoint: &mut AsSetSavepoint,
    bounded_context: &str,
    planned: &[PlannedCommand],
    sequences_used: i64,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    sync_projections: &[String],
) -> crate::error::Result<()> {
    if planned.is_empty() {
        return Ok(());
    }
    let schema = schema_ident(bounded_context);
    // The savepoint opens in the same round trip as the first write. A
    // plain statement for that, so `sequences_used` - a count this
    // function computed, never caller input - is inlined.
    savepoint
        .write(
            tx,
            (sequences_used > 0).then(|| {
                format!("UPDATE {schema}.sequence SET next_value = next_value + {sequences_used}")
            }),
        )
        .await?;

    let commands: Vec<&Command> = planned.iter().map(|p| &p.command).collect();
    let rows: Vec<(i64, String)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.commands ({COMMAND_COLUMNS}) \
         SELECT external_id, command_type_name, payload, metadata_type, metadata_version, \
                client_id, created_at, correlation_id, causation_id, consistency_tags::jsonb, \
                consistency_boundary, consistency_query::jsonb \
         FROM unnest($1::text[], $2::text[], $3::text[], $4::text[], $5::bigint[], $6::text[], \
                     $7::timestamptz[], $8::text[], $9::text[], $10::text[], $11::bigint[], \
                     $12::text[]) \
              AS u(external_id, command_type_name, payload, metadata_type, metadata_version, \
                   client_id, created_at, correlation_id, causation_id, consistency_tags, \
                   consistency_boundary, consistency_query) \
         RETURNING id, external_id"
    )))
    .bind(commands.iter().map(|c| c.id.as_str()).collect::<Vec<_>>())
    .bind(
        commands
            .iter()
            .map(|c| c.command_type.name.as_str())
            .collect::<Vec<_>>(),
    )
    .bind(
        commands
            .iter()
            .map(|c| c.payload.as_str())
            .collect::<Vec<_>>(),
    )
    .bind(
        commands
            .iter()
            .map(|c| c.metadata.r#type.as_str())
            .collect::<Vec<_>>(),
    )
    .bind(
        commands
            .iter()
            .map(|c| c.metadata.version)
            .collect::<Vec<_>>(),
    )
    .bind(
        commands
            .iter()
            .map(|c| c.metadata.client_id.as_str())
            .collect::<Vec<_>>(),
    )
    .bind(
        commands
            .iter()
            .map(|c| c.metadata.created_at)
            .collect::<Vec<_>>(),
    )
    .bind(
        commands
            .iter()
            .map(|c| c.metadata.correlation_id.as_deref())
            .collect::<Vec<_>>(),
    )
    .bind(
        commands
            .iter()
            .map(|c| c.metadata.causation_id.as_deref())
            .collect::<Vec<_>>(),
    )
    .bind(
        commands
            .iter()
            .map(|c| {
                serde_json::to_string(&c.consistency_tags).expect("Tag serialisation is infallible")
            })
            .collect::<Vec<_>>(),
    )
    .bind(
        commands
            .iter()
            .map(|c| c.consistency_boundary)
            .collect::<Vec<_>>(),
    )
    .bind(
        commands
            .iter()
            .map(|c| {
                serde_json::to_string(&c.consistency_query)
                    .expect("QueryItem serialisation is infallible")
            })
            .collect::<Vec<_>>(),
    )
    .fetch_all(&mut **tx)
    .await?;
    let ids: std::collections::HashMap<String, i64> = rows
        .into_iter()
        .map(|(id, external_id)| (external_id, id))
        .collect();
    let command_id = |command: &Command| {
        *ids.get(&command.id)
            .expect("every inserted command came back from RETURNING")
    };

    let events: Vec<(&Event, i64)> = planned
        .iter()
        .flat_map(|p| {
            let id = command_id(&p.command);
            p.events.iter().map(move |event| (event, id))
        })
        .collect();
    if !events.is_empty() {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.events (sequence, event_type_name, payload, metadata_type, \
             metadata_version, metadata_client_id, metadata_created_at, metadata_correlation_id, \
             metadata_causation_id, tags, origin_kind, origin_source_content, \
             origin_source_context, origin_command_id) \
             SELECT sequence, event_type_name, payload, metadata_type, metadata_version, \
                    client_id, created_at, correlation_id, causation_id, tags::jsonb, \
                    'command_triggered', NULL, NULL, command_id \
             FROM unnest($1::bigint[], $2::text[], $3::text[], $4::text[], $5::bigint[], \
                         $6::text[], $7::timestamptz[], $8::text[], $9::text[], $10::text[], \
                         $11::bigint[]) \
                  AS u(sequence, event_type_name, payload, metadata_type, metadata_version, \
                       client_id, created_at, correlation_id, causation_id, tags, command_id)"
        )))
        .bind(events.iter().map(|(e, _)| e.sequence).collect::<Vec<_>>())
        .bind(
            events
                .iter()
                .map(|(e, _)| e.event_type.name.as_str())
                .collect::<Vec<_>>(),
        )
        .bind(
            events
                .iter()
                .map(|(e, _)| e.payload.as_str())
                .collect::<Vec<_>>(),
        )
        .bind(
            events
                .iter()
                .map(|(e, _)| e.metadata.r#type.as_str())
                .collect::<Vec<_>>(),
        )
        .bind(
            events
                .iter()
                .map(|(e, _)| e.metadata.version)
                .collect::<Vec<_>>(),
        )
        .bind(
            events
                .iter()
                .map(|(e, _)| e.metadata.client_id.as_str())
                .collect::<Vec<_>>(),
        )
        .bind(
            events
                .iter()
                .map(|(e, _)| e.metadata.created_at)
                .collect::<Vec<_>>(),
        )
        .bind(
            events
                .iter()
                .map(|(e, _)| e.metadata.correlation_id.as_deref())
                .collect::<Vec<_>>(),
        )
        .bind(
            events
                .iter()
                .map(|(e, _)| e.metadata.causation_id.as_deref())
                .collect::<Vec<_>>(),
        )
        .bind(
            events
                .iter()
                .map(|(e, _)| {
                    serde_json::to_string(&e.tags).expect("Tag serialisation is infallible")
                })
                .collect::<Vec<_>>(),
        )
        .bind(events.iter().map(|(_, id)| *id).collect::<Vec<_>>())
        .execute(&mut **tx)
        .await?;
    }

    let (key_commands, command_keys): (Vec<i64>, Vec<i64>) = planned
        .iter()
        .flat_map(|p| {
            let id = command_id(&p.command);
            p.command_key_ids.iter().map(move |key| (id, *key))
        })
        .unzip();
    if !key_commands.is_empty() {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.command_encryption_keys (command_id, encryption_key_id) \
             SELECT * FROM unnest($1::bigint[], $2::bigint[])"
        )))
        .bind(&key_commands)
        .bind(&command_keys)
        .execute(&mut **tx)
        .await?;
    }
    let (key_events, event_keys): (Vec<i64>, Vec<i64>) = planned
        .iter()
        .flat_map(|p| {
            p.events
                .iter()
                .zip(&p.event_key_ids)
                .flat_map(|(event, keys)| keys.iter().map(move |key| (event.sequence, *key)))
        })
        .unzip();
    if !key_events.is_empty() {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.event_encryption_keys (event_sequence, encryption_key_id) \
             SELECT * FROM unnest($1::bigint[], $2::bigint[])"
        )))
        .bind(&key_events)
        .bind(&event_keys)
        .execute(&mut **tx)
        .await?;
    }

    let keyed: Vec<(&PlannedCommand, &str)> = planned
        .iter()
        .filter_map(|p| p.idempotency_key.as_deref().map(|key| (p, key)))
        .collect();
    if !keyed.is_empty() {
        // `triggered_event_sequences` is an array per row, which `unnest`
        // can't take as an array of arrays of different lengths - so each
        // row's goes as a JSON array.
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.idempotency_keys \
             (command_type_name, client_id, idempotency_key, triggered_event_sequences, created_at) \
             SELECT command_type_name, client_id, idempotency_key, \
                    ARRAY(SELECT jsonb_array_elements_text(sequences::jsonb)::bigint), created_at \
             FROM unnest($1::text[], $2::text[], $3::text[], $4::text[], $5::timestamptz[]) \
                  AS u(command_type_name, client_id, idempotency_key, sequences, created_at)"
        )))
        .bind(
            keyed
                .iter()
                .map(|(p, _)| p.command.command_type.name.as_str())
                .collect::<Vec<_>>(),
        )
        .bind(
            keyed
                .iter()
                .map(|(p, _)| p.command.metadata.client_id.as_str())
                .collect::<Vec<_>>(),
        )
        .bind(keyed.iter().map(|(_, key)| *key).collect::<Vec<_>>())
        .bind(
            keyed
                .iter()
                .map(|(p, _)| {
                    serde_json::to_string(
                        &p.events.iter().map(|e| e.sequence).collect::<Vec<_>>(),
                    )
                    .expect("a list of numbers serialises")
                })
                .collect::<Vec<_>>(),
        )
        .bind(keyed.iter().map(|(p, _)| p.now).collect::<Vec<_>>())
        .execute(&mut **tx)
        .await?;
    }

    if !sync_projections.is_empty() {
        let events: Vec<&Event> = events.iter().map(|(event, _)| *event).collect();
        fold_events_into_sync_projections_in_tx(
            tx,
            bounded_context,
            &events,
            projection_dispatcher,
            sync_projections,
        )
        .await?;
    }
    Ok(())
}

/// Folds a batch's `events`, already inserted on `tx` and in sequence
/// order, into every one of `sync_projections` at once - what folding
/// them one by one with [`fold_event_into_sync_projections_in_tx`] does,
/// with a few statements per projection instead of two per key per event
/// (docs/architecture.md §196), the way the async catch-up folds a chunk
/// (§182): every row the events touch is read and locked in one
/// statement, the events are folded into them in memory, in order, each
/// row is written back in one statement, and `caught_up_to` moves once.
async fn fold_events_into_sync_projections_in_tx(
    tx: &mut Transaction<'_, Postgres>,
    bounded_context: &str,
    events: &[&Event],
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    sync_projections: &[String],
) -> crate::error::Result<()> {
    let Some(last) = events.last() else {
        return Ok(());
    };
    let schema = schema_ident(bounded_context);
    for projection_name in sync_projections {
        // As in `fold_event_into_sync_projections_in_tx`: a projection
        // this instance doesn't declare can't be folded here, and a write
        // that it consumes is refused (docs/architecture.md §160).
        let Some(default_state_json) = dispatcher.default_state(bounded_context, projection_name)
        else {
            let mut types: Vec<&str> = events.iter().map(|e| e.event_type.name.as_str()).collect();
            types.sort_unstable();
            types.dedup();
            let consumes: bool = sqlx::query_scalar(sqlx::AssertSqlSafe(format!(
                "SELECT EXISTS (SELECT 1 FROM {schema}.projection_consumed_event_types \
                 WHERE projection_name = $1 AND event_type_name = ANY($2))"
            )))
            .bind(projection_name)
            .bind(&types)
            .fetch_one(&mut **tx)
            .await?;
            if consumes {
                return Err(crate::event_store::Error::SyncProjectionNotDeclared(
                    projection_name.clone(),
                )
                .into());
            }
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "UPDATE {schema}.projections SET caught_up_to = $1 WHERE name = $2"
            )))
            .bind(last.sequence)
            .bind(projection_name)
            .execute(&mut **tx)
            .await?;
            continue;
        };
        let owner_tag_key = dispatcher
            .owner_tag_key(bounded_context, projection_name)
            .flatten();

        let mut touched: Vec<(&Event, Vec<String>)> = Vec::new();
        let mut keys: Vec<String> = Vec::new();
        let mut seen = std::collections::HashSet::new();
        for event in events {
            let event_keys = dispatcher
                .keys(bounded_context, projection_name, event)
                .unwrap_or_default();
            for key in &event_keys {
                if seen.insert(key.clone()) {
                    keys.push(key.clone());
                }
            }
            if !event_keys.is_empty() {
                touched.push((event, event_keys));
            }
        }

        if !keys.is_empty() {
            // Get-or-create-with-lock, every key at once - see
            // `get_or_create_projection_state_for_update`.
            let rows: Vec<(String, i64, String)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
                "INSERT INTO {schema}.projection_state (projection_name, key, state, updated_at) \
                 SELECT $1, key, $3, now() FROM unnest($2::text[]) AS key \
                 ON CONFLICT (projection_name, key) DO UPDATE SET \
                 state = {schema}.projection_state.state \
                 RETURNING key, as_of_sequence, state"
            )))
            .bind(projection_name)
            .bind(&keys)
            .bind(&default_state_json)
            .fetch_all(&mut **tx)
            .await?;
            let mut states: std::collections::HashMap<String, CatchUpChunkState> = rows
                .into_iter()
                .map(|(key, as_of_sequence, state)| {
                    (
                        key,
                        CatchUpChunkState {
                            as_of_sequence,
                            state,
                            owner: None,
                            folded: false,
                        },
                    )
                })
                .collect();

            for (event, event_keys) in &touched {
                let owner = event_owner(owner_tag_key, event);
                for key in event_keys {
                    let entry = states
                        .get_mut(key)
                        .expect("every touched key's row was just read");
                    if entry.as_of_sequence >= event.sequence {
                        continue;
                    }
                    if let Some(result) = dispatcher.project(
                        bounded_context,
                        projection_name,
                        &entry.state,
                        event,
                        key,
                    ) {
                        entry.state = result?;
                    }
                    entry.as_of_sequence = event.sequence;
                    if owner.is_some() {
                        entry.owner.clone_from(&owner);
                    }
                    entry.folded = true;
                }
            }

            let mut folded_keys = Vec::new();
            let mut folded_states = Vec::new();
            let mut owners = Vec::new();
            let mut as_of_sequences = Vec::new();
            for (key, folded) in states.iter().filter(|(_, s)| s.folded) {
                folded_keys.push(key.as_str());
                folded_states.push(folded.state.as_str());
                owners.push(folded.owner.as_deref());
                as_of_sequences.push(folded.as_of_sequence);
            }
            if !folded_keys.is_empty() {
                // A `NULL` owner leaves the stored one as it is - see
                // `apply_projection_fold_update`.
                sqlx::query(sqlx::AssertSqlSafe(format!(
                    "UPDATE {schema}.projection_state AS s SET state = u.state, \
                     owner = COALESCE(u.owner, s.owner), as_of_sequence = u.as_of_sequence, \
                     updated_at = now() \
                     FROM unnest($2::text[], $3::text[], $4::text[], $5::bigint[]) \
                     AS u(key, state, owner, as_of_sequence) \
                     WHERE s.projection_name = $1 AND s.key = u.key"
                )))
                .bind(projection_name)
                .bind(&folded_keys)
                .bind(&folded_states)
                .bind(&owners)
                .bind(&as_of_sequences)
                .execute(&mut **tx)
                .await?;
            }
        }

        sqlx::query(sqlx::AssertSqlSafe(format!(
            "UPDATE {schema}.projections SET caught_up_to = $1 WHERE name = $2"
        )))
        .bind(last.sequence)
        .bind(projection_name)
        .execute(&mut **tx)
        .await?;
    }
    Ok(())
}

/// `commit_command_batch`'s per-command path: every command in `batch`, in
/// order, decided and written in its own savepoint, so a command that
/// fails rolls back alone. Since docs/architecture.md §196 it is the
/// fallback for a batch that couldn't be written as a set.
#[allow(clippy::too_many_arguments)]
async fn commit_command_batch_per_command(
    tx: &mut Transaction<'static, Postgres>,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    key_service: Option<&KeyService>,
    bounded_context_name: &str,
    locked_highest: i64,
    sync_projections: &[String],
    batch: Vec<BatchedCommand>,
    slow: Option<&crate::slow_command::SlowCommandWarnings>,
) -> crate::error::Result<(Vec<BatchedCommandResult>, BatchPhaseTiming)> {
    // Per-phase wall-clock accumulators (issue #32,
    // round four investigation) - the batch-size histogram above already
    // ruled out "batches aren't forming large enough to amortise" as the
    // explanation for the flat ~27/s ceiling; this is the next
    // measurement, not more reasoning from round-trip counting alone:
    // which of decide/sequence-draw/persist actually eats the wall-clock
    // time inside the held lock. One log line per batch, greppable, same
    // zero-infra reasoning as the batch-size line above.
    let mut decide_total = std::time::Duration::ZERO;
    let mut sequence_total = std::time::Duration::ZERO;
    let mut persist_total = std::time::Duration::ZERO;

    let mut results = Vec::with_capacity(batch.len());
    let mut extra_committed_events: Vec<Event> = Vec::new();
    let mut sequence_pool = SequencePool::new();
    let batch_len = batch.len();

    for (idx, item) in batch.into_iter().enumerate() {
        // Not inside a `SAVEPOINT`: `decide_command_in_tx` only reads (on
        // `tx`, since it runs under the batch's lock - docs/architecture.md
        // §117), and a failing read means the connection itself is in
        // trouble, which no savepoint would contain. A decider's own
        // error is a Rust `Err`, not a statement, and stays per-command.
        let decide_started = std::time::Instant::now();
        let context = crate::plugin::DecisionContext::at(item.now);
        let decide_result = decide_command_in_tx(
            tx,
            dispatcher,
            &item.command_type,
            &item.payload,
            &item.client_id,
            &item.bounded_context_events,
            &item.consistency_tags,
            &item.matching_events,
            item.initial_decision,
            item.snapshot.as_ref().map(|s| SnapshotContext {
                state_json: &s.state_json,
                as_of_sequence: s.as_of_sequence,
            }),
            &item.snapshot_states,
            item.idempotency_key.as_deref(),
            locked_highest,
            &extra_committed_events,
            item.event_types_by_name,
            item.covered_through,
            None,
            None,
            slow,
            &context,
        )
        .await;
        decide_total += decide_started.elapsed();

        let decided = match decide_result {
            Ok(DecideOutcome::Terminal(outcome)) => {
                results.push(Ok(outcome));
                continue;
            }
            Ok(DecideOutcome::Accepted(decided)) => decided,
            Err(e) => {
                results.push(Err(e));
                continue;
            }
        };

        // Reserved against `tx` itself, not the `nested` `SAVEPOINT`
        // opened below - see `SequencePool`'s own doc comment for why
        // that's what lets a later command's failure recycle these
        // instead of burning a permanent gap. `refill_hint` is "how many
        // commands (including this one) are still left to process" - an
        // upper bound on how many single-event commands could still
        // share whatever this refill provisions.
        let refill_hint = (batch_len - idx) as i64;
        let sequence_started = std::time::Instant::now();
        let sequence_result = sequence_pool
            .take(
                tx,
                bounded_context_name,
                decided.event_specs.len() as i64,
                refill_hint,
            )
            .await;
        sequence_total += sequence_started.elapsed();
        let sequences = match sequence_result {
            Ok(sequences) => sequences,
            Err(e) => {
                // A failure bumping `{schema}.sequence` on `tx` itself -
                // not a per-command problem any `SAVEPOINT` isolates,
                // since this call deliberately runs outside one. Same
                // treatment as a final `tx.commit()` failure below:
                // nothing in this batch is trustworthy from here, so
                // every command - this one and everything still
                // queued - gets the caller's own uniform `BatchFailed`
                // treatment instead of a partial `results`.
                return Err(e);
            }
        };

        let persist_started = std::time::Instant::now();
        let mut nested = tx.begin().await?;
        let outcome = finish_accepted_command_in_tx(
            &mut nested,
            projection_dispatcher,
            &item.command_type,
            &item.payload,
            &item.client_id,
            item.correlation_id.as_deref(),
            item.causation_id.as_deref(),
            key_service,
            item.now,
            item.idempotency_key.as_deref(),
            sync_projections,
            sequences,
            decided,
            item.resolved,
        )
        .await;

        match outcome {
            Ok(outcome) => {
                // A failure of this savepoint statement itself (as with
                // `tx.begin()`/`nested.rollback()` below) means the shared
                // connection is unusable, not that this one command is bad,
                // so it deliberately aborts the whole batch: the
                // transaction can no longer be committed, and the earlier
                // commands' writes live only in it. Per-command failures
                // (`finish_accepted_command_in_tx` returning `Err`) are
                // the ones isolated by the savepoint - see the `Err` arm.
                //
                // Releases this command's own savepoint - its writes stay
                // in `tx`, visible to every subsequent command in this
                // same batch, but still no more durable than the rest of
                // `tx` until the one `tx.commit()` below succeeds.
                nested.commit().await?;
                persist_total += persist_started.elapsed();
                sequence_pool.confirm_last_draw();
                if let SubmitCommandOutcome::Accepted { ref events, .. } = outcome {
                    extra_committed_events.extend(events.iter().cloned());
                }
                results.push(Ok(outcome));
            }
            Err(e) => {
                // `ROLLBACK TO SAVEPOINT`, awaited explicitly rather than
                // left to `nested`'s own `Drop` - both end up issuing the
                // same statement, but every subsequent command in this
                // loop shares `tx`'s one underlying connection, so the
                // rollback must be known-complete before the next
                // `tx.begin()` reuses it, not merely queued by a
                // fire-and-forget `Drop`.
                nested.rollback().await?;
                persist_total += persist_started.elapsed();
                sequence_pool.return_last_draw();
                results.push(Err(e));
            }
        }
    }

    sequence_pool.shrink_back(tx, bounded_context_name).await?;

    Ok((
        results,
        BatchPhaseTiming {
            as_set: false,
            decide: decide_total,
            sequence: sequence_total,
            persist: persist_total,
        },
    ))
}

/// [`begin_command_batch_leader_tx`] immediately followed by
/// [`commit_command_batch`], with no `idle_in_transaction_session_timeout`
/// and nothing drained from a shared queue in between - the whole-batch-
/// in-one-call shape every direct caller (this crate's own
/// `submit_command.rs` tests, which hand-build a batch up front) wants.
/// `command_batcher::CommandBatcher::run_as_leader` calls the two halves
/// separately instead, draining its own queue in the gap between them -
/// see that function's own doc comment for why.
pub async fn submit_command_batch(
    pool: &Pool,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    key_service: Option<&KeyService>,
    bounded_context_name: &str,
    batch: Vec<BatchedCommand>,
) -> crate::error::Result<Vec<BatchedCommandResult>> {
    let leader_tx = begin_command_batch_leader_tx(pool, bounded_context_name, None).await?;
    commit_command_batch(
        leader_tx,
        dispatcher,
        projection_dispatcher,
        key_service,
        batch,
        None,
    )
    .await
}

/// What [`resolve_command_submission`] settles on - everything both
/// [`decide_and_submit_command`] and `command_batcher::CommandBatcher::decide_and_submit`
/// need to hand off to their own "locked half" ([`submit_command`] or
/// [`CommandBatcher::submit`](crate::command_batcher::CommandBatcher::submit)
/// respectively), computed identically by both.
pub struct ResolvedCommandSubmission {
    pub bounded_context_events: Vec<Event>,
    /// The position `bounded_context_events` is complete through - see
    /// `list_events_for_bounded_context_matching_tags_cached`.
    pub covered_through: i64,
    pub consistency_tags: Vec<Tag>,
    /// The command type's own consistency query, derived from the payload
    /// - empty for one that declares none (docs/architecture.md §198).
    pub consistency_query: Vec<QueryItem>,
    pub matching_events: Vec<Event>,
    pub decision: crate::shared::CommandDecision,
    pub snapshot_context: Option<ResolvedSnapshot>,
    /// The states of the query's snapshot items, as of the read
    /// (docs/architecture.md §202) - empty for a query without any.
    pub snapshot_states: Vec<crate::plugin::SnapshotState>,
    /// How long reading the history took, snapshot rows included
    /// (docs/architecture.md §203).
    pub read_time: std::time::Duration,
    /// How long `decide()` took on what was read.
    pub decide_time: std::time::Duration,
}

/// `CommandType::consistency_query`, as `dispatcher` holds it for
/// `command_type`, derived from `payload` - empty for a command type that
/// declares none (docs/architecture.md §198). Derived wherever it's
/// needed rather than carried: it's a pure function of the two, and the
/// compiled query is what the compiled `decide()` was written against.
fn command_consistency_query(
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    command_type: &CommandType,
    payload: &str,
) -> crate::error::Result<Vec<QueryItem>> {
    let bounded_context = &command_type.bounded_context.name;
    match dispatcher.consistency_query(bounded_context, &command_type.name) {
        Some(mappings) => crate::event_store::derive_query(
            &mappings,
            payload,
            &dispatcher.blind_index(),
            bounded_context,
        ),
        None => Ok(Vec::new()),
    }
}

/// The optimistic, unlocked half of `ProcessCommand`'s own "optimistic
/// decide, then locked submit" sequence - derive consistency tags,
/// resolve a snapshot context if one applies (`resolve_snapshot_context`),
/// fetch matching events (tag-indexed - [docs/architecture.md §19](../../../docs/architecture.md#optional-snapshotting-matching-events)'s
/// own "Problem 1" fix), `dispatch()` once optimistically. Shared by
/// [`decide_and_submit_command`] (hands the result to [`submit_command`])
/// and `command_batcher::CommandBatcher::decide_and_submit` (hands it to
/// [`CommandBatcher::submit`](crate::command_batcher::CommandBatcher::submit)
/// instead) - both need the identical resolution, only what happens with
/// it afterward differs.
pub async fn resolve_command_submission(
    pool: &Pool,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    snapshot_dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    event_cache: &crate::event_cache::EventCache,
    command_type: &CommandType,
    payload: &str,
    context: &crate::plugin::DecisionContext,
) -> crate::error::Result<ResolvedCommandSubmission> {
    // docs/architecture.md §200: a bounded context an older instance added
    // during a rolling deploy has no `consistency_query` column for the
    // command to be written with. Once per process per bounded context.
    ensure_bounded_context_current(pool, &command_type.bounded_context).await?;
    let bounded_context_name = command_type.bounded_context.name.clone();
    let consistency_tags = crate::event_store::derive_tags(
        &command_type.tag_mappings,
        payload,
        &dispatcher.blind_index(),
        &bounded_context_name,
    )?;
    let consistency_query = command_consistency_query(dispatcher, command_type, payload)?;

    // `build()` refuses a snapshot together with a query; a dispatcher
    // built by hand that has both gets the query.
    let snapshot_context = match dispatcher.snapshot_name(&bounded_context_name, &command_type.name)
    {
        Some(Some(snapshot_name)) if consistency_query.is_empty() => {
            resolve_snapshot_context(
                pool,
                &bounded_context_name,
                snapshot_dispatcher,
                snapshot_name,
                &consistency_tags,
            )
            .await?
        }
        _ => None,
    };

    let read_started = std::time::Instant::now();
    let mut snapshot_states = Vec::new();
    let (bounded_context_events, covered_through) =
        if crate::event_store::query_reads_nothing(&consistency_query) {
            // docs/architecture.md §201: no history to read, and the re-check
            // under the lock skips it too, so the position it would start from
            // doesn't matter.
            (Vec::new(), -1)
        } else if crate::event_store::query_has_snapshots(&consistency_query) {
            let (events, covered_through, states) = read_query_with_snapshots(
                pool,
                event_cache,
                dispatcher,
                &bounded_context_name,
                &consistency_query,
            )
            .await?;
            snapshot_states = states;
            (events, covered_through)
        } else if consistency_query.is_empty() {
            list_events_for_bounded_context_matching_tags_cached(
                pool,
                event_cache,
                &bounded_context_name,
                &consistency_tags,
                snapshot_context.as_ref().map(|ctx| ctx.as_of_sequence),
            )
            .await?
        } else {
            list_events_matching_query_cached(
                pool,
                event_cache,
                &bounded_context_name,
                &consistency_query,
                None,
            )
            .await?
        };
    let matching_events = crate::event_store::select_matching_events(
        &decided_on(&consistency_query, &consistency_tags),
        &bounded_context_events,
    );
    let read_time = read_started.elapsed();

    let decide_started = std::time::Instant::now();
    let decision = match &snapshot_context {
        Some(ctx) => dispatcher
            .dispatch_from_snapshot(
                &bounded_context_name,
                &command_type.name,
                payload,
                &ctx.state_json,
                &matching_events,
                context,
            )
            .ok_or(crate::error::Error::NoDeciderRegistered)??,
        None => dispatcher
            .dispatch_with(
                &bounded_context_name,
                &command_type.name,
                payload,
                &matching_events,
                &snapshot_states,
                context,
            )
            .ok_or(crate::error::Error::NoDeciderRegistered)??,
    };
    let decide_time = decide_started.elapsed();
    tracing::debug!(
        bounded_context = %bounded_context_name,
        command_type = %command_type.name,
        events_read = bounded_context_events.len(),
        read_us = read_time.as_micros(),
        decide_us = decide_time.as_micros(),
        "command optimistic read"
    );

    Ok(ResolvedCommandSubmission {
        bounded_context_events,
        covered_through,
        consistency_tags,
        consistency_query,
        matching_events,
        decision,
        snapshot_context,
        snapshot_states,
        read_time,
        decide_time,
    })
}

/// The items whose events `decide()` is handed: the command's query
/// without its snapshot items, whose events are folded into their states
/// instead (docs/architecture.md §202), or the default, one item per
/// consistency tag, for a command type that declares no query.
fn decided_on(consistency_query: &[QueryItem], consistency_tags: &[Tag]) -> Vec<QueryItem> {
    if consistency_query.is_empty() {
        crate::event_store::effective_query(consistency_query, consistency_tags)
    } else {
        crate::event_store::event_items(consistency_query)
    }
}

/// What [`dry_run_command`] found: `decide()`'s answer, and the matching
/// events it decided from.
#[derive(Debug)]
pub struct CommandDryRun {
    pub decision: DryRunDecision,
    /// Unrendered and unscoped, every event `decide()` saw. A surface that
    /// shows them narrows and renders them first, as `submitCommand` does
    /// for a rejection's (`event_store::visible_matching_events`).
    pub matching_events: Vec<Event>,
}

#[derive(Debug)]
#[non_exhaustive]
pub enum DryRunDecision {
    /// Unrendered: plaintext, as `decide()` emitted them. See
    /// `event_store::render_would_be_event`.
    Accepted {
        events: Vec<WouldBeEvent>,
    },
    Rejected {
        reason: String,
        kind: String,
    },
}

/// `rule DryRunCommand`/`rule DryRunTriggerCommand` past authorisation
/// (issue #47): what a submission of `payload` would decide
/// right now. It is [`resolve_command_submission`] - the same snapshot
/// resolution, the same tag-indexed read, the same `decide()` - and
/// nothing after it. No lock is taken, nothing is written, no sequence
/// is used up, no encryption key is provisioned, and no idempotency key
/// is looked up or recorded. Nor does it re-check under a lock, so a
/// commit racing it can make the real submission decide differently.
///
/// An accepted decision fails where the real submission would before
/// writing: with `UnregisteredEventType` for an event type this bounded
/// context hasn't registered, and with `MasterKeyNotConfigured` when the
/// command or a would-be event has a sensitive field to encrypt and no
/// `key_service` is configured. The key itself is never
/// looked up or provisioned. `client_id` is stamped on each would-be
/// event, as
/// `process_command` stamps it: it is what an `Own` private field's
/// default reader is decided by.
#[allow(clippy::too_many_arguments)]
pub async fn dry_run_command(
    pool: &Pool,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    snapshot_dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    event_cache: &crate::event_cache::EventCache,
    command_type: &CommandType,
    payload: &str,
    client_id: &str,
    key_service: Option<&KeyService>,
    now: DateTime<Utc>,
) -> crate::error::Result<CommandDryRun> {
    let context = crate::plugin::DecisionContext::at(now);
    let resolved = resolve_command_submission(
        pool,
        dispatcher,
        snapshot_dispatcher,
        event_cache,
        command_type,
        payload,
        &context,
    )
    .await?;
    let decision = match resolved.decision {
        crate::shared::CommandDecision::Rejected { reason, kind } => {
            DryRunDecision::Rejected { reason, kind }
        }
        crate::shared::CommandDecision::Accepted { events: specs } => {
            let mut event_types: std::collections::HashMap<String, EventType> =
                std::collections::HashMap::new();
            let mut events = Vec::with_capacity(specs.len());
            for spec in specs {
                if !event_types.contains_key(&spec.event_type) {
                    let event_type =
                        get_event_type(pool, &command_type.bounded_context.name, &spec.event_type)
                            .await?
                            .ok_or_else(|| {
                                crate::event_store::Error::UnregisteredEventType(
                                    spec.event_type.clone(),
                                )
                            })?;
                    event_types.insert(spec.event_type.clone(), event_type);
                }
                let event_type = event_types[&spec.event_type].clone();
                let payload = spec.payload.to_string();
                events.push(WouldBeEvent {
                    tags: crate::event_store::derive_tags(
                        &event_type.tag_mappings,
                        &payload,
                        &dispatcher.blind_index(),
                        &command_type.bounded_context.name,
                    )?,
                    event_type,
                    payload,
                    client_id: client_id.to_string(),
                });
            }
            let needs_a_key = !crate::event_store::sensitive_field_subjects(
                &command_type.sensitive_fields,
                payload,
            )
            .is_empty()
                || events.iter().any(|e| {
                    !crate::event_store::sensitive_field_subjects(
                        &e.event_type.sensitive_fields,
                        &e.payload,
                    )
                    .is_empty()
                });
            if needs_a_key && key_service.is_none() {
                return Err(encryption::Error::MasterKeyNotConfigured.into());
            }
            DryRunDecision::Accepted { events }
        }
    };
    Ok(CommandDryRun {
        decision,
        matching_events: resolved.matching_events,
    })
}

/// The full "optimistic decide, then locked submit" sequence
/// `ProcessCommand` describes end to end, for a caller that already has
/// a resolved `CommandType` and a JSON payload in hand - see
/// [`resolve_command_submission`] for the optimistic half this hands off
/// to [`submit_command`] for the real, locked recheck-and-retry.
///
/// Previously this exact sequence was independently duplicated by
/// `skilj-rest`'s `post_commands_trigger` and `skilj-graphql`'s
/// `submitCommand` resolver (each one's own comments cross-referenced
/// the other as "the identical branch") - both now call through here
/// instead, and it is also what `SkiljBuilder`'s cross-context event
/// router (docs/architecture.md's own write-up of that pass) uses to
/// submit a routed command in-process, a third caller with no REST/
/// GraphQL wire concerns of its own to keep separate from this. `None`
/// from `dispatch`/`dispatch_from_snapshot` (no decider registered for
/// this `(bounded_context, command_type)` pair - `CommandDispatcher::
/// dispatch`'s own doc comment on why that's reachable in principle)
/// surfaces as `Error::NoDeciderRegistered`, the same variant every
/// caller already converts into its own wire error today.
///
/// **Not routed through `command_batcher::CommandBatcher`** - this stays
/// the direct, unbatched path, still exactly what it always was. High-
/// volume, externally-triggered submission (REST/GraphQL command
/// submission, parked-delivery redrive) uses `CommandBatcher::decide_and_submit`
/// instead (issue #32, round two); the lower-volume, periodic
/// internal ones (the cross-context event router's own tick,
/// `fire_due_deadlines`) still call through here, deliberately - batching
/// buys the least where a caller is already ticking on its own schedule
/// rather than arriving as a burst of concurrent external requests.
#[allow(clippy::too_many_arguments)]
pub async fn decide_and_submit_command(
    pool: &Pool,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    snapshot_dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    command_type: &CommandType,
    payload: &str,
    client_id: &str,
    correlation_id: Option<&str>,
    causation_id: Option<&str>,
    key_service: Option<&KeyService>,
    now: DateTime<Utc>,
    idempotency_key: Option<&str>,
    deadline: Option<crate::plugin::DeadlineContext>,
) -> crate::error::Result<SubmitCommandOutcome> {
    let mut rotated_once = false;
    loop {
        let outcome = decide_and_submit_command_once(
            pool,
            dispatcher,
            projection_dispatcher,
            snapshot_dispatcher,
            broadcaster,
            event_cache,
            command_type,
            payload,
            client_id,
            correlation_id,
            causation_id,
            key_service,
            now,
            idempotency_key,
            deadline,
        )
        .await;
        match outcome {
            Err(err) if blind_tags_rotated(&err) && !rotated_once => rotated_once = true,
            outcome => return outcome,
        }
    }
}

/// Whether `err` is a command sent round again because its blind tags were
/// derived before a key rotation (docs/architecture.md §209) - retried once
/// by the submission functions, rehashed.
pub fn blind_tags_rotated(err: &crate::error::Error) -> bool {
    matches!(
        err,
        crate::error::Error::Blind(crate::blind::Error::Rotated { .. })
    )
}

#[allow(clippy::too_many_arguments)]
async fn decide_and_submit_command_once(
    pool: &Pool,
    dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    snapshot_dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    command_type: &CommandType,
    payload: &str,
    client_id: &str,
    correlation_id: Option<&str>,
    causation_id: Option<&str>,
    key_service: Option<&KeyService>,
    now: DateTime<Utc>,
    idempotency_key: Option<&str>,
    deadline: Option<crate::plugin::DeadlineContext>,
) -> crate::error::Result<SubmitCommandOutcome> {
    let context = match deadline {
        Some(deadline) => crate::plugin::DecisionContext {
            now,
            deadline: Some(deadline),
        },
        None => crate::plugin::DecisionContext::at(now),
    };
    let resolved = resolve_command_submission(
        pool,
        dispatcher,
        snapshot_dispatcher,
        event_cache,
        command_type,
        payload,
        &context,
    )
    .await?;

    submit_command(
        pool,
        dispatcher,
        projection_dispatcher,
        broadcaster,
        event_cache,
        command_type,
        payload,
        client_id,
        correlation_id,
        causation_id,
        &resolved.bounded_context_events,
        &resolved.consistency_tags,
        &resolved.matching_events,
        resolved.decision,
        key_service,
        now,
        resolved
            .snapshot_context
            .as_ref()
            .map(|ctx| SnapshotContext {
                state_json: &ctx.state_json,
                as_of_sequence: ctx.as_of_sequence,
            }),
        &resolved.snapshot_states,
        idempotency_key,
        Some(resolved.covered_through),
        &context,
    )
    .await
}

/// `cross_context_route_cursors`'s own read - `None` when no row exists
/// at all, which means this route has never had a single catch-up tick
/// run for it since it was registered (a row, once written, is never
/// deleted - see `update_cross_context_route_cursor`). Distinct from a
/// row genuinely holding `-1` (a `CrossContextRouteStartFrom::Latest`
/// route whose very first tick found no `Source` occurrences at all yet
/// to seed past - see `catch_up_cross_context_route`'s own doc comment):
/// that case has already had its one-time seeding tick, so it must never
/// be seeded again, which is exactly why this returns `Option<i64>`
/// rather than collapsing both into the same `-1` sentinel
/// `sequence`/`caught_up_to` use elsewhere.
async fn get_cross_context_route_cursor(
    pool: &Pool,
    source_bounded_context: &str,
    route_name: &str,
) -> crate::error::Result<Option<i64>> {
    let schema = schema_ident(source_bounded_context);
    let row: Option<(i64,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT last_dispatched_sequence FROM {schema}.cross_context_route_cursors \
         WHERE route_name = $1"
    )))
    .bind(route_name)
    .fetch_optional(pool)
    .await?;
    Ok(row.map(|(seq,)| seq))
}

/// Also unconditionally clears any retry backoff state (issue
/// #21) - every call site advances the cursor past an occurrence that is
/// now *done* one way or another (skipped, rejected, accepted, or
/// parked after retries were exhausted), so whatever retry state applied
/// to it is stale for the next occurrence regardless of which of those
/// outcomes this one was. See `catch_up_cross_context_route`'s own doc
/// comment.
async fn update_cross_context_route_cursor(
    pool: &Pool,
    source_bounded_context: &str,
    route_name: &str,
    sequence: i64,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    let schema = schema_ident(source_bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.cross_context_route_cursors \
         (route_name, last_dispatched_sequence, updated_at) VALUES ($1, $2, $3) \
         ON CONFLICT (route_name) DO UPDATE SET \
         last_dispatched_sequence = EXCLUDED.last_dispatched_sequence, \
         updated_at = EXCLUDED.updated_at, \
         retry_attempt_count = 0, \
         retry_first_failed_at = NULL, \
         retry_next_attempt_at = NULL"
    )))
    .bind(route_name)
    .bind(sequence)
    .bind(now)
    .execute(pool)
    .await?;
    Ok(())
}

/// `(retry_attempt_count, retry_first_failed_at, retry_next_attempt_at)` -
/// `get_cross_context_route_retry_state`'s own return shape, named only
/// to keep that signature (and clippy) happy, not used anywhere else.
type CrossContextRouteRetryState = (i32, Option<DateTime<Utc>>, Option<DateTime<Utc>>);

/// `catch_up_cross_context_route`'s own read of the retry backoff state
/// `record_cross_context_route_retry_failure` writes - `(0, None, None)`
/// when no row exists yet (this route has never ticked, or every prior
/// occurrence succeeded outright), the same "no row = nothing recorded"
/// convention `get_cross_context_route_cursor` already uses one level up.
async fn get_cross_context_route_retry_state(
    pool: &Pool,
    source_bounded_context: &str,
    route_name: &str,
) -> crate::error::Result<CrossContextRouteRetryState> {
    let schema = schema_ident(source_bounded_context);
    let row: Option<CrossContextRouteRetryState> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT retry_attempt_count, retry_first_failed_at, retry_next_attempt_at \
             FROM {schema}.cross_context_route_cursors WHERE route_name = $1"
    )))
    .bind(route_name)
    .fetch_optional(pool)
    .await?;
    Ok(row.unwrap_or((0, None, None)))
}

/// Persists one more failed attempt at the route's own blocked
/// head-of-line occurrence - `current_cursor` is `last_dispatched_sequence`'s
/// own current value (unchanged by this call; only present so the
/// `INSERT` branch of `ON CONFLICT` has a value to write for a route
/// whose very first-ever tick is already failing, before
/// `update_cross_context_route_cursor` has ever run for it). Doesn't
/// touch `updated_at` on conflict - that column tracks the cursor's own
/// last *advance*, not the last retry attempt.
#[allow(clippy::too_many_arguments)]
async fn record_cross_context_route_retry_failure(
    pool: &Pool,
    source_bounded_context: &str,
    route_name: &str,
    current_cursor: i64,
    attempt_count: i32,
    first_failed_at: DateTime<Utc>,
    next_attempt_at: DateTime<Utc>,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    let schema = schema_ident(source_bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.cross_context_route_cursors \
         (route_name, last_dispatched_sequence, updated_at, retry_attempt_count, \
          retry_first_failed_at, retry_next_attempt_at) \
         VALUES ($1, $2, $3, $4, $5, $6) \
         ON CONFLICT (route_name) DO UPDATE SET \
         retry_attempt_count = EXCLUDED.retry_attempt_count, \
         retry_first_failed_at = EXCLUDED.retry_first_failed_at, \
         retry_next_attempt_at = EXCLUDED.retry_next_attempt_at"
    )))
    .bind(route_name)
    .bind(current_cursor)
    .bind(now)
    .bind(attempt_count)
    .bind(first_failed_at)
    .bind(next_attempt_at)
    .execute(pool)
    .await?;
    Ok(())
}

/// Holds a route back until `next_attempt_at` without touching its
/// attempt count or first failure (docs/architecture.md §161) - unlike
/// [`record_cross_context_route_retry_failure`].
async fn defer_cross_context_route(
    pool: &Pool,
    source_bounded_context: &str,
    route_name: &str,
    current_cursor: i64,
    next_attempt_at: DateTime<Utc>,
) -> crate::error::Result<()> {
    let schema = schema_ident(source_bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.cross_context_route_cursors \
         (route_name, last_dispatched_sequence, updated_at, retry_next_attempt_at) \
         VALUES ($1, $2, $3, $4) \
         ON CONFLICT (route_name) DO UPDATE SET \
         retry_next_attempt_at = EXCLUDED.retry_next_attempt_at"
    )))
    .bind(route_name)
    .bind(current_cursor)
    .bind(Utc::now())
    .bind(next_attempt_at)
    .execute(pool)
    .await?;
    Ok(())
}

/// issue #21 - which family of thing a [`ParkedDelivery`]
/// originally was, and therefore how `retryParkedDelivery` redrives it.
/// `target_bounded_context`/`target_command_type` are populated only for
/// `CrossContextRoute` and `Deadline`; `ExternalEvent`/
/// `CommandTrigger` populate `access_token_id` instead (see
/// `ParkedDelivery`'s own doc comment for the full column-by-kind story).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ParkedDeliveryKind {
    CrossContextRoute,
    ExternalEvent,
    CommandTrigger,
    /// A deadline whose command kept failing (docs/architecture.md §115).
    Deadline,
}

impl ParkedDeliveryKind {
    fn as_str(self) -> &'static str {
        match self {
            ParkedDeliveryKind::CrossContextRoute => "cross_context_route",
            ParkedDeliveryKind::ExternalEvent => "external_event",
            ParkedDeliveryKind::CommandTrigger => "command_trigger",
            ParkedDeliveryKind::Deadline => "deadline",
        }
    }
}

fn parked_delivery_kind_from_str(s: &str) -> ParkedDeliveryKind {
    match s {
        "external_event" => ParkedDeliveryKind::ExternalEvent,
        "command_trigger" => ParkedDeliveryKind::CommandTrigger,
        "deadline" => ParkedDeliveryKind::Deadline,
        _ => ParkedDeliveryKind::CrossContextRoute,
    }
}

/// issue #21's own generic "parked delivery" record - see
/// `docs/architecture.md`'s parked-deliveries section for the full
/// design. `request_json` always carries enough to redrive a retry on
/// its own:
/// - `CrossContextRoute`: the `Target` command's own already-translated
///   JSON payload (`target_bounded_context`/`target_command_type` name
///   where to submit it - `access_token_id` is `None`).
/// - `ExternalEvent`/`CommandTrigger`: the bridge's own original
///   `ExternalEventRequest`/`CommandTriggerRequest` body, verbatim
///   (`target_bounded_context`/`target_command_type` are `None`;
///   `access_token_id` names which `ExternalEventToken`/`CommandToken`
///   to re-resolve and redrive through - the bridge's own credential,
///   never the token's secret, which is never stored here).
///
/// Lives in the same bounded-context schema the failing delivery itself
/// targeted - for `ExternalEvent`/`CommandTrigger`, that's
/// `access_token_id`'s own token's bounded context, resolved once at
/// ingestion time by `skilj-rest`'s `POST /v1/parked-deliveries` handler
/// (the same capability-based resolution every other REST route already
/// does), not a caller-supplied path/argument.
#[derive(Debug, Clone, PartialEq)]
pub struct ParkedDelivery {
    pub id: String,
    pub source: String,
    pub kind: ParkedDeliveryKind,
    pub identifier: String,
    pub access_token_id: Option<String>,
    pub target_bounded_context: Option<String>,
    pub target_command_type: Option<String>,
    pub request_json: serde_json::Value,
    pub error: String,
    pub attempt_count: i32,
    pub first_failed_at: DateTime<Utc>,
    pub last_failed_at: DateTime<Utc>,
}

#[derive(sqlx::FromRow)]
struct ParkedDeliveryRow {
    id: String,
    source: String,
    kind: String,
    identifier: String,
    access_token_id: Option<String>,
    target_bounded_context: Option<String>,
    target_command_type: Option<String>,
    request_json: Json<serde_json::Value>,
    error: String,
    attempt_count: i32,
    first_failed_at: DateTime<Utc>,
    last_failed_at: DateTime<Utc>,
}

impl From<ParkedDeliveryRow> for ParkedDelivery {
    fn from(row: ParkedDeliveryRow) -> Self {
        ParkedDelivery {
            id: row.id,
            source: row.source,
            kind: parked_delivery_kind_from_str(&row.kind),
            identifier: row.identifier,
            access_token_id: row.access_token_id,
            target_bounded_context: row.target_bounded_context,
            target_command_type: row.target_command_type,
            request_json: row.request_json.0,
            error: row.error,
            attempt_count: row.attempt_count,
            first_failed_at: row.first_failed_at,
            last_failed_at: row.last_failed_at,
        }
    }
}

const PARKED_DELIVERY_COLUMNS: &str = "id, source, kind, identifier, access_token_id, \
    target_bounded_context, target_command_type, request_json, error, attempt_count, \
    first_failed_at, last_failed_at";

/// issue #21 - `parked_deliveries`, one row per persistently-
/// failed delivery. A brand-new table, so (unlike
/// `cross_context_route_cursors`'s own retry columns above) no
/// already-provisioned bounded context needs a separate `ALTER TABLE`
/// patch - `CREATE TABLE IF NOT EXISTS`, called from both
/// `provision_bounded_context_schema` and every `build()`'s startup
/// loop, is the whole story, the same "brand-new table needs no
/// migration dance" register `ensure_external_message_cursors_table`'s
/// own doc comment already uses.
#[tracing::instrument(skip_all)]
pub async fn ensure_parked_deliveries_table<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    let index = create_index_patch(
        &schema,
        "parked_deliveries_page_order",
        format!(
            "CREATE INDEX IF NOT EXISTS parked_deliveries_page_order \
             ON {schema}.parked_deliveries (first_failed_at DESC, id DESC)"
        ),
    );
    sqlx::raw_sql(sqlx::AssertSqlSafe(format!(
        "CREATE TABLE IF NOT EXISTS {schema}.parked_deliveries (
            id TEXT PRIMARY KEY,
            source TEXT NOT NULL,
            kind TEXT NOT NULL,
            identifier TEXT NOT NULL,
            access_token_id TEXT,
            target_bounded_context TEXT,
            target_command_type TEXT,
            request_json JSONB NOT NULL,
            error TEXT NOT NULL,
            attempt_count INT NOT NULL,
            first_failed_at TIMESTAMPTZ NOT NULL,
            last_failed_at TIMESTAMPTZ NOT NULL
        );
        {index}"
    )))
    .execute(executor)
    .await?;
    Ok(())
}

/// The index this module's first parked-delivery migration created -
/// `(source, kind, identifier)` alone. Replaced by
/// [`PARKED_DELIVERIES_OCCURRENCE_INDEX`]; kept only so
/// `migrate_parked_deliveries_dedup_and_unique_index` can drop it.
const PARKED_DELIVERIES_LEGACY_DEDUP_INDEX: &str = "parked_deliveries_source_kind_identifier_key";

const PARKED_DELIVERIES_OCCURRENCE_INDEX: &str = "parked_deliveries_occurrence_key";

/// The `UNIQUE` index `insert_parked_delivery`'s own `ON CONFLICT` infers
/// against - one row per `(source, kind, identifier)` *per access token*.
/// The token is part of the key because it's what `retryParkedDelivery`
/// redrives under: with it left out, a second bridge credential
/// reporting a (guessable) identifier another credential already parked
/// would upsert onto that row, swapping its own `request_json` in under
/// the first token's authority. `COALESCE` rather than `NULLS NOT
/// DISTINCT` (Postgres 15+ only) so `CrossContextRoute`'s own
/// always-`NULL` rows still dedupe against each other; a real token id is
/// never empty, so `''` can't collide with one.
fn parked_deliveries_occurrence_index_ddl(schema: &str) -> String {
    format!(
        "CREATE UNIQUE INDEX IF NOT EXISTS {PARKED_DELIVERIES_OCCURRENCE_INDEX} \
         ON {schema}.parked_deliveries (source, kind, identifier, (COALESCE(access_token_id, '')))"
    )
}

/// issue #25 review (docs/architecture.md §56): belt-and-suspenders
/// for `catch_up_cross_context_route`'s own advisory-lock fix above -
/// a `UNIQUE` index identifying one real failed occurrence (see
/// `parked_deliveries_occurrence_index_ddl` for its exact key) so
/// `insert_parked_delivery`'s own `ON CONFLICT` can turn any remaining
/// duplicate-insert path, from this bug or a future one, into a harmless
/// upsert instead of a second row.
///
/// A live bounded context that already hit the race this fixes can have
/// real duplicate rows sitting in `parked_deliveries` already - creating
/// the index directly would fail outright against those, turning a
/// silent duplication bug into a hard startup error. So this runs as a
/// real migration, `migrate_idempotency_keys_client_id_scoping`'s own
/// shape: a dedicated transaction, a `pg_advisory_xact_lock` on the
/// schema name (serializing concurrent instances migrating the same
/// bounded context at startup), an idempotency check against
/// `pg_indexes` so an already-migrated schema is a cheap no-op, then the
/// actual work - here, deleting every duplicate but the newest
/// (`(last_failed_at, id)` descending; `id` only to break an exact tie,
/// never itself meaningful) before creating the index. A duplicate row
/// this deletes was never independently actionable - both were always
/// the identical occurrence records under `retryParkedDelivery`'s own
/// terms - so discarding all but one loses no real operator-facing
/// information, unlike `idempotency_keys`' own pre-migration rows.
///
/// A schema migrated under the earlier, narrower
/// `(source, kind, identifier)` index converges here too: that index is
/// strictly stricter, so its rows never violate the wider one, and it's
/// dropped once the wider one exists. A bounded context provisioned
/// after this existed already has the wider index from
/// `provision_bounded_context_schema` itself, and is a no-op here.
pub async fn migrate_parked_deliveries_dedup_and_unique_index(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    let raw_schema = format!("bc_{bounded_context}");

    let mut tx = pool.begin().await?;

    sqlx::query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)")
        .bind(&raw_schema)
        .execute(&mut *tx)
        .await?;

    let (has_current, has_legacy): (bool, bool) = sqlx::query_as(
        "SELECT \
            EXISTS (SELECT 1 FROM pg_indexes WHERE schemaname = $1 AND indexname = $2), \
            EXISTS (SELECT 1 FROM pg_indexes WHERE schemaname = $1 AND indexname = $3)",
    )
    .bind(&raw_schema)
    .bind(PARKED_DELIVERIES_OCCURRENCE_INDEX)
    .bind(PARKED_DELIVERIES_LEGACY_DEDUP_INDEX)
    .fetch_one(&mut *tx)
    .await?;

    if has_current && !has_legacy {
        tx.commit().await?;
        return Ok(());
    }

    if !has_current {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "DELETE FROM {schema}.parked_deliveries a USING {schema}.parked_deliveries b \
             WHERE a.source = b.source AND a.kind = b.kind AND a.identifier = b.identifier \
             AND a.access_token_id IS NOT DISTINCT FROM b.access_token_id \
             AND (a.last_failed_at, a.id) < (b.last_failed_at, b.id)"
        )))
        .execute(&mut *tx)
        .await?;
        sqlx::query(sqlx::AssertSqlSafe(parked_deliveries_occurrence_index_ddl(
            &schema,
        )))
        .execute(&mut *tx)
        .await?;
    }
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DROP INDEX IF EXISTS {schema}.{PARKED_DELIVERIES_LEGACY_DEDUP_INDEX}"
    )))
    .execute(&mut *tx)
    .await?;

    tx.commit().await?;
    Ok(())
}

/// `id` is generated here (`shared::generate_token_id`, the same opaque-
/// id generator every other synthetic identifier in this codebase
/// already uses - see its own doc comment) rather than left to the
/// caller, since nothing about a parked delivery's own identity needs to
/// be caller-chosen or caller-visible before this call returns it.
/// `ON CONFLICT` on `parked_deliveries_occurrence_index_ddl`'s key
/// (docs/architecture.md §56) turns a duplicate-occurrence insert into an
/// upsert that refreshes the failure details onto the existing row
/// rather than a second one -
/// `RETURNING` so the id/fields this returns always describe the row
/// that actually exists afterward, real either way (the fresh `id` this
/// generated, or the winning row's own from an earlier insert).
#[allow(clippy::too_many_arguments)]
pub async fn insert_parked_delivery(
    pool: &Pool,
    bounded_context: &str,
    source: &str,
    kind: ParkedDeliveryKind,
    identifier: &str,
    access_token_id: Option<&str>,
    target_bounded_context: Option<&str>,
    target_command_type: Option<&str>,
    request_json: &serde_json::Value,
    error: &str,
    attempt_count: i32,
    first_failed_at: DateTime<Utc>,
    last_failed_at: DateTime<Utc>,
) -> crate::error::Result<ParkedDelivery> {
    let schema = schema_ident(bounded_context);
    let id = crate::shared::generate_token_id();
    let row: ParkedDeliveryRow = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.parked_deliveries \
         (id, source, kind, identifier, access_token_id, target_bounded_context, \
          target_command_type, request_json, error, attempt_count, first_failed_at, \
          last_failed_at) \
         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12) \
         ON CONFLICT (source, kind, identifier, (COALESCE(access_token_id, ''))) DO UPDATE SET \
         request_json = EXCLUDED.request_json, \
         error = EXCLUDED.error, \
         attempt_count = EXCLUDED.attempt_count, \
         last_failed_at = EXCLUDED.last_failed_at \
         RETURNING {PARKED_DELIVERY_COLUMNS}"
    )))
    .bind(&id)
    .bind(source)
    .bind(kind.as_str())
    .bind(identifier)
    .bind(access_token_id)
    .bind(target_bounded_context)
    .bind(target_command_type)
    .bind(Json(request_json))
    .bind(error)
    .bind(attempt_count)
    .bind(first_failed_at)
    .bind(last_failed_at)
    .fetch_one(pool)
    .await?;
    Ok(row.into())
}

/// Every parked delivery in `bounded_context`, in page order (see
/// [`list_parked_deliveries_page`]). Unbounded - for tests and internal
/// checks; `parkedDeliveries` pages.
pub async fn list_parked_deliveries(
    pool: &Pool,
    bounded_context: &str,
) -> crate::error::Result<Vec<ParkedDelivery>> {
    list_parked_deliveries_page(pool, bounded_context, None, i64::MAX).await
}

/// `AdminAccess`-gated `parkedDeliveries(boundedContext:, after:)`'s own
/// read (docs/architecture.md §86): at most `limit` rows, newest parked
/// first, strictly after `after` in that order. The order is
/// `(first_failed_at DESC, id DESC)`, not `last_failed_at`: a retry
/// that fails again updates `last_failed_at`, which would move the row
/// across a page boundary mid-listing and skip or repeat it, while
/// `first_failed_at` never changes for a row.
pub async fn list_parked_deliveries_page(
    pool: &Pool,
    bounded_context: &str,
    after: Option<&ParkedDeliveryCursor>,
    limit: i64,
) -> crate::error::Result<Vec<ParkedDelivery>> {
    let schema = schema_ident(bounded_context);
    let rows: Vec<ParkedDeliveryRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {PARKED_DELIVERY_COLUMNS} FROM {schema}.parked_deliveries \
         WHERE $1::timestamptz IS NULL OR (first_failed_at, id) < ($1, $2) \
         ORDER BY first_failed_at DESC, id DESC LIMIT $3"
    )))
    .bind(after.map(|c| c.first_failed_at))
    .bind(after.map(|c| c.id.clone()))
    .bind(limit)
    .fetch_all(pool)
    .await?;
    Ok(rows.into_iter().map(ParkedDelivery::from).collect())
}

/// A position in [`list_parked_deliveries_page`]'s order. It carries the
/// position itself rather than naming a row, so it stays valid when that
/// row is retried or discarded between pages.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParkedDeliveryCursor {
    pub first_failed_at: DateTime<Utc>,
    pub id: String,
}

impl ParkedDeliveryCursor {
    pub fn of(delivery: &ParkedDelivery) -> Self {
        Self {
            first_failed_at: delivery.first_failed_at,
            id: delivery.id.clone(),
        }
    }

    /// `{microseconds since the epoch}:{id}` - opaque to clients.
    pub fn encode(&self) -> String {
        format!("{}:{}", self.first_failed_at.timestamp_micros(), self.id)
    }

    pub fn decode(cursor: &str) -> Option<Self> {
        let (micros, id) = cursor.split_once(':')?;
        Some(Self {
            first_failed_at: DateTime::from_timestamp_micros(micros.parse().ok()?)?,
            id: id.to_string(),
        })
    }
}

pub async fn get_parked_delivery(
    pool: &Pool,
    bounded_context: &str,
    id: &str,
) -> crate::error::Result<Option<ParkedDelivery>> {
    let schema = schema_ident(bounded_context);
    let row: Option<ParkedDeliveryRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {PARKED_DELIVERY_COLUMNS} FROM {schema}.parked_deliveries WHERE id = $1"
    )))
    .bind(id)
    .fetch_optional(pool)
    .await?;
    Ok(row.map(ParkedDelivery::from))
}

/// The `client_id` every `CrossContextRoute` submission runs under -
/// server-derived, never caller-suppliable (see
/// `RESERVED_IDEMPOTENCY_KEY_PREFIX`'s own doc comment).
pub const CROSS_CONTEXT_ROUTE_CLIENT_ID: &str = "cross-context-route";

/// A `CrossContextRoute`-kind parked row's `source` is this prefix plus
/// the route's name; its `identifier` is the source event's sequence.
const CROSS_CONTEXT_ROUTE_PARKED_SOURCE_PREFIX: &str = "cross-context-route:";

/// The idempotency key one route's submission for one source event runs
/// under - shared by `catch_up_cross_context_route` and
/// [`parked_delivery_redrive_identity`], so a redrive of a parked
/// occurrence dedupes against the original attempt if that attempt did
/// commit after all.
fn cross_context_route_idempotency_key(route_name: &str, source_sequence: &str) -> String {
    format!(
        "{}{route_name}:{source_sequence}",
        crate::event_store::RESERVED_IDEMPOTENCY_KEY_PREFIX
    )
}

/// The `(client_id, idempotency_key)` `retryParkedDelivery` redrives a
/// command-kind [`ParkedDelivery`] under, so that however many times it
/// is redriven (a retry whose submission committed but whose row delete
/// then failed, or one racing a lost lock) the command lands once:
///
/// - `CrossContextRoute`: the route's own client id and the exact key its
///   original attempt used. An attempt that failed on the caller's side
///   but committed anyway (a dropped connection after `COMMIT`) is then
///   a `Deduplicated` no-op on redrive, not a second command.
/// - `CommandTrigger`: the token's own client id (`caller_client_id`)
///   and `original_idempotency_key` - the `Idempotency-Key` the bridge's
///   original request carried, when it reported one - so an original
///   attempt that committed after all dedupes too. Without one, a key
///   reserved to this row (`RESERVED_PARKED_DELIVERY_IDEMPOTENCY_KEY_PREFIX`),
///   which only dedupes across redrives.
///
/// - `Deadline`: the deadline's own client id and reserved key, exactly
///   as `fire_due_deadlines` submitted it (docs/architecture.md §115).
///
/// `None` for `ExternalEvent`, which has no idempotency key - see
/// [`parked_delivery_redrive_dedupe_partition_key`] for its equivalent.
pub fn parked_delivery_redrive_identity(
    delivery: &ParkedDelivery,
    caller_client_id: &str,
    original_idempotency_key: Option<&str>,
) -> Option<(String, String)> {
    match delivery.kind {
        ParkedDeliveryKind::CrossContextRoute => {
            match delivery
                .source
                .strip_prefix(CROSS_CONTEXT_ROUTE_PARKED_SOURCE_PREFIX)
            {
                Some(route_name) => Some((
                    CROSS_CONTEXT_ROUTE_CLIENT_ID.to_string(),
                    cross_context_route_idempotency_key(route_name, &delivery.identifier),
                )),
                // Only `catch_up_cross_context_route` writes this kind,
                // always with that prefix; kept total rather than
                // panicking on a hand-edited row.
                None => Some((
                    CROSS_CONTEXT_ROUTE_CLIENT_ID.to_string(),
                    format!(
                        "{}{}",
                        crate::event_store::RESERVED_PARKED_DELIVERY_IDEMPOTENCY_KEY_PREFIX,
                        delivery.id
                    ),
                )),
            }
        }
        ParkedDeliveryKind::CommandTrigger => Some((
            caller_client_id.to_string(),
            match original_idempotency_key {
                Some(key) => key.to_string(),
                None => format!(
                    "{}{}",
                    crate::event_store::RESERVED_PARKED_DELIVERY_IDEMPOTENCY_KEY_PREFIX,
                    delivery.id
                ),
            },
        )),
        // The deadline's own reserved key: an attempt that failed on this
        // side but committed anyway dedupes, and so do repeated redrives.
        ParkedDeliveryKind::Deadline => Some((
            DEADLINE_CLIENT_ID.to_string(),
            format!(
                "{}{}",
                crate::event_store::RESERVED_DEADLINE_IDEMPOTENCY_KEY_PREFIX,
                delivery.identifier
            ),
        )),
        ParkedDeliveryKind::ExternalEvent => None,
    }
}

/// The `dedupe` partition every `ExternalEvent`-kind redrive uses,
/// always at sequence `1`: one partition per parked row, under the row's
/// own token (the watermark's `adapter_id`). The first redrive lands and
/// sets the watermark; any later redrive of the same row - one whose
/// event committed but whose row delete then failed - is `Redelivered`,
/// not a second event. The `ExternalEvent` counterpart of
/// [`parked_delivery_redrive_identity`]'s idempotency keys. Leaves one
/// `external_message_cursors` row per redrive, which is bounded by how
/// often operators retry parked deliveries.
///
/// Used even when the bridge's request carried a cursor of its own
/// (issue #58). By the time a parked message is retried, the
/// bridge has committed past it and kept recording that partition, so
/// the partition's watermark is usually beyond the parked sequence, and
/// redriving under the original cursor was deduped away - nothing
/// created, the row deleted as a success. The cost: an original attempt
/// that committed without the bridge hearing back, then got parked, is
/// created a second time on retry. The watermark keeps only the highest
/// sequence per partition, so that case can't be told apart from a
/// message later ones overtook (docs/architecture.md §173).
pub fn parked_delivery_redrive_dedupe_partition_key(delivery: &ParkedDelivery) -> String {
    format!(
        "{}{}",
        crate::event_store::RESERVED_PARKED_DELIVERY_IDEMPOTENCY_KEY_PREFIX,
        delivery.id
    )
}

/// `retryParkedDelivery`'s serialization: a lock-only transaction holding
/// a `pg_try_advisory_xact_lock` on this one parked row, the same
/// lock-only-transaction shape `catch_up_cross_context_route` uses per
/// route (docs/architecture.md §56). The caller re-reads the row *after*
/// this returns and keeps the transaction alive until its redrive and the
/// row's delete (or failure record) are done; dropping or committing it
/// releases the lock. Without it, two retries of one row both read it,
/// both redrive, and the delivery lands twice.
///
/// `None` when another retry of the same row holds the lock. Non-blocking
/// on purpose: a waiter would pin a pooled connection while the holder
/// still needs connections for its own redrive, and for an operator
/// action "already being retried" is a better answer than a queue.
pub async fn try_lock_parked_delivery_for_retry(
    pool: &Pool,
    bounded_context: &str,
    id: &str,
) -> crate::error::Result<Option<Transaction<'static, Postgres>>> {
    let mut lock_tx = pool.begin().await?;
    let acquired: bool =
        sqlx::query_scalar("SELECT pg_try_advisory_xact_lock(hashtext($1)::bigint)")
            .bind(format!("parked_delivery:{bounded_context}:{id}"))
            .fetch_one(&mut *lock_tx)
            .await?;
    Ok(acquired.then_some(lock_tx))
}

/// `retryParkedDelivery`'s own failed-again path - the row stays parked,
/// but its own `error`/`attempt_count`/`last_failed_at` reflect this
/// latest attempt rather than only the original one, so an operator
/// looking at the list sees it was actually retried, not just left
/// alone.
pub async fn record_parked_delivery_retry_failure(
    pool: &Pool,
    bounded_context: &str,
    id: &str,
    error: &str,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.parked_deliveries \
         SET error = $1, attempt_count = attempt_count + 1, last_failed_at = $2 \
         WHERE id = $3"
    )))
    .bind(error)
    .bind(now)
    .bind(id)
    .execute(pool)
    .await?;
    Ok(())
}

/// `forgetSubject`'s parked-delivery half (docs/architecture.md §91):
/// deletes every parked delivery in `bounded_context` whose request
/// references `(subject_key, subject_value)`, returning how many went. A
/// parked `request_json` is the plaintext request as it was submitted -
/// never encrypted - so destroying the subject's key leaves it readable to
/// any admin, and `retryParkedDelivery` would re-create the subject's data
/// under a fresh key. Called *before* the key is destroyed: if this failed
/// afterwards, `forgetSubject` couldn't be retried (the key is no longer
/// active) and the rows would stay.
///
/// A row references the subject when the payload its redrive would submit
/// names it through the target type's own sensitive fields - exactly the
/// subjects encryption would key it under (`sensitive_field_subjects`).
/// A row whose target type can't be resolved (its token or bounded
/// context gone) or whose request isn't the redrive's shape can't be
/// redriven anyway; it is deleted if the subject value appears anywhere in
/// its request, erring toward erasure.
pub async fn delete_parked_deliveries_for_subject(
    pool: &Pool,
    bounded_context: &str,
    subject_key: &str,
    subject_value: &str,
) -> crate::error::Result<u64> {
    let mut deleted = 0;
    let mut after: Option<ParkedDeliveryCursor> = None;
    let mut rules_cache = ParkedPayloadRulesCache::default();
    loop {
        let page = list_parked_deliveries_page(pool, bounded_context, after.as_ref(), 1000).await?;
        let Some(last) = page.last() else {
            return Ok(deleted);
        };
        after = Some(ParkedDeliveryCursor::of(last));
        for delivery in &page {
            if parked_delivery_references_subject(
                pool,
                &mut rules_cache,
                delivery,
                subject_key,
                subject_value,
            )
            .await?
                && delete_parked_delivery(pool, bounded_context, &delivery.id)
                    .await?
                    .is_some()
            {
                deleted += 1;
            }
        }
    }
}

async fn parked_delivery_references_subject(
    pool: &Pool,
    rules_cache: &mut ParkedPayloadRulesCache,
    delivery: &ParkedDelivery,
    subject_key: &str,
    subject_value: &str,
) -> crate::error::Result<bool> {
    let rules = rules_cache.get(pool, delivery).await?;
    Ok(match (rules, parked_delivery_payload(delivery)) {
        (Some(rules), Some(payload)) => {
            let payload = serde_json::to_string(payload)
                .expect("serde_json::Value serialization is infallible");
            crate::event_store::sensitive_field_subjects(&rules.sensitive_fields, &payload)
                .iter()
                .any(|(key, value)| key == subject_key && value == subject_value)
        }
        _ => json_mentions(&delivery.request_json, subject_value),
    })
}

/// What governs a parked delivery's payload: the declarations of the type
/// its redrive would submit it as - the target `CommandType` of a route
/// or deadline, the token's `EventType` for an external event, the
/// token's `CommandType` for a trigger.
#[derive(Debug, Clone)]
pub struct ParkedPayloadRules {
    pub sensitive_fields: Vec<SensitiveField>,
    pub private_fields: Vec<PrivateField>,
    pub tag_mappings: Vec<TagMapping>,
    pub owner_tag_key: Option<String>,
}

/// [`ParkedPayloadRules`] for `delivery`, or `None` when its type can't be
/// resolved any more (its token, bounded context or type is gone) - such
/// a row can't be redriven either.
pub async fn parked_delivery_payload_rules(
    pool: &Pool,
    delivery: &ParkedDelivery,
) -> crate::error::Result<Option<ParkedPayloadRules>> {
    let from_command = |ct: CommandType| ParkedPayloadRules {
        sensitive_fields: ct.sensitive_fields,
        private_fields: ct.private_fields,
        tag_mappings: ct.tag_mappings,
        owner_tag_key: ct.owner_tag_key,
    };
    Ok(match delivery.kind {
        ParkedDeliveryKind::CrossContextRoute | ParkedDeliveryKind::Deadline => match (
            &delivery.target_bounded_context,
            &delivery.target_command_type,
        ) {
            (Some(bc), Some(name)) => get_command_type(pool, bc, name).await?.map(from_command),
            _ => None,
        },
        ParkedDeliveryKind::ExternalEvent => match &delivery.access_token_id {
            Some(id) => get_external_event_token(pool, id).await?.map(|token| {
                let et = token.event_type;
                ParkedPayloadRules {
                    sensitive_fields: et.sensitive_fields,
                    private_fields: et.private_fields,
                    tag_mappings: et.tag_mappings,
                    owner_tag_key: et.owner_tag_key,
                }
            }),
            None => None,
        },
        ParkedDeliveryKind::CommandTrigger => match &delivery.access_token_id {
            Some(id) => get_command_token(pool, id)
                .await?
                .map(|token| from_command(token.command_type)),
            None => None,
        },
    })
}

/// [`parked_delivery_payload_rules`], memoized for the length of one
/// scan (docs/architecture.md §153). The rules depend only on what a row
/// targets - its route's or deadline's command type, or its bridge's
/// token - and the rows one bridge or route parks share that, so a scan
/// over thousands of rows needs a handful of lookups rather than a few
/// queries per row. `parkedDeliveries` filling a page for a scoped grant,
/// and `forgetSubject` sweeping every row, both walk arbitrarily many.
#[derive(Default)]
pub struct ParkedPayloadRulesCache {
    rules: std::collections::HashMap<String, Option<ParkedPayloadRules>>,
}

impl ParkedPayloadRulesCache {
    pub async fn get(
        &mut self,
        pool: &Pool,
        delivery: &ParkedDelivery,
    ) -> crate::error::Result<Option<ParkedPayloadRules>> {
        let key = match delivery.kind {
            ParkedDeliveryKind::CrossContextRoute | ParkedDeliveryKind::Deadline => format!(
                "type:{:?}:{:?}",
                delivery.target_bounded_context, delivery.target_command_type
            ),
            ParkedDeliveryKind::ExternalEvent => {
                format!("event-token:{:?}", delivery.access_token_id)
            }
            ParkedDeliveryKind::CommandTrigger => {
                format!("command-token:{:?}", delivery.access_token_id)
            }
        };
        if let Some(rules) = self.rules.get(&key) {
            return Ok(rules.clone());
        }
        let rules = parked_delivery_payload_rules(pool, delivery).await?;
        self.rules.insert(key, rules.clone());
        Ok(rules)
    }
}

/// The payload inside a parked delivery's request: the request itself for
/// a route or deadline, its `payload` field for an external event or a
/// trigger.
pub fn parked_delivery_payload(delivery: &ParkedDelivery) -> Option<&serde_json::Value> {
    match delivery.kind {
        ParkedDeliveryKind::CrossContextRoute | ParkedDeliveryKind::Deadline => {
            Some(&delivery.request_json)
        }
        ParkedDeliveryKind::ExternalEvent | ParkedDeliveryKind::CommandTrigger => {
            delivery.request_json.get("payload")
        }
    }
}

/// Whether `access_mapping` may see and handle `delivery`
/// (docs/architecture.md §119): always for an unscoped grant; for a
/// scoped one, only when the payload's owner - its owner tag, derived as
/// a stored record's would be - is the grant's scope. A type declaring no
/// owner tag is unowned and visible, as its events are to `queryEvents`.
/// A row whose type can't be resolved (`rules` is `None`) or whose payload
/// is missing fails closed.
pub fn parked_delivery_visible_to(
    delivery: &ParkedDelivery,
    rules: Option<&ParkedPayloadRules>,
    access_mapping: &RoleAccessMapping,
) -> bool {
    if access_mapping.scope.is_none() {
        return true;
    }
    let (Some(rules), Some(payload)) = (rules, parked_delivery_payload(delivery)) else {
        return false;
    };
    let payload =
        serde_json::to_string(payload).expect("serde_json::Value serialization is infallible");
    crate::event_store::tag_owner_scope_satisfied(
        &crate::event_store::derive_plain_tags(&rules.tag_mappings, &payload),
        rules.owner_tag_key.as_deref(),
        access_mapping.scope.as_deref(),
    )
}

/// `delivery` as `access_mapping` is shown it (docs/architecture.md
/// §119). The stored request is never encrypted - the write it carries
/// failed - so its protected leaves are masked here instead: a sensitive
/// field is `null` unless `sensitive_field_is_granted` for its subject,
/// and a private field is always `null`, since a parked request has no
/// author Role to be entitled to it (REST's fail-closed
/// `redact_private_fields` treatment). With its type unresolvable, the
/// whole payload is `null`: nothing says which leaves are protected. The
/// stored row itself is untouched; a redrive submits it in full.
pub fn render_parked_delivery(
    delivery: &ParkedDelivery,
    rules: Option<&ParkedPayloadRules>,
    access_mapping: &RoleAccessMapping,
) -> ParkedDelivery {
    let mut rendered = delivery.clone();
    let payload = match rendered.kind {
        ParkedDeliveryKind::CrossContextRoute | ParkedDeliveryKind::Deadline => {
            Some(&mut rendered.request_json)
        }
        ParkedDeliveryKind::ExternalEvent | ParkedDeliveryKind::CommandTrigger => {
            rendered.request_json.get_mut("payload")
        }
    };
    let Some(payload) = payload else {
        return rendered;
    };
    let Some(rules) = rules else {
        *payload = serde_json::Value::Null;
        return rendered;
    };
    let original = payload.clone();
    for sf in &rules.sensitive_fields {
        let subject = crate::event_store::payload_field_value(&original, &sf.subject_field)
            .and_then(crate::event_store::json_scalar_to_string);
        let granted = subject.is_some_and(|subject| {
            crate::event_store::sensitive_field_is_granted(access_mapping, &subject)
        });
        if !granted {
            if let Some(leaf) = crate::event_store::payload_field_value_mut(payload, &sf.field) {
                *leaf = serde_json::Value::Null;
            }
        }
    }
    for pf in &rules.private_fields {
        if let Some(leaf) = crate::event_store::payload_field_value_mut(payload, &pf.field) {
            *leaf = serde_json::Value::Null;
        }
    }
    rendered
}

/// `forgetSubject`'s deadline half (docs/architecture.md §132): every
/// still-`pending` deadline targeting `bounded_context` whose payload
/// names the subject is resolved as `forgotten`, its payload cleared. A
/// deadline stores its target command's payload in plaintext until it
/// fires - outside any key's reach - and firing after the subject was
/// forgotten would submit that data again under a fresh key. Deadlines
/// live with their schedule's source bounded context, not their target,
/// so every bounded context's `deadlines` table is walked, a page at a
/// time. A row names the subject when its payload does through the
/// target command type's sensitive fields (`sensitive_field_subjects`),
/// or - when that type is gone, or the payload doesn't parse - when the
/// subject value appears anywhere in it, erring toward erasure as
/// [`delete_parked_deliveries_for_subject`] does. A row already `firing`
/// is past stopping and left alone; its payload is cleared when it
/// resolves. The resolved row stays, as a trace that a deadline was
/// forgotten rather than fired or cancelled. A row resolved (fired,
/// cancelled, parked) before resolution cleared its payload still holds
/// it, and has it cleared here too, keeping its status
/// (docs/architecture.md §162). Returns how many pending deadlines were
/// resolved as `forgotten`.
pub async fn forget_subject_in_deadlines(
    pool: &Pool,
    bounded_context: &str,
    subject_key: &str,
    subject_value: &str,
    now: DateTime<Utc>,
) -> crate::error::Result<u64> {
    let mut forgotten = 0;
    let mut sensitive_fields = std::collections::HashMap::new();
    for holder in list_bounded_contexts(pool).await? {
        match forget_subject_in_holder_deadlines(
            pool,
            &holder.name,
            bounded_context,
            subject_key,
            subject_value,
            now,
            &mut sensitive_fields,
        )
        .await
        {
            Ok(n) => forgotten += n,
            // docs/architecture.md §157: deleted since the listing - its
            // deadlines went with it.
            Err(_) if get_bounded_context(pool, &holder.name).await?.is_none() => {}
            Err(err) => return Err(err),
        }
    }
    Ok(forgotten)
}

/// [`forget_subject_in_deadlines`] for the deadlines one bounded context,
/// `holder`, stores.
async fn forget_subject_in_holder_deadlines(
    pool: &Pool,
    holder: &str,
    bounded_context: &str,
    subject_key: &str,
    subject_value: &str,
    now: DateTime<Utc>,
    sensitive_fields: &mut std::collections::HashMap<String, Option<Vec<SensitiveField>>>,
) -> crate::error::Result<u64> {
    const PAGE: i64 = 1000;
    let schema = schema_ident(holder);
    let mut forgotten = 0;
    let mut after = String::new();
    loop {
        // Pending rows, and resolved ones still holding a payload - a row
        // resolved before resolution cleared it (docs/architecture.md §162).
        let rows: Vec<(String, String, String, String)> =
            sqlx::query_as(sqlx::AssertSqlSafe(format!(
                "SELECT id, target_command_type, payload, status FROM {schema}.deadlines \
                 WHERE target_bounded_context = $1 AND id > $2 \
                 AND (status = 'pending' OR (status <> 'firing' AND payload <> '{{}}')) \
                 ORDER BY id LIMIT $3"
            )))
            .bind(bounded_context)
            .bind(&after)
            .bind(PAGE)
            .fetch_all(pool)
            .await?;
        let Some((last_id, _, _, _)) = rows.last() else {
            break;
        };
        after = last_id.clone();
        for (id, command_type, payload, status) in &rows {
            if !sensitive_fields.contains_key(command_type) {
                let fields = get_command_type(pool, bounded_context, command_type)
                    .await?
                    .map(|ct| ct.sensitive_fields);
                sensitive_fields.insert(command_type.clone(), fields);
            }
            let parsed = serde_json::from_str::<serde_json::Value>(payload).ok();
            let names_subject = match (&sensitive_fields[command_type], &parsed) {
                (Some(fields), Some(_)) => {
                    crate::event_store::sensitive_field_subjects(fields, payload)
                        .iter()
                        .any(|(key, value)| key == subject_key && value == subject_value)
                }
                (_, Some(json)) => json_mentions(json, subject_value),
                (_, None) => payload.contains(subject_value),
            };
            if names_subject && status == "pending" {
                forgotten += sqlx::query(sqlx::AssertSqlSafe(format!(
                    "UPDATE {schema}.deadlines \
                     SET status = 'forgotten', payload = '{{}}', resolved_at = $1 \
                     WHERE id = $2 AND status = 'pending'"
                )))
                .bind(now)
                .bind(id)
                .execute(pool)
                .await?
                .rows_affected();
            } else if names_subject {
                sqlx::query(sqlx::AssertSqlSafe(format!(
                    "UPDATE {schema}.deadlines SET payload = '{{}}' \
                     WHERE id = $1 AND status NOT IN ('pending', 'firing')"
                )))
                .bind(id)
                .execute(pool)
                .await?;
            }
        }
        if (rows.len() as i64) < PAGE {
            break;
        }
    }
    Ok(forgotten)
}

/// Whether `value` appears as a string leaf, or a number/bool rendered as
/// a string, anywhere in `json`.
fn json_mentions(json: &serde_json::Value, value: &str) -> bool {
    match json {
        serde_json::Value::String(s) => s == value,
        serde_json::Value::Number(n) => n.to_string() == value,
        serde_json::Value::Bool(b) => b.to_string() == value,
        serde_json::Value::Array(items) => items.iter().any(|v| json_mentions(v, value)),
        serde_json::Value::Object(fields) => fields.values().any(|v| json_mentions(v, value)),
        serde_json::Value::Null => false,
    }
}

/// `discardParkedDelivery`'s own write, and `retryParkedDelivery`'s own
/// success path (a delivery that finally landed is no longer "stuck",
/// so it leaves this table the same way a resolved
/// `discardProjectionRebuild` row does - no separate `resolved`/
/// `discarded` status to track, `delete_projection_rebuild`'s own
/// register). Returns the row as it was immediately before deletion, the
/// same "hand back what's gone" treatment `discard_projection_rebuild`'s
/// own doc comment gives for the identical reason: the caller (a GraphQL
/// mutation) still needs to render it in its response.
pub async fn delete_parked_delivery(
    pool: &Pool,
    bounded_context: &str,
    id: &str,
) -> crate::error::Result<Option<ParkedDelivery>> {
    let existing = get_parked_delivery(pool, bounded_context, id).await?;
    if existing.is_none() {
        return Ok(None);
    }
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.parked_deliveries WHERE id = $1"
    )))
    .bind(id)
    .execute(pool)
    .await?;
    Ok(existing)
}

/// One catch-up tick for one registered [`crate::plugin::CrossContextRoute`] -
/// called in a loop, on a timer, by the single shared background task
/// `SkiljBuilder::build()` spawns (docs/architecture.md's own write-up
/// of this pass), the same "one shared task, not one per route" register
/// `catch_up_bounded_context`/`catch_up_snapshots` already use.
///
/// Fetches every `Source` occurrence since this route's own cursor
/// (`list_events_cached`, already filtered to `Source`'s own event type -
/// the identical read path `EventReadToken`-based REST consumption
/// already uses), and for each one, in sequence order: asks the
/// type-erased dispatcher to translate the payload
/// (`CrossContextRouteDispatcher::route`), submits `Target`'s own
/// command through [`decide_and_submit_command`] when it produces one,
/// then advances the cursor to that occurrence's own sequence
/// regardless of the outcome - a skip, a rejection, and an accepted
/// submission are all equally "this occurrence is done", only a real
/// `Err` (a transient failure worth retrying next tick) leaves the
/// cursor where it was, stopping this route's own catch-up for this
/// tick without losing anything (the next tick re-fetches from the same
/// cursor).
///
/// **First-ever tick, `CrossContextRoute::START_FROM != Beginning`**:
/// when `get_cross_context_route_cursor` comes back `None` (no row -
/// this route has never ticked before) and the route asks to start
/// anywhere other than `Beginning`, this tick does no dispatching at
/// all. It instead loads `Source`'s own occurrences once (the identical
/// `list_events_cached` call the normal path below makes, from `-1`) -
/// needed to compute `Latest`'s/`AtTime`'s own seed, paid unconditionally
/// even for `AtSequence` (which doesn't need it) for one shared code
/// path rather than a fourth special case - purely to find the seed
/// sequence, writes the cursor row there (or leaves it at `-1`,
/// unchanged, if there's nothing to seed past), and returns - so every
/// occurrence that already existed at registration time is treated as
/// "already seen" without a single `route()` call or `Target` submission
/// for any of them:
/// - `Latest`: the highest sequence among every loaded occurrence.
/// - `AtSequence(n)`: `n` directly - no need to look at `events` at all,
///   the same "opaque, unvalidated value" treatment
///   `EventReadToken.start_at_sequence` gets.
/// - `AtTime(unix_secs)`: the highest sequence among occurrences whose
///   own `metadata.created_at` is at or before that moment - the
///   identical `at_time_position` computation `event_store::consume_events`
///   makes, minus the scope filter (`CrossContextRoute` has no scope
///   concept to filter by).
///
/// This is the mechanism that stops a brand-new route like
/// `UserRegistered -> SendWelcomeEmail` from emailing every user who has
/// ever registered: exactly one full history load, exactly once, ever,
/// for this route - every later tick reads the real cursor row this
/// seeded and only ever sees genuinely new occurrences, the same as a
/// `Beginning` route always has.
///
/// **issue #21**: `decide_and_submit_command`'s own `Err` used
/// to propagate straight out of this function via a bare `?`, which
/// stopped this tick immediately without advancing the cursor - correct
/// as far as it went (a crash-safe "the next tick retries the identical
/// occurrence"), but with no cap: a persistently-failing occurrence
/// blocked this route's cursor forever, retried on every single poll
/// tick, unthrottled. Replaced with `retry_policy` (`skilj_retry::
/// RetryPolicy`): each failure grows the backoff before this route's
/// blocked head-of-line occurrence is attempted again (the "not yet
/// time" early return below, backed by `cross_context_route_cursors`'
/// own new `retry_*` columns), and once the policy is exhausted, the
/// occurrence is recorded as a [`ParkedDelivery`] (`source:
/// "cross-context-route:{route.name}"`, `kind: CrossContextRoute`) and
/// the cursor finally advances past it - the route un-blocks, and an
/// operator gets a visible, retryable/discardable record instead of a
/// route silently stuck forever.
///
/// **issue #25 review (docs/architecture.md §56)**: this whole
/// tick - reading `retry_attempt_count`, deciding whether the policy is
/// exhausted, and either recording another backoff or parking - is a
/// plain read-then-write with no lock of its own, so two instances
/// polling the same route concurrently could both read the same
/// almost-exhausted retry state, both independently exhaust it, and both
/// call `insert_parked_delivery` for the identical occurrence: two rows
/// for one real failure. Closed by serializing the *entire* tick per
/// `route_name` with a blocking `pg_advisory_xact_lock` - the identical
/// primitive `lock_read_cursor_for_consume` already uses for its own
/// claim race, just held on a dedicated lock-only transaction here
/// rather than the transaction the protected work itself runs in: this
/// function's own work already spans many independent pooled calls
/// (`decide_and_submit_command` alone opens and commits its own nested
/// transaction), so threading one shared transaction through all of it
/// would be a far larger change than this fix calls for. A lock held on
/// its own connection for the tick's whole duration serializes callers
/// just as effectively, since what needs protecting is "only one
/// instance runs this route's tick at a time," not any single row.
#[allow(clippy::too_many_arguments)]
#[tracing::instrument(skip_all, fields(route = %route.name))]
pub async fn catch_up_cross_context_route(
    pool: &Pool,
    route: &crate::plugin::CrossContextRouteInfo,
    route_dispatcher: &dyn crate::plugin::CrossContextRouteDispatcher,
    command_dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    snapshot_dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    key_service: Option<&KeyService>,
    retry_policy: &skilj_retry::RetryPolicy,
) -> crate::error::Result<()> {
    // Held for this whole call's duration on a dedicated transaction
    // that carries no application writes of its own - `pg_advisory_xact_lock`
    // releases automatically when it commits (the success path) or rolls
    // back (dropped on an early `?` return), so there's no separate
    // unlock call to forget on any exit path. See this function's own
    // doc comment above for why the lock's connection is deliberately
    // not the same one the tick's own reads/writes use.
    let mut lock_tx = pool.begin().await?;
    let lock_key = format!(
        "cross_context_route:{}:{}",
        route.source_bounded_context, route.name
    );
    sqlx::query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)")
        .bind(&lock_key)
        .execute(&mut *lock_tx)
        .await?;
    let result = catch_up_cross_context_route_locked(
        pool,
        route,
        route_dispatcher,
        command_dispatcher,
        projection_dispatcher,
        snapshot_dispatcher,
        broadcaster,
        event_cache,
        key_service,
        retry_policy,
    )
    .await;
    lock_tx.commit().await?;
    result
}

#[allow(clippy::too_many_arguments)]
async fn catch_up_cross_context_route_locked(
    pool: &Pool,
    route: &crate::plugin::CrossContextRouteInfo,
    route_dispatcher: &dyn crate::plugin::CrossContextRouteDispatcher,
    command_dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    snapshot_dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    key_service: Option<&KeyService>,
    retry_policy: &skilj_retry::RetryPolicy,
) -> crate::error::Result<()> {
    let existing_cursor =
        get_cross_context_route_cursor(pool, route.source_bounded_context, route.name).await?;
    let cursor = existing_cursor.unwrap_or(-1);
    if existing_cursor.is_none()
        && route.start_from != crate::plugin::CrossContextRouteStartFrom::Beginning
    {
        // First-ever tick: seed the cursor and dispatch nothing. The
        // seed is one `MAX(sequence)`, not a scan of the loaded history.
        let seed = match route.start_from {
            crate::plugin::CrossContextRouteStartFrom::Beginning => {
                unreachable!("excluded by this branch's own condition above")
            }
            crate::plugin::CrossContextRouteStartFrom::Latest => {
                highest_sequence_of_type(
                    pool,
                    route.source_bounded_context,
                    route.source_event_type,
                    None,
                )
                .await?
            }
            crate::plugin::CrossContextRouteStartFrom::AtSequence(n) => n,
            crate::plugin::CrossContextRouteStartFrom::AtTime(unix_secs) => {
                let threshold = DateTime::from_timestamp(unix_secs, 0).unwrap_or(Utc::now());
                highest_sequence_of_type(
                    pool,
                    route.source_bounded_context,
                    route.source_event_type,
                    Some(threshold),
                )
                .await?
            }
        };
        update_cross_context_route_cursor(
            pool,
            route.source_bounded_context,
            route.name,
            seed,
            Utc::now(),
        )
        .await?;
        return Ok(());
    }

    // At most `MAX_EVENTS_PER_CATCH_UP_TICK` per tick - the cursor
    // persists per processed event, so the next tick continues exactly
    // where this one stopped, and a long backlog is never loaded whole.
    let events = list_events_cached_limited(
        pool,
        event_cache,
        route.source_bounded_context,
        route.source_event_type,
        cursor,
        MAX_EVENTS_PER_CATCH_UP_TICK,
    )
    .await?;

    // issue #21 - see this function's own doc comment. Read
    // once per tick, ahead of the loop: only the loop's own first
    // occurrence can ever be a retry of a previously-failed one, since
    // the cursor never advances past a blocked occurrence - the same
    // invariant `cross_context_route_cursors` needing only one row's
    // worth of retry state (not one per occurrence) already relies on.
    let (mut retry_attempt, mut retry_first_failed_at, retry_next_attempt_at) =
        get_cross_context_route_retry_state(pool, route.source_bounded_context, route.name).await?;
    // Not gated on `retry_attempt > 0`: a deferral to another instance
    // (docs/architecture.md §161) sets a next attempt without spending
    // one. Advancing the cursor clears it.
    if let Some(next_attempt_at) = retry_next_attempt_at {
        if Utc::now() < next_attempt_at {
            // Not yet time - this route's own blocked occurrence is
            // still in backoff. Skip this tick entirely rather than
            // re-attempting the identical failing submission on
            // every single poll.
            return Ok(());
        }
    }

    for event in &events {
        match route_dispatcher.route(route.name, &event.payload) {
            None => {
                // Defensive only - `route.name` came from this same
                // dispatcher's own `routes()` list, so this should never
                // actually happen. Still advances the cursor below
                // rather than looping on it forever.
                tracing::warn!(
                    sequence = event.sequence,
                    "cross-context route not found in its own dispatcher - skipping"
                );
            }
            Some(Err(e)) => {
                // The stored payload didn't deserialize into `Source::
                // Payload` - see `BoundedContextEvent::try_from_event`'s
                // own doc comment on why this is reachable. Retrying can
                // never fix a payload the event itself was stored with,
                // so this is logged and skipped, not retried forever.
                tracing::warn!(
                    sequence = event.sequence,
                    error = %e,
                    "cross-context route: source payload did not deserialize - skipping"
                );
            }
            Some(Ok(None)) => {
                // `route()` itself decided this occurrence doesn't
                // apply - a real, expected outcome, not an error.
            }
            Some(Ok(Some(target_payload))) => {
                let Some(target_command_type) = get_command_type(
                    pool,
                    route.target_bounded_context,
                    route.target_command_type,
                )
                .await?
                else {
                    tracing::warn!(
                        sequence = event.sequence,
                        target_bounded_context = route.target_bounded_context,
                        target_command_type = route.target_command_type,
                        "cross-context route's own target CommandType isn't registered - \
                         skipping this occurrence, cursor still advances"
                    );
                    update_cross_context_route_cursor(
                        pool,
                        route.source_bounded_context,
                        route.name,
                        event.sequence,
                        Utc::now(),
                    )
                    .await?;
                    retry_attempt = 0;
                    retry_first_failed_at = None;
                    continue;
                };
                // Prefixed with `RESERVED_IDEMPOTENCY_KEY_PREFIX` - a
                // Historical note (docs/architecture.md §36/§37): this
                // prefix originally existed because `idempotency_keys`
                // had no caller/client_id column at all, so an ordinary
                // Write-level caller could pre-plant `"{route.name}:{sequence}"`
                // via `submitCommand`/`Idempotency-Key` ahead of time and
                // silently swallow this submission as a `Deduplicated`
                // no-op. `idempotency_keys` is `client_id`-scoped now (this
                // call's own `client_id` below is always `"cross-context-route"`,
                // never externally suppliable), which closes that gap
                // structurally - this reservation is kept as a harmless
                // second layer, not the load-bearing defense it was.
                let idempotency_key =
                    cross_context_route_idempotency_key(route.name, &event.sequence.to_string());
                // issue #18: the routed command finally gets a
                // real answer to "what caused this" - forward-carrying
                // the source event's own correlation_id (always present
                // by this point) and naming the source event itself as
                // the direct cause, via `event_causation_id`'s composed
                // `{bounded_context}:{sequence}` string (`Event` has no
                // synthetic id of its own to use instead - see that
                // helper's own doc comment).
                // issue #98: an approval-required target becomes a
                // proposal here too, never a direct submission - otherwise
                // whoever can cause the source event bypasses the approver.
                // `Ok(None)` is "proposed"; errors take the same retry/park
                // path as a failed submission.
                let causation_id = crate::event_store::event_causation_id(event);
                let outcome = match propose_if_approval_required(
                    pool,
                    &target_command_type,
                    &target_payload,
                    CROSS_CONTEXT_ROUTE_CLIENT_ID,
                    event.metadata.correlation_id.as_deref(),
                    Some(&causation_id),
                    &idempotency_key,
                    key_service,
                    Utc::now(),
                )
                .await
                {
                    Ok(true) => Ok(None),
                    Ok(false) => decide_and_submit_command(
                        pool,
                        command_dispatcher,
                        projection_dispatcher,
                        snapshot_dispatcher,
                        broadcaster,
                        event_cache,
                        &target_command_type,
                        &target_payload,
                        CROSS_CONTEXT_ROUTE_CLIENT_ID,
                        event.metadata.correlation_id.as_deref(),
                        Some(&causation_id),
                        key_service,
                        Utc::now(),
                        Some(&idempotency_key),
                        None,
                    )
                    .await
                    .map(Some),
                    Err(e) => Err(e),
                };
                // issue #21 - see this function's own doc
                // comment. `Err` no longer propagates straight out via
                // `?`; it's retried with backoff, up to `retry_policy`,
                // before this occurrence is parked.
                let outcome = match outcome {
                    Ok(outcome) => outcome,
                    Err(e) if e.another_instance_can_do_it() => {
                        // docs/architecture.md §161: no attempt spent, never
                        // parked - the route waits for an instance that can.
                        let next_attempt_at = Utc::now()
                            + chrono::Duration::from_std(ANOTHER_INSTANCE_RETRY_DELAY)
                                .expect("a ten-second delay fits a chrono::Duration");
                        tracing::warn!(
                            sequence = event.sequence,
                            error = %e,
                            next_attempt_at = %next_attempt_at,
                            "cross-context route: this instance can't submit the target \
                             command, another can - retrying later; route blocked until then"
                        );
                        defer_cross_context_route(
                            pool,
                            route.source_bounded_context,
                            route.name,
                            cursor,
                            next_attempt_at,
                        )
                        .await?;
                        return Ok(());
                    }
                    Err(e) => {
                        retry_attempt += 1;
                        // Every path out of this `Err` arm either
                        // `continue`s (after resetting `retry_attempt`/
                        // `retry_first_failed_at` to their defaults - the
                        // occurrence is done, parked) or `return`s (the
                        // function exits before the outer
                        // `retry_first_failed_at` would ever be read
                        // again) - so unlike `retry_attempt`, there's no
                        // corresponding outer reassignment needed for
                        // `first_failed_at` here, only this local,
                        // already-resolved value.
                        let first_failed_at = retry_first_failed_at.unwrap_or_else(Utc::now);
                        let now = Utc::now();
                        let elapsed = (now - first_failed_at).to_std().unwrap_or_default();
                        if retry_policy.is_exhausted(retry_attempt as u32, elapsed) {
                            tracing::error!(
                                sequence = event.sequence,
                                error = %e,
                                attempt = retry_attempt,
                                "cross-context route: target command submission failed \
                                 repeatedly - parking and skipping this occurrence"
                            );
                            let request_json = serde_json::from_str(&target_payload)
                                .unwrap_or(serde_json::Value::String(target_payload));
                            insert_parked_delivery(
                                pool,
                                route.target_bounded_context,
                                &format!(
                                    "{CROSS_CONTEXT_ROUTE_PARKED_SOURCE_PREFIX}{}",
                                    route.name
                                ),
                                ParkedDeliveryKind::CrossContextRoute,
                                &event.sequence.to_string(),
                                None,
                                Some(route.target_bounded_context),
                                Some(route.target_command_type),
                                &request_json,
                                &e.to_string(),
                                retry_attempt,
                                first_failed_at,
                                now,
                            )
                            .await?;
                            update_cross_context_route_cursor(
                                pool,
                                route.source_bounded_context,
                                route.name,
                                event.sequence,
                                now,
                            )
                            .await?;
                            retry_attempt = 0;
                            retry_first_failed_at = None;
                            continue;
                        }
                        let next_attempt_at =
                            retry_policy.next_attempt_at(now, retry_attempt as u32);
                        tracing::warn!(
                            sequence = event.sequence,
                            error = %e,
                            attempt = retry_attempt,
                            next_attempt_at = %next_attempt_at,
                            "cross-context route: target command submission failed - will \
                             retry with backoff; route blocked until then"
                        );
                        record_cross_context_route_retry_failure(
                            pool,
                            route.source_bounded_context,
                            route.name,
                            cursor,
                            retry_attempt,
                            first_failed_at,
                            next_attempt_at,
                            now,
                        )
                        .await?;
                        return Ok(());
                    }
                };
                // Defence in depth, not solely a bypass signal: with the
                // prefix reserved, nothing *else* can write into this
                // namespace, but this route's own past attempt at this
                // exact occurrence can - a process crash/restart between
                // this submission committing and the cursor advancing
                // below leaves the cursor pointing at this same source
                // event, so the next tick re-derives the identical key
                // and correctly lands here. That's ordinary, benign
                // crash recovery, not an anomaly - warned rather than
                // errored either way, since the cursor still correctly
                // advances past this occurrence.
                if matches!(outcome, Some(SubmitCommandOutcome::Deduplicated { .. })) {
                    tracing::warn!(
                        sequence = event.sequence,
                        "cross-context route's own idempotency key was already present - \
                         expected after a crash/restart between a prior submission and its \
                         cursor advance; unexpected otherwise, since the key space is reserved"
                    );
                }
            }
        }
        update_cross_context_route_cursor(
            pool,
            route.source_bounded_context,
            route.name,
            event.sequence,
            Utc::now(),
        )
        .await?;
        retry_attempt = 0;
        retry_first_failed_at = None;
    }
    Ok(())
}

// --- issue #20: native one-shot, per-entity deadlines ---
//
// `catch_up_schedule_deadline`/`catch_up_cancel_deadline` are
// `catch_up_cross_context_route`'s own shape, applied to
// `ScheduleDeadline`/`CancelDeadline` instead of `CrossContextRoute` -
// walk one registered reactor's own `Source` event stream after its
// cursor, react to every occurrence, advance the cursor past it either
// way. `fire_due_deadlines` has no `CrossContextRoute` analogue: it
// isn't tied to any one registered type, it scans the `deadlines` table
// itself by `fire_at`, the same register `scheduler_tick_for_bounded_context`'s
// own due-occurrence scan already is.

/// `deadline_cursors`' own read - `get_cross_context_route_cursor`'s
/// analogue, `cursor_owner` a `ScheduleDeadline::NAME`/`CancelDeadline::NAME`.
async fn get_deadline_cursor(
    pool: &Pool,
    bounded_context: &str,
    cursor_owner: &str,
) -> crate::error::Result<Option<i64>> {
    let schema = schema_ident(bounded_context);
    let row: Option<(i64,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT last_dispatched_sequence FROM {schema}.deadline_cursors WHERE cursor_owner = $1"
    )))
    .bind(cursor_owner)
    .fetch_optional(pool)
    .await?;
    Ok(row.map(|(seq,)| seq))
}

async fn update_deadline_cursor(
    pool: &Pool,
    bounded_context: &str,
    cursor_owner: &str,
    sequence: i64,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.deadline_cursors \
         (cursor_owner, last_dispatched_sequence, updated_at) VALUES ($1, $2, $3) \
         ON CONFLICT (cursor_owner) DO UPDATE SET \
         last_dispatched_sequence = EXCLUDED.last_dispatched_sequence, \
         updated_at = EXCLUDED.updated_at"
    )))
    .bind(cursor_owner)
    .bind(sequence)
    .bind(now)
    .execute(pool)
    .await?;
    Ok(())
}

/// One registered `ScheduleDeadline`'s own catch-up tick - see this
/// section's own header comment, and `catch_up_cross_context_route`'s
/// doc comment for the full "first-ever tick seeding" reasoning
/// `start_from != Beginning` shares with it verbatim.
pub async fn catch_up_schedule_deadline(
    pool: &Pool,
    schedule: &crate::plugin::ScheduleDeadlineInfo,
    dispatcher: &dyn crate::plugin::ScheduleDeadlineDispatcher,
    event_cache: &crate::event_cache::EventCache,
) -> crate::error::Result<()> {
    let existing_cursor =
        get_deadline_cursor(pool, schedule.source_bounded_context, schedule.name).await?;
    let cursor = existing_cursor.unwrap_or(-1);
    if existing_cursor.is_none()
        && schedule.start_from != crate::plugin::DeadlinePollStartFrom::Beginning
    {
        // First-ever tick: seed the cursor and dispatch nothing. The
        // seed is one `MAX(sequence)`, not a scan of the loaded history.
        let seed = match schedule.start_from {
            crate::plugin::DeadlinePollStartFrom::Beginning => {
                unreachable!("excluded by this branch's own condition above")
            }
            crate::plugin::DeadlinePollStartFrom::Latest => {
                highest_sequence_of_type(
                    pool,
                    schedule.source_bounded_context,
                    schedule.source_event_type,
                    None,
                )
                .await?
            }
            crate::plugin::DeadlinePollStartFrom::AtSequence(n) => n,
            crate::plugin::DeadlinePollStartFrom::AtTime(unix_secs) => {
                let threshold = DateTime::from_timestamp(unix_secs, 0).unwrap_or(Utc::now());
                highest_sequence_of_type(
                    pool,
                    schedule.source_bounded_context,
                    schedule.source_event_type,
                    Some(threshold),
                )
                .await?
            }
        };
        update_deadline_cursor(
            pool,
            schedule.source_bounded_context,
            schedule.name,
            seed,
            Utc::now(),
        )
        .await?;
        return Ok(());
    }

    // At most `MAX_EVENTS_PER_CATCH_UP_TICK` per tick - the cursor
    // persists per processed event, so the next tick continues exactly
    // where this one stopped, and a long backlog is never loaded whole.
    let events = list_events_cached_limited(
        pool,
        event_cache,
        schedule.source_bounded_context,
        schedule.source_event_type,
        cursor,
        MAX_EVENTS_PER_CATCH_UP_TICK,
    )
    .await?;

    let schema = schema_ident(schedule.source_bounded_context);
    for event in &events {
        match dispatcher.schedule(schedule.name, &event.payload) {
            None => {
                // Defensive only - `schedule.name` came from this same
                // dispatcher's own `schedules()` list.
                tracing::warn!(
                    sequence = event.sequence,
                    "schedule deadline not found in its own dispatcher - skipping"
                );
            }
            Some(Err(e)) => {
                tracing::warn!(
                    sequence = event.sequence,
                    error = %e,
                    "schedule deadline: source payload did not deserialize - skipping"
                );
            }
            Some(Ok(None)) => {
                // `schedule()` itself decided this occurrence doesn't
                // apply - a real, expected outcome, not an error.
            }
            Some(Ok(Some(spec))) => {
                // issue #95 - a recurring spec's own initial
                // `fire_at` must lie inside its own validity window, or
                // the chain would emit a row that is already expired.
                // Skipped with a warning, cursor still advances - a caller
                // bug in `schedule()`, not a condition to retry.
                let out_of_window = match &spec.recurrence {
                    Some(recurrence) => {
                        spec.fire_at
                            < recurrence
                                .start_at
                                .unwrap_or(chrono::DateTime::<Utc>::MIN_UTC)
                            || spec.fire_at
                                > recurrence
                                    .end_at
                                    .unwrap_or(chrono::DateTime::<Utc>::MAX_UTC)
                            || spec.fire_at
                                > recurrence
                                    .valid_until
                                    .unwrap_or(chrono::DateTime::<Utc>::MAX_UTC)
                    }
                    None => false,
                };
                if out_of_window {
                    tracing::warn!(
                        sequence = event.sequence,
                        fire_at = %spec.fire_at,
                        "schedule deadline: initial fire_at outside its own recurrence window - skipping"
                    );
                } else {
                    // Deterministic id - see `ensure_deadlines_table`'s
                    // own doc comment for why `ON CONFLICT (id) DO
                    // NOTHING` makes a redelivered tick a safe no-op.
                    // The first row names itself its own chain parent at
                    // sequence 0; `fire_due_deadlines` derives every later
                    // row's id from those. A one-shot stores no recurrence
                    // columns at all. A bad cron expression degrades to a
                    // one-shot (a warning here, not a refusal) - the chain
                    // simply ends after the first firing.
                    let id = format!("{}:{}", schedule.name, event.sequence);
                    let (recurrence_schedule, recurrence_policy, recurrence_start_at) =
                        match &spec.recurrence {
                            Some(recurrence) => (
                                Some(recurrence.schedule.clone()),
                                Some(recurrence_policy_to_str(recurrence.policy)),
                                recurrence.start_at,
                            ),
                            None => (None, None, None),
                        };
                    let (recurrence_end_at, recurrence_valid_until) = match &spec.recurrence {
                        Some(recurrence) => (recurrence.end_at, recurrence.valid_until),
                        None => (None, None),
                    };
                    sqlx::query(sqlx::AssertSqlSafe(format!(
                        "INSERT INTO {schema}.deadlines \
                         (id, schedule_name, fire_at, expires_at, tags, correlation_id, \
                          target_bounded_context, target_command_type, payload, status, created_at, \
                          recurrence_schedule, recurrence_policy, recurrence_start_at, \
                          recurrence_end_at, recurrence_valid_until, recurrence_parent_id, \
                          recurrence_sequence) \
                         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, 'pending', $10, $11, $12, $13, \
                                 $14, $15, $16, $17) \
                         ON CONFLICT (id) DO NOTHING"
                    )))
                    .bind(&id)
                    .bind(schedule.name)
                    .bind(spec.fire_at)
                    .bind(spec.expires_at)
                    .bind(Json(&spec.tags))
                    .bind(event.metadata.correlation_id.as_deref())
                    .bind(schedule.target_bounded_context)
                    .bind(schedule.target_command_type)
                    .bind(&spec.payload_json)
                    .bind(Utc::now())
                    .bind(recurrence_schedule)
                    .bind(recurrence_policy)
                    .bind(recurrence_start_at)
                    .bind(recurrence_end_at)
                    .bind(recurrence_valid_until)
                    .bind(spec.recurrence.as_ref().map(|_| id.clone()))
                    .bind(spec.recurrence.as_ref().map(|_| 0_i64))
                    .execute(pool)
                    .await?;
                }
            }
        }
        update_deadline_cursor(
            pool,
            schedule.source_bounded_context,
            schedule.name,
            event.sequence,
            Utc::now(),
        )
        .await?;
    }
    Ok(())
}

/// When the first of `cancel`'s source events it hasn't processed yet was
/// created, or `None` when it has processed every one there is
/// (docs/architecture.md §131). A cancel that has never run has processed
/// nothing.
async fn cancel_backlog_start(
    pool: &Pool,
    cancel: &crate::plugin::CancelDeadlineInfo,
) -> crate::error::Result<Option<DateTime<Utc>>> {
    // A cancel whose source bounded context was hard-deleted can never
    // cancel anything again, so there is nothing to wait for. Querying its
    // dropped schema instead failed every fire tick of the bounded context
    // holding the deadlines - none of them fired (docs/architecture.md §133).
    let source_exists: Option<i32> =
        sqlx::query_scalar("SELECT 1 FROM bounded_contexts WHERE name = $1")
            .bind(cancel.source_bounded_context)
            .fetch_optional(pool)
            .await?;
    if source_exists.is_none() {
        return Ok(None);
    }
    let cursor = get_deadline_cursor(pool, cancel.source_bounded_context, cancel.name)
        .await?
        .unwrap_or(-1);
    let schema = schema_ident(cancel.source_bounded_context);
    Ok(sqlx::query_scalar(sqlx::AssertSqlSafe(format!(
        "SELECT metadata_created_at FROM {schema}.events \
         WHERE event_type_name = $1 AND sequence > $2 ORDER BY sequence LIMIT 1"
    )))
    .bind(cancel.source_event_type)
    .bind(cursor)
    .fetch_optional(pool)
    .await?)
}

/// Where a `CancelDeadline`'s schedule still has work: the first of the
/// schedule's source events it hasn't processed. Compared by sequence
/// when the cancelling events share its bounded context - exact, since
/// events become visible in sequence order - and by creation time across
/// bounded contexts, where sequences aren't comparable.
enum ScheduleBacklogStart {
    Sequence(i64),
    Time(DateTime<Utc>),
}

/// The start of `cancel`'s schedule's unprocessed backlog, or `None` when
/// it has processed every source event there is (docs/architecture.md
/// §130). A schedule that has never run has processed nothing.
async fn deadline_schedule_backlog_start(
    pool: &Pool,
    cancel: &crate::plugin::CancelDeadlineInfo,
) -> crate::error::Result<Option<ScheduleBacklogStart>> {
    let cursor = get_deadline_cursor(
        pool,
        cancel.deadline_schedule_bounded_context,
        cancel.deadline_schedule_name,
    )
    .await?
    .unwrap_or(-1);
    let schema = schema_ident(cancel.deadline_schedule_bounded_context);
    let first: Option<(i64, DateTime<Utc>)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT sequence, metadata_created_at FROM {schema}.events \
         WHERE event_type_name = $1 AND sequence > $2 ORDER BY sequence LIMIT 1"
    )))
    .bind(cancel.deadline_schedule_source_event_type)
    .bind(cursor)
    .fetch_optional(pool)
    .await?;
    Ok(first.map(|(sequence, created_at)| {
        if cancel.deadline_schedule_bounded_context == cancel.source_bounded_context {
            ScheduleBacklogStart::Sequence(sequence)
        } else {
            ScheduleBacklogStart::Time(created_at)
        }
    }))
}

/// One registered `CancelDeadline`'s own catch-up tick - same shape as
/// `catch_up_schedule_deadline` just above, reacting by cancelling
/// pending rows instead of inserting one. Writes into
/// `cancel.deadline_schedule_bounded_context`'s own `deadlines` table,
/// which can differ from `cancel.source_bounded_context` - see
/// `CancelDeadlineInfo::deadline_schedule_bounded_context`'s own doc
/// comment.
pub async fn catch_up_cancel_deadline(
    pool: &Pool,
    cancel: &crate::plugin::CancelDeadlineInfo,
    dispatcher: &dyn crate::plugin::CancelDeadlineDispatcher,
    event_cache: &crate::event_cache::EventCache,
) -> crate::error::Result<()> {
    let existing_cursor =
        get_deadline_cursor(pool, cancel.source_bounded_context, cancel.name).await?;
    let cursor = existing_cursor.unwrap_or(-1);
    if existing_cursor.is_none()
        && cancel.start_from != crate::plugin::DeadlinePollStartFrom::Beginning
    {
        // First-ever tick: seed the cursor and dispatch nothing. The
        // seed is one `MAX(sequence)`, not a scan of the loaded history.
        let seed = match cancel.start_from {
            crate::plugin::DeadlinePollStartFrom::Beginning => {
                unreachable!("excluded by this branch's own condition above")
            }
            crate::plugin::DeadlinePollStartFrom::Latest => {
                highest_sequence_of_type(
                    pool,
                    cancel.source_bounded_context,
                    cancel.source_event_type,
                    None,
                )
                .await?
            }
            crate::plugin::DeadlinePollStartFrom::AtSequence(n) => n,
            crate::plugin::DeadlinePollStartFrom::AtTime(unix_secs) => {
                let threshold = DateTime::from_timestamp(unix_secs, 0).unwrap_or(Utc::now());
                highest_sequence_of_type(
                    pool,
                    cancel.source_bounded_context,
                    cancel.source_event_type,
                    Some(threshold),
                )
                .await?
            }
        };
        update_deadline_cursor(
            pool,
            cancel.source_bounded_context,
            cancel.name,
            seed,
            Utc::now(),
        )
        .await?;
        return Ok(());
    }

    // At most `MAX_EVENTS_PER_CATCH_UP_TICK` per tick - the cursor
    // persists per processed event, so the next tick continues exactly
    // where this one stopped, and a long backlog is never loaded whole.
    let events = list_events_cached_limited(
        pool,
        event_cache,
        cancel.source_bounded_context,
        cancel.source_event_type,
        cursor,
        MAX_EVENTS_PER_CATCH_UP_TICK,
    )
    .await?;

    // docs/architecture.md §130: a cancel only applies to deadlines its
    // schedule has already created. The two run independently, so a
    // cancelling event is held back until the schedule has processed
    // every source event that precedes it - otherwise it matches nothing,
    // the deadline is created a moment later, and fires regardless.
    let before = deadline_schedule_backlog_start(pool, cancel).await?;
    let target_schema = schema_ident(cancel.deadline_schedule_bounded_context);
    for event in &events {
        let scheduled_past = match &before {
            None => true,
            Some(ScheduleBacklogStart::Sequence(first_unscheduled)) => {
                event.sequence < *first_unscheduled
            }
            Some(ScheduleBacklogStart::Time(first_unscheduled)) => {
                event.metadata.created_at < *first_unscheduled
            }
        };
        if !scheduled_past {
            // The rest waits for the schedule; the cursor stays on the
            // last event handled, and a later tick resumes from there.
            break;
        }
        match dispatcher.cancel_tags(cancel.name, &event.payload) {
            None => {
                tracing::warn!(
                    sequence = event.sequence,
                    "cancel deadline not found in its own dispatcher - skipping"
                );
            }
            Some(Err(e)) => {
                tracing::warn!(
                    sequence = event.sequence,
                    error = %e,
                    "cancel deadline: source payload did not deserialize - skipping"
                );
            }
            Some(Ok(None)) => {
                // `cancel_tags()` itself decided this occurrence doesn't
                // apply.
            }
            Some(Ok(Some(tags))) if tags.is_empty() => {
                // An empty tag list matches nothing - the identical
                // treatment `list_events_for_bounded_context_matching_tags`'s
                // own early return already gives, applied here rather
                // than running a `WHERE` clause with no tag condition at
                // all (which would match every still-pending row this
                // schedule owns, not none).
            }
            Some(Ok(Some(tags))) => {
                // Tag-containment, one `tags @> $n::jsonb` clause per
                // wanted tag, ORed together - the identical shape
                // `list_events_for_bounded_context_matching_tags` already
                // uses against the `events` table's own `tags` column
                // (docs/architecture.md §19 Problem 1), applied here to
                // `deadlines.tags` instead. Cancels every still-`pending`
                // row this schedule owns that shares at least one of
                // these tags - zero, one, or several rows, all a
                // legitimate outcome (see `CancelDeadline::cancel_tags`'s
                // own doc comment).
                let tag_literals: Vec<String> = tags
                    .iter()
                    .map(|t| {
                        serde_json::to_string(std::slice::from_ref(t))
                            .expect("Tag serialisation is infallible")
                    })
                    .collect();
                let tag_clause = (0..tag_literals.len())
                    .map(|i| format!("tags @> ${}::jsonb", i + 3))
                    .collect::<Vec<_>>()
                    .join(" OR ");
                let mut query = sqlx::query(sqlx::AssertSqlSafe(format!(
                    "UPDATE {target_schema}.deadlines SET status = 'cancelled', resolved_at = $1, \
                     payload = '{{}}' \
                     WHERE schedule_name = $2 AND status = 'pending' AND ({tag_clause})"
                )))
                .bind(Utc::now())
                .bind(cancel.deadline_schedule_name);
                for literal in tag_literals {
                    query = query.bind(literal);
                }
                query.execute(pool).await?;
            }
        }
        update_deadline_cursor(
            pool,
            cancel.source_bounded_context,
            cancel.name,
            event.sequence,
            Utc::now(),
        )
        .await?;
    }
    Ok(())
}

/// `fire_due_deadlines`'s own per-tick cap - the identical "recent
/// window, not a hard limit on correctness" register
/// `scheduler_tick`'s own `MAX_OCCURRENCES_PER_TICK` already is: a
/// backlog bigger than this just takes more ticks to drain, each one
/// picking up wherever the last left off (`fire_at` order, never
/// re-offering an already-`fired`/`cancelled` row).
const MAX_DUE_DEADLINES_PER_TICK: i64 = 1000;

/// How long a claimed (`'firing'`) row is left alone before a future
/// tick is allowed to reclaim it - long enough that a live instance's
/// own `decide_and_submit_command` call (a handful of DB round trips)
/// never comes close, short enough that a genuinely crashed claim (the
/// only way a row is still `'firing'` this long after `firing_at`) gets
/// retried on a human-visible timescale rather than parked forever. The
/// retry itself is safe even if the original attempt actually did
/// commit its command before crashing: `RESERVED_DEADLINE_IDEMPOTENCY_KEY_PREFIX`
/// makes the resubmission a harmless `Deduplicated`, the same
/// defense-in-depth `fire_due_deadlines`'s own doc comment already
/// describes for the fire-vs-fire case this claim mechanism otherwise
/// closes off entirely.
fn deadline_firing_claim_stale_after() -> chrono::Duration {
    chrono::Duration::minutes(5)
}

#[derive(sqlx::FromRow)]
struct DueDeadlineRow {
    id: String,
    schedule_name: String,
    fire_at: DateTime<Utc>,
    expires_at: Option<DateTime<Utc>>,
    tags: Json<Vec<Tag>>,
    correlation_id: Option<String>,
    target_bounded_context: String,
    target_command_type: String,
    payload: String,
    attempt_count: i32,
    first_failed_at: Option<DateTime<Utc>>,
    recurrence_schedule: Option<String>,
    recurrence_policy: Option<String>,
    recurrence_start_at: Option<DateTime<Utc>>,
    recurrence_end_at: Option<DateTime<Utc>>,
    recurrence_valid_until: Option<DateTime<Utc>>,
    recurrence_parent_id: Option<String>,
    recurrence_sequence: Option<i64>,
}

/// issue #95 - one due row's own recurrence state, reconstituted
/// from its columns. `None` for a one-shot (`recurrence_schedule` is
/// `NULL`) or for a row whose stored policy no known writer could have
/// stored (defensive; the `CHECK` constraint already refuses those) - a
/// chain that can't be understood is simply not advanced.
struct Recurrence {
    schedule: String,
    policy: crate::plugin::MissedRunPolicy,
    start_at: Option<DateTime<Utc>>,
    end_at: Option<DateTime<Utc>>,
    valid_until: Option<DateTime<Utc>>,
    parent_id: Option<String>,
    sequence: Option<i64>,
}

impl DueDeadlineRow {
    fn recurrence(&self) -> Option<Recurrence> {
        Some(Recurrence {
            schedule: self.recurrence_schedule.clone()?,
            policy: recurrence_policy_from_str(self.recurrence_policy.as_deref())?,
            start_at: self.recurrence_start_at,
            end_at: self.recurrence_end_at,
            valid_until: self.recurrence_valid_until,
            parent_id: self.recurrence_parent_id.clone(),
            sequence: self.recurrence_sequence,
        })
    }
}

/// A `Deadline`-kind parked row's `source` is this prefix plus the
/// `ScheduleDeadline` that created it; its `identifier` is the deadline's
/// id (docs/architecture.md §115).
pub const DEADLINE_PARKED_SOURCE_PREFIX: &str = "deadline:";

/// The `client_id` every deadline's command is submitted under.
pub const DEADLINE_CLIENT_ID: &str = "deadline";

/// One bounded context's own share of the firing scan - **not** tied to
/// any one registered `ScheduleDeadline`, unlike the two catch-up
/// functions above: it scans `{schema}.deadlines` itself, so a row fires
/// regardless of whether the `ScheduleDeadline` that created it is still
/// registered in this process (the same "every instance does the same
/// redundant, idempotent work" register [docs/architecture.md §22](../../../docs/architecture.md#background-polling-and-startup-scaling)
/// already established.
///
/// No `FOR UPDATE SKIP LOCKED` on the initial `SELECT` - two instances
/// racing to fire the same row both submit under the identical
/// idempotency key, so the second is a harmless `Deduplicated`. But
/// unlike that fire-vs-fire race, a fire-vs-*cancel* race is not
/// harmless: `catch_up_cancel_deadline` can flip this same row to
/// `'cancelled'` concurrently, and if that landed between this
/// function's own `SELECT` and its call to `decide_and_submit_command`,
/// the row would end up recorded `'cancelled'` while the target command
/// had already been submitted - see [docs/architecture.md §55](../../../docs/architecture.md#55-closing-the-canceldeadline-fire-vs-cancel-race).
/// Each row is therefore atomically claimed (`'pending'` -> `'firing'`)
/// immediately before submitting, via the same `UPDATE ... WHERE
/// status = 'pending' RETURNING` shape `mark_deadline_resolved` already
/// uses to make its own write idempotent. `catch_up_cancel_deadline`'s
/// own `UPDATE ... WHERE status = 'pending'` then naturally loses the
/// race once a row is `'firing'` - no change needed there, only a
/// dedicated test proving it (`skilj/tests/deadlines.rs`).
///
/// A due row whose own `target_command_type` isn't registered at all is
/// marked `fired` without ever calling `decide_and_submit_command` -
/// logged as a warning, not retried forever, the identical stance
/// `catch_up_cross_context_route` already takes for its own "target
/// `CommandType` isn't registered" case. No claim needed on that path:
/// no side effect has happened yet, so losing a race with a concurrent
/// cancel there is just ordinary "cancelled before it fired" - the
/// correct outcome, not a bug - so `mark_deadline_resolved` is called
/// directly against the still-`'pending'` row. A `Target` command that
/// *is* submitted but gets rejected by its own `decide()` is marked
/// `fired` too - a legitimate business outcome (`ScheduleDeadline`'s own
/// doc comment), not a reason to retry.
///
/// A submission that fails with an *error* is retried per
/// `retry_policy` - the row goes back to `pending` with `next_attempt_at`
/// set, so a cancel in the meantime still wins - and once the policy is
/// exhausted, parked as a `Deadline`-kind [`ParkedDelivery`] in the
/// target bounded context and marked `parked`, where an operator can
/// retry or discard it like a parked route delivery. Either way the rest
/// of the tick carries on (docs/architecture.md §115).
///
/// issue #95 - a row carrying recurrence state is the head of a
/// chain, and a firing advances it: the next row is inserted *before*
/// this one is marked `fired` (deterministic id, `ON CONFLICT DO
/// NOTHING`), so a crash between the two re-fires idempotently under the
/// same `skilj-deadline:` key and re-inserts the same next row as a
/// no-op - no gap, no duplicate. An `Accepted`, `Rejected` (per-fire
/// business, like a one-shot's) or `Deduplicated` outcome advances the
/// chain; a parked outcome advances it too, so one poisoned occurrence
/// doesn't stall every later one. A retryable error or an
/// `another_instance` defer leaves the row `pending` and begets nothing;
/// an unregistered target, an archived target, an unparseable schedule,
/// or a window the next occurrence falls outside of ends the chain - the
/// row is simply marked `fired`. A pending row already past
/// `valid_until` never submits at all: marked `fired`, nothing begotten.
/// `Cancelled` rows never reach here, so a `CancelDeadline` matching the
/// head ends the chain the same way - nothing further is ever inserted.
#[allow(clippy::too_many_arguments)]
pub async fn fire_due_deadlines(
    pool: &Pool,
    command_dispatcher: &dyn crate::plugin::CommandDispatcher,
    projection_dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    snapshot_dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    broadcaster: &crate::event_store::EventBroadcaster,
    event_cache: &crate::event_cache::EventCache,
    bounded_context: &str,
    now: DateTime<Utc>,
    key_service: Option<&KeyService>,
    retry_policy: &skilj_retry::RetryPolicy,
    cancels: &[crate::plugin::CancelDeadlineInfo],
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    let stale_cutoff = now - deadline_firing_claim_stale_after();
    // docs/architecture.md §131: per cancel that can reach this bounded
    // context's deadlines, when its first unprocessed source event was
    // created - looked up once per tick, on first need.
    let mut cancel_backlogs: std::collections::HashMap<&str, Option<DateTime<Utc>>> =
        std::collections::HashMap::new();
    let rows: Vec<DueDeadlineRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT id, schedule_name, fire_at, expires_at, tags, correlation_id, \
         target_bounded_context, \
         target_command_type, payload, attempt_count, first_failed_at, recurrence_schedule, \
         recurrence_policy, recurrence_start_at, recurrence_end_at, recurrence_valid_until, \
         recurrence_parent_id, recurrence_sequence \
         FROM {schema}.deadlines \
         WHERE (status = 'pending' OR (status = 'firing' AND firing_at <= $1)) AND fire_at <= $2 \
         AND (next_attempt_at IS NULL OR next_attempt_at <= $2) \
         ORDER BY fire_at LIMIT {MAX_DUE_DEADLINES_PER_TICK}"
    )))
    .bind(stale_cutoff)
    .bind(now)
    .fetch_all(pool)
    .await?;

    'rows: for row in rows {
        // docs/architecture.md §131: a deadline only fires once every
        // cancel that can reach it has processed its source events up to
        // the deadline's `fire_at` - one committed before then, but not
        // yet processed by a lagging cancel loop, would otherwise lose to
        // the fire. Held rows stay `pending` for a later tick.
        for cancel in cancels.iter().filter(|c| {
            c.deadline_schedule_bounded_context == bounded_context
                && c.deadline_schedule_name == row.schedule_name
        }) {
            let backlog = match cancel_backlogs.get(cancel.name) {
                Some(backlog) => *backlog,
                None => {
                    let backlog = cancel_backlog_start(pool, cancel).await?;
                    cancel_backlogs.insert(cancel.name, backlog);
                    backlog
                }
            };
            if backlog.is_some_and(|first_unprocessed| first_unprocessed <= row.fire_at) {
                continue 'rows;
            }
        }
        // issue #95 - the chain's kill-switch: a pending row
        // already past its own `valid_until` never submits and begets
        // nothing, marked `fired` like any other chain end. The claim
        // below is skipped deliberately - no side effect has happened, so
        // a concurrent cancel racing this tick is just ordinary
        // "cancelled before it fired", the same register the
        // unregistered-target path already is.
        let recurrence = row.recurrence();
        if recurrence.as_ref().is_some_and(|recurrence| {
            now > recurrence
                .valid_until
                .unwrap_or(chrono::DateTime::<Utc>::MAX_UTC)
        }) {
            mark_deadline_resolved(pool, &schema, &row.id, "fired", now).await?;
            continue;
        }
        let Some(target_command_type) =
            get_command_type(pool, &row.target_bounded_context, &row.target_command_type).await?
        else {
            tracing::warn!(
                deadline_id = %row.id,
                target_bounded_context = %row.target_bounded_context,
                target_command_type = %row.target_command_type,
                "deadline's own target CommandType isn't registered - marking fired without submitting"
            );
            mark_deadline_resolved(pool, &schema, &row.id, "fired", now).await?;
            continue;
        };
        // docs/architecture.md §96: an archived target refuses the command
        // (`process_command`), and would keep refusing it - left as an
        // error, the claim would go stale and be retried every few minutes
        // forever. Resolved the same way as an unregistered target.
        if target_command_type.bounded_context.status
            != crate::event_store::BoundedContextStatus::Active
        {
            tracing::warn!(
                deadline_id = %row.id,
                target_bounded_context = %row.target_bounded_context,
                target_command_type = %row.target_command_type,
                "deadline's own target bounded context is archived - marking fired without submitting"
            );
            mark_deadline_resolved(pool, &schema, &row.id, "fired", now).await?;
            continue;
        }
        // Claims a `'pending'` row outright, or reclaims a `'firing'` one
        // whose own `firing_at` is already past `stale_cutoff` - the
        // identical condition the `SELECT` above already filtered on,
        // re-checked here under the `UPDATE`'s own row lock so a second
        // instance racing to reclaim the same stale row always loses
        // (Postgres re-evaluates `WHERE` against the just-committed row
        // once the first `UPDATE` releases it, and by then `firing_at`
        // is `now`, no longer `<= stale_cutoff`).
        let claimed: Option<(String,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "UPDATE {schema}.deadlines SET status = 'firing', firing_at = $1 \
             WHERE id = $2 AND (status = 'pending' OR (status = 'firing' AND firing_at <= $3)) \
             AND (next_attempt_at IS NULL OR next_attempt_at <= $1) \
             RETURNING id"
        )))
        .bind(now)
        .bind(&row.id)
        .bind(stale_cutoff)
        .fetch_optional(pool)
        .await?;
        if claimed.is_none() {
            // Lost the claim to a concurrent cancel, or to a concurrent
            // instance's own fire/reclaim attempt on the same row -
            // either way, correct to skip: this instance must not submit
            // the target command.
            continue;
        }
        // Prefixed with `RESERVED_DEADLINE_IDEMPOTENCY_KEY_PREFIX` - see
        // that constant's own doc comment for why this is
        // defense-in-depth, not load-bearing, now that `idempotency_keys`
        // is `client_id`-scoped and this call's own `client_id` below
        // ("deadline") is never externally suppliable.
        let idempotency_key = format!(
            "{}{}",
            crate::event_store::RESERVED_DEADLINE_IDEMPOTENCY_KEY_PREFIX,
            row.id
        );
        // issue #18: carries the scheduling event's own
        // correlation_id forward (stored on the row at schedule time) -
        // no `causation_id` of its own, since there's no `Event` this
        // firing directly descends from the way a `CrossContextRoute`'s
        // own submission descends from the `Source` event that triggered
        // it (`event_causation_id`); a fired deadline's real cause is a
        // clock, not a prior commit.
        // issue #97: the target's `decide_with` gets the deadline
        // this command descends from - when it was scheduled to fire
        // (`fire_at`), its optional `expires_at`, and whether this firing
        // is past it - so it can refuse an action it fired too late for.
        let deadline_context =
            crate::plugin::DeadlineContext::new(row.fire_at, row.expires_at, now);
        // issue #98: an approval-required target becomes a
        // proposal, never a direct submission - otherwise whoever can cause
        // the scheduling event bypasses the approver. `Ok(None)` is
        // "proposed"; errors take the same retry/park path as a failed
        // submission.
        let outcome = match propose_if_approval_required(
            pool,
            &target_command_type,
            &row.payload,
            DEADLINE_CLIENT_ID,
            row.correlation_id.as_deref(),
            None,
            &idempotency_key,
            key_service,
            now,
        )
        .await
        {
            Ok(true) => Ok(None),
            Ok(false) => decide_and_submit_command(
                pool,
                command_dispatcher,
                projection_dispatcher,
                snapshot_dispatcher,
                broadcaster,
                event_cache,
                &target_command_type,
                &row.payload,
                DEADLINE_CLIENT_ID,
                row.correlation_id.as_deref(),
                None,
                key_service,
                now,
                Some(&idempotency_key),
                Some(deadline_context),
            )
            .await
            .map(Some),
            Err(e) => Err(e),
        };
        let outcome = match outcome {
            Ok(outcome) => outcome,
            Err(e) if e.another_instance_can_do_it() => {
                defer_deadline_to_another_instance(pool, &schema, &row, &e, now).await?;
                continue;
            }
            Err(e) => {
                record_deadline_failure(pool, &schema, &row, &e, retry_policy, now).await?;
                let parked: Option<(String,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
                    "SELECT id FROM {schema}.deadlines WHERE id = $1 AND status = 'parked'"
                )))
                .bind(&row.id)
                .fetch_optional(pool)
                .await?;
                if parked.is_some() {
                    advance_deadline_chain(pool, &schema, &row, recurrence.as_ref(), now).await?;
                }
                continue;
            }
        };
        if matches!(outcome, Some(SubmitCommandOutcome::Deduplicated { .. })) {
            tracing::warn!(
                deadline_id = %row.id,
                "deadline's own idempotency key was already present - expected after a \
                 crash/restart between a prior fire attempt and marking it resolved; \
                 unexpected otherwise, since the key space is reserved"
            );
        }
        // issue #95 - the next row lands before this one is
        // marked `fired`, so a crash between the two re-fires idempotently
        // and re-inserts the same next id as a no-op.
        advance_deadline_chain(pool, &schema, &row, recurrence.as_ref(), now).await?;
        mark_deadline_resolved(pool, &schema, &row.id, "fired", now).await?;
    }
    Ok(())
}

/// issue #95 - advances one recurring chain past the firing of
/// `row`: derives the next `fire_at` from the recurrence math and inserts
/// the next pending row (deterministic id, `ON CONFLICT DO NOTHING`),
/// carrying the chain's tags, payload, correlation, target and recurrence
/// state forward. A `None` derivation ends the chain silently - warned
/// once only for an unparseable schedule, since a windowed end is the
/// ordinary, expected way a chain stops. The sequence counts up from the
/// parent's 0, so ids (`"{parent_id}#r{sequence}"`) can never collide with
/// the parent's own `"{schedule}:{sequence}"` shape or with each other.
async fn advance_deadline_chain(
    pool: &Pool,
    schema: &str,
    row: &DueDeadlineRow,
    recurrence: Option<&Recurrence>,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    let Some(recurrence) = recurrence else {
        return Ok(());
    };
    let Some(next_fire_at) = crate::plugin::next_recurrence_fire_at(
        &crate::plugin::RecurrenceSpec {
            schedule: recurrence.schedule.clone(),
            policy: recurrence.policy,
            start_at: recurrence.start_at,
            end_at: recurrence.end_at,
            valid_until: recurrence.valid_until,
        },
        row.fire_at,
        now,
    ) else {
        if crate::event_store::next_occurrence_after(&recurrence.schedule, row.fire_at).is_none()
            && crate::event_store::latest_occurrence_at_or_before(&recurrence.schedule, now)
                .is_none()
        {
            tracing::warn!(
                deadline_id = %row.id,
                schedule = %recurrence.schedule,
                "deadline's own recurrence schedule does not parse - ending the chain"
            );
        }
        return Ok(());
    };
    let parent_id = recurrence.parent_id.as_deref().unwrap_or(&row.id);
    let next_sequence = recurrence
        .sequence
        .map(|sequence| sequence + 1)
        .unwrap_or(1);
    let next_id = format!("{parent_id}#r{next_sequence}");
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.deadlines \
         (id, schedule_name, fire_at, expires_at, tags, correlation_id, target_bounded_context, \
          target_command_type, payload, status, created_at, recurrence_schedule, \
          recurrence_policy, recurrence_start_at, recurrence_end_at, \
          recurrence_valid_until, recurrence_parent_id, recurrence_sequence) \
         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, 'pending', $10, $11, $12, $13, $14, \
                 $15, $16, $17) \
         ON CONFLICT (id) DO NOTHING"
    )))
    .bind(&next_id)
    .bind(&row.schedule_name)
    .bind(next_fire_at)
    .bind(row.expires_at)
    .bind(&row.tags)
    .bind(row.correlation_id.as_deref())
    .bind(&row.target_bounded_context)
    .bind(&row.target_command_type)
    .bind(&row.payload)
    .bind(now)
    .bind(&recurrence.schedule)
    .bind(recurrence_policy_to_str(recurrence.policy))
    .bind(recurrence.start_at)
    .bind(recurrence.end_at)
    .bind(recurrence.valid_until)
    .bind(parent_id)
    .bind(next_sequence)
    .execute(pool)
    .await?;
    Ok(())
}

/// `WHERE status IN ('pending', 'firing')` - called both directly
/// against a still-`'pending'` row (the "target `CommandType` isn't
/// registered" path, no claim taken) and against a row this same tick
/// already claimed into `'firing'` (the normal fire path) - either way
/// idempotent: a status that's already terminal (`'fired'`/`'cancelled'`)
/// never matches, so a redelivered/duplicate call is a safe no-op.
/// A deadline whose command submission failed with an error: back to
/// `pending` until its next attempt, or - once `retry_policy` is
/// exhausted - parked in the target bounded context and marked `parked`
/// (docs/architecture.md §115). Only this instance's own claim is
/// updated (`status = 'firing'`): a reclaim racing it leaves it alone.
/// How long work this instance can't do, but another can
/// ([`crate::error::Error::another_instance_can_do_it`]), waits before
/// being tried again - by whichever instance claims it then
/// (docs/architecture.md §161).
pub const ANOTHER_INSTANCE_RETRY_DELAY: std::time::Duration =
    skilj_retry::ANOTHER_INSTANCE_RETRY_DELAY;

/// Releases a claimed deadline this instance can't fire, for another
/// instance to take after [`ANOTHER_INSTANCE_RETRY_DELAY`]. Unlike
/// [`record_deadline_failure`] it spends no attempt and never parks.
async fn defer_deadline_to_another_instance(
    pool: &Pool,
    schema: &str,
    row: &DueDeadlineRow,
    error: &crate::error::Error,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    let next_attempt_at = now
        + chrono::Duration::from_std(ANOTHER_INSTANCE_RETRY_DELAY)
            .expect("a ten-second delay fits a chrono::Duration");
    tracing::warn!(
        deadline_id = %row.id,
        error = %error,
        next_attempt_at = %next_attempt_at,
        "deadline: this instance can't fire it, another can - retrying later"
    );
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.deadlines SET status = 'pending', firing_at = NULL, \
         next_attempt_at = $1 WHERE id = $2 AND status = 'firing'"
    )))
    .bind(next_attempt_at)
    .bind(&row.id)
    .execute(pool)
    .await?;
    Ok(())
}

async fn record_deadline_failure(
    pool: &Pool,
    schema: &str,
    row: &DueDeadlineRow,
    error: &crate::error::Error,
    retry_policy: &skilj_retry::RetryPolicy,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    let attempt_count = row.attempt_count + 1;
    let first_failed_at = row.first_failed_at.unwrap_or(now);
    let elapsed = (now - first_failed_at).to_std().unwrap_or_default();
    let message = error.to_string();
    if retry_policy.is_exhausted(attempt_count as u32, elapsed) {
        tracing::error!(
            deadline_id = %row.id,
            error = %message,
            attempt = attempt_count,
            "deadline: target command submission failed repeatedly - parking it"
        );
        let request_json = serde_json::from_str(&row.payload)
            .unwrap_or_else(|_| serde_json::Value::String(row.payload.clone()));
        insert_parked_delivery(
            pool,
            &row.target_bounded_context,
            &format!("{DEADLINE_PARKED_SOURCE_PREFIX}{}", row.schedule_name),
            ParkedDeliveryKind::Deadline,
            &row.id,
            None,
            Some(&row.target_bounded_context),
            Some(&row.target_command_type),
            &request_json,
            &message,
            attempt_count,
            first_failed_at,
            now,
        )
        .await?;
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "UPDATE {schema}.deadlines SET status = 'parked', resolved_at = $1, \
             attempt_count = $2, last_error = $3, payload = '{{}}' \
             WHERE id = $4 AND status = 'firing'"
        )))
        .bind(now)
        .bind(attempt_count)
        .bind(&message)
        .bind(&row.id)
        .execute(pool)
        .await?;
        return Ok(());
    }
    let next_attempt_at = retry_policy.next_attempt_at(now, attempt_count as u32);
    tracing::warn!(
        deadline_id = %row.id,
        error = %message,
        attempt = attempt_count,
        next_attempt_at = %next_attempt_at,
        "deadline: target command submission failed - will retry"
    );
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.deadlines SET status = 'pending', firing_at = NULL, \
         attempt_count = $1, first_failed_at = $2, next_attempt_at = $3, last_error = $4 \
         WHERE id = $5 AND status = 'firing'"
    )))
    .bind(attempt_count)
    .bind(first_failed_at)
    .bind(next_attempt_at)
    .bind(&message)
    .bind(&row.id)
    .execute(pool)
    .await?;
    Ok(())
}

async fn mark_deadline_resolved(
    pool: &Pool,
    schema: &str,
    id: &str,
    status: &str,
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.deadlines SET status = $1, resolved_at = $2, payload = '{{}}' \
         WHERE id = $3 AND status IN ('pending', 'firing')"
    )))
    .bind(status)
    .bind(now)
    .bind(id)
    .execute(pool)
    .await?;
    Ok(())
}

/// A hit returns the stored `triggered_event_sequences` from a prior
/// `Accepted` outcome for this exact `(command_type_name, client_id,
/// idempotency_key)` triple - `submit_command`'s own short-circuit. Must
/// only be called after the bounded context's own `sequence` row lock
/// is already held (see `submit_command`'s own doc comment) - that lock
/// is what makes this plain, unlocked `SELECT` race-free, the same way
/// it already makes the DCB-conflict recheck a few lines below it
/// race-free.
///
/// Whether this `(command type, client, key)` already produced an
/// accepted command. Approval-required submissions check this *before*
/// creating a proposal: once an approver accepted a proposal submitted
/// with a caller key, a duplicate submission must short-circuit to the
/// ordinary dedup path rather than proposing the same command again.
pub async fn idempotency_key_already_used(
    pool: &Pool,
    bounded_context: &str,
    command_type_name: &str,
    client_id: &str,
    idempotency_key: &str,
) -> crate::error::Result<bool> {
    let schema = schema_ident(bounded_context);
    Ok(
        lookup_idempotency_key(pool, &schema, command_type_name, client_id, idempotency_key)
            .await?
            .is_some(),
    )
}

/// A real `client_id`-only match, never a `client_id = ''` legacy row -
/// see `migrate_idempotency_keys_client_id_scoping`'s own doc comment
/// for why a pre-migration row is deliberately left permanently
/// unmatchable rather than kept as a fallback: the user's own explicit
/// call, choosing to fully close the cross-tenant collision this whole
/// fix exists for over preserving those specific rows' dedup power.
async fn lookup_idempotency_key<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    schema: &str,
    command_type_name: &str,
    client_id: &str,
    idempotency_key: &str,
) -> crate::error::Result<Option<Vec<i64>>> {
    let row: Option<(Vec<i64>,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT triggered_event_sequences FROM {schema}.idempotency_keys \
         WHERE command_type_name = $1 AND client_id = $2 AND idempotency_key = $3"
    )))
    .bind(command_type_name)
    .bind(client_id)
    .bind(idempotency_key)
    .fetch_optional(executor)
    .await?;
    Ok(row.map(|(sequences,)| sequences))
}

/// Records a real `Accepted` outcome against its idempotency key, inside
/// the same transaction as the `Command`/`Event` rows it describes - a
/// later duplicate submission bearing this key from this same
/// `client_id` short-circuits to `triggered_event_sequences` via
/// `lookup_idempotency_key` instead of being re-decided. No `ON
/// CONFLICT` - the sequence row lock already rules out a concurrent
/// duplicate reaching here (`lookup_idempotency_key` would already have
/// caught it); a real conflict here would mean a bug in that check,
/// worth surfacing as a hard error rather than silently swallowing.
async fn insert_idempotency_key<'e>(
    executor: impl sqlx::PgExecutor<'e>,
    schema: &str,
    command_type_name: &str,
    client_id: &str,
    idempotency_key: &str,
    triggered_event_sequences: &[i64],
    now: DateTime<Utc>,
) -> crate::error::Result<()> {
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.idempotency_keys \
         (command_type_name, client_id, idempotency_key, triggered_event_sequences, created_at) \
         VALUES ($1, $2, $3, $4, $5)"
    )))
    .bind(command_type_name)
    .bind(client_id)
    .bind(idempotency_key)
    .bind(triggered_event_sequences)
    .bind(now)
    .execute(executor)
    .await?;
    Ok(())
}

/// issue #15: the batched replacement for looping every
/// registered projection through `get_projection_rebuild` - that path
/// cost up to `~2P` queries per tick for `P` projections even when
/// nothing was building (`get_projection_rebuild` alone is 3 queries:
/// `get_projection`, the rebuild row, `rebuild_consumed_event_types` -
/// and that last one has its own inner N+1, one `get_event_type` call
/// per consumed event type name). This does the same job in a small
/// constant number of queries regardless of `P` or how many rebuilds
/// are actually building: one query for every `building` row in the
/// bc's `projection_rebuilds` table, one for every row in
/// `projection_rebuild_consumed_event_types` (grouped by
/// `projection_name` in memory), one for every `EventType` in the bc
/// (`list_event_types_for_bounded_context`, already a single query),
/// and zero further queries for the live `Projection` each rebuild
/// belongs to - `all_projections` is data the caller
/// (`catch_up_bounded_context`) already fetched, handed in here instead
/// of re-fetched via `get_project` per row the way `get_projection_rebuild`
/// does for its own single-row callers (`RebuildProjection`/
/// `DiscardProjectionRebuild`'s resolvers - untouched, a single lookup
/// is the right shape there).
async fn list_building_projection_rebuilds_for_bounded_context(
    pool: &Pool,
    bounded_context: &str,
    all_projections: &[Projection],
) -> crate::error::Result<Vec<ProjectionRebuild>> {
    let schema = schema_ident(bounded_context);

    let rebuild_rows: Vec<ProjectionRebuildRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {PROJECTION_REBUILD_COLUMNS} FROM {schema}.projection_rebuilds \
         WHERE status = 'building'"
    )))
    .fetch_all(pool)
    .await?;
    if rebuild_rows.is_empty() {
        return Ok(Vec::new());
    }

    let consumed_rows: Vec<(String, String)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT projection_name, event_type_name \
         FROM {schema}.projection_rebuild_consumed_event_types WHERE status = 'building'"
    )))
    .fetch_all(pool)
    .await?;
    let mut consumed_by_projection: std::collections::HashMap<String, Vec<String>> =
        std::collections::HashMap::new();
    for (projection_name, event_type_name) in consumed_rows {
        consumed_by_projection
            .entry(projection_name)
            .or_default()
            .push(event_type_name);
    }

    let all_event_types = list_event_types_for_bounded_context(pool, bounded_context).await?;
    let event_types_by_name: std::collections::HashMap<&str, &EventType> = all_event_types
        .iter()
        .map(|et| (et.name.as_str(), et))
        .collect();

    let projections_by_name: std::collections::HashMap<&str, &Projection> = all_projections
        .iter()
        .map(|p| (p.name.as_str(), p))
        .collect();

    let mut rebuilds = Vec::with_capacity(rebuild_rows.len());
    for row in rebuild_rows {
        let Some(projection) = projections_by_name.get(row.projection_name.as_str()) else {
            continue;
        };
        let consumed_event_types = consumed_by_projection
            .remove(&row.projection_name)
            .unwrap_or_default()
            .into_iter()
            .map(|name| {
                event_types_by_name
                    .get(name.as_str())
                    .copied()
                    .cloned()
                    .expect(
                        "projection_rebuild_consumed_event_types join row references an \
                         event_types row that no longer exists",
                    )
            })
            .collect();
        rebuilds.push(ProjectionRebuild {
            projection: (*projection).clone(),
            schema: row.schema,
            schema_version: row.schema_version,
            consumed_event_types,
            sync: row.sync,
            caught_up_to: row.caught_up_to,
            status: projection_rebuild_status_from_str(&row.status),
        });
    }
    Ok(rebuilds)
}

/// The background half of [§8](../../../docs/architecture.md#open-for-a-future-pass) item 6: one poll tick, for one bounded
/// context - folds every committed event not yet reflected in that
/// context's `sync = false` `Projection`s, and separately walks any
/// `building` `ProjectionRebuild`s toward completion, promoting each one
/// automatically once it catches up to the same high-water mark. Called
/// in a loop, on a timer, by the single shared background task
/// `SkiljBuilder::build()` spawns - see that function's own doc comment
/// for why one shared task rather than one per bounded context.
///
/// Uses the `-1` "nothing yet" sentinel `next_sequence`'s own `sequence`
/// row is seeded with throughout, rather than threading `Option<i64>`
/// through every comparison - `caught_up_to.unwrap_or(-1)` and
/// `latest_sequence(...).unwrap_or(-1)` compare directly, and a
/// building rebuild in a bounded context with no events at all (`latest
/// = -1`) is then trivially already caught up (`caught_up_to.unwrap_or(-1)
/// == -1`) and promotes immediately, with no separate "nothing committed
/// yet" special case needed.
///
/// A rebuild whose `caught_up_to` is `None` - freshly staged, or
/// restarted while `building` (a `rebuildProjection` arriving mid-build,
/// see `transition_projection_rebuild_to_building`) - has its
/// `projection_rebuild_state` rows deleted in the transaction that folds
/// its first event, under the rebuild row's lock: `ProjectionDispatcher::
/// default_state` resolved fresh, right before the first event actually
/// gets folded, is the only correct starting point once that reset has
/// happened; a row left over from a build attempt this same reset just
/// invalidated would otherwise be silently reused as if it were still
/// current. Each fold re-reads the rebuild's `caught_up_to` under that
/// lock and goes ahead only if it's exactly the previous event's
/// sequence, so an instance working from a stale snapshot never folds a
/// restarted rebuild, and never deletes what another instance just folded
/// (docs/architecture.md §151). A rebuild
/// this dispatcher can't resolve at all (no compiled type registered in
/// this process for that name) still advances - `state` frozen at `"{}"`,
/// a neutral placeholder never actually deserialised by anything, since
/// `dispatcher.project()` returns `None` for the same lookup key
/// `default_state()` did - the same "position always advances, state
/// only changes when the dispatcher can" treatment sync projections
/// already get from `insert_event_and_update_sync_projections` above.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn catch_up_bounded_context(
    pool: &Pool,
    bounded_context: &str,
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    let latest = latest_sequence(pool, bounded_context).await?.unwrap_or(-1);

    // docs/architecture.md §160: only the projections this instance's
    // dispatcher knows. One it doesn't - declared by a newer version
    // during a rolling deploy, or no longer declared at all - has no keys
    // and no fold here, and walking it anyway advanced its `caught_up_to`
    // past events nothing folded. It's left to an instance that knows it.
    let all_projections: Vec<Projection> =
        list_projections_for_bounded_context(pool, bounded_context)
            .await?
            .into_iter()
            .filter(|p| dispatcher.default_state(bounded_context, &p.name).is_some())
            .collect();
    // issue #25 (docs/architecture.md §51) - every async
    // projection is split here by its own `Projection::PARTITION_COUNT`
    // (via the dispatcher, since that's a Rust-only config the domain
    // `Projection` struct itself never carries). `unpartitioned_async_projections`
    // (`<= 1`, the default, and every projection that predates this
    // feature) feeds the exact same loop this function has always had,
    // completely unchanged below - order is kept simply by never
    // entering the new code path. `.max(1)` guards a misconfigured
    // `PARTITION_COUNT = 0` against a later divide-by-zero.
    let unpartitioned_async_projections: Vec<_> = all_projections
        .iter()
        .filter(|p| {
            !p.sync
                && dispatcher
                    .partition_count(bounded_context, &p.name)
                    .unwrap_or(1)
                    .max(1)
                    <= 1
        })
        .collect();
    let partitioned_async_projections: Vec<(&Projection, u32)> = all_projections
        .iter()
        .filter(|p| !p.sync)
        .filter_map(|p| {
            let partition_count = dispatcher
                .partition_count(bounded_context, &p.name)
                .unwrap_or(1)
                .max(1);
            (partition_count > 1).then_some((p, partition_count))
        })
        .collect();
    let building_rebuilds = list_building_projection_rebuilds_for_bounded_context(
        pool,
        bounded_context,
        &all_projections,
    )
    .await?;

    if unpartitioned_async_projections.is_empty()
        && partitioned_async_projections.is_empty()
        && building_rebuilds.is_empty()
    {
        return Ok(());
    }

    let min_caught_up = unpartitioned_async_projections
        .iter()
        .map(|p| p.caught_up_to.unwrap_or(-1))
        .chain(
            building_rebuilds
                .iter()
                .map(|r| r.caught_up_to.unwrap_or(-1)),
        )
        .min()
        .unwrap_or(latest);

    let events = if min_caught_up >= latest {
        Vec::new()
    } else {
        // At most `MAX_EVENTS_PER_CATCH_UP_TICK`: progress persists per
        // event, so a new projection/rebuild/snapshot over a long history
        // catches up over several ticks instead of loading it whole.
        list_events_for_bounded_context_from_limited(
            pool,
            bounded_context,
            min_caught_up,
            MAX_EVENTS_PER_CATCH_UP_TICK,
        )
        .await?
    };

    // The sequence of the bounded context's event just before the chunk
    // being folded: `events` is every event after `min_caught_up`, in
    // order, so a rebuild may fold an event only if it has processed
    // exactly up to the one before it (docs/architecture.md §151). A chunk
    // of events per transaction, not one (§182).
    let mut previous = min_caught_up;
    for chunk in events.chunks(CATCH_UP_EVENTS_PER_TRANSACTION) {
        let folded = fold_catch_up_chunk(
            pool,
            bounded_context,
            &schema,
            dispatcher,
            &unpartitioned_async_projections,
            &building_rebuilds,
            chunk,
            previous,
        )
        .await;
        if let Err(failure) = folded {
            // A failing event doesn't take the events before it in its
            // chunk down with it: those commit on their own, as they did
            // with one transaction per event, and the error is returned.
            // The failure blamed is not always the earliest: a shorter
            // run can fail again earlier, and is then shortened to that
            // (docs/architecture.md §200).
            let mut end = failure.folded_before;
            while end > 0 {
                match fold_catch_up_chunk(
                    pool,
                    bounded_context,
                    &schema,
                    dispatcher,
                    &unpartitioned_async_projections,
                    &building_rebuilds,
                    &chunk[..end],
                    previous,
                )
                .await
                {
                    Ok(()) => break,
                    Err(retry) if retry.folded_before < end => end = retry.folded_before,
                    Err(retry) => return Err(retry.error),
                }
            }
            return Err(failure.error);
        }
        previous = chunk.last().expect("chunks are never empty").sequence;
    }

    for rebuild in &building_rebuilds {
        // It can have vanished since the fold loop above: another
        // instance's overlapping tick may have promoted it (deleting the
        // building row), or a `hard_delete_bounded_context` may have
        // landed. Either way there's nothing left to promote - and a panic
        // here would take down the one background task every bounded
        // context's catch-up runs on, not just this tick.
        let Some(current) = get_projection_rebuild(
            pool,
            bounded_context,
            &rebuild.projection.name,
            ProjectionRebuildStatus::Building,
        )
        .await?
        else {
            continue;
        };
        if current.caught_up_to.unwrap_or(-1) == latest {
            // A cheap fast-path filter, not the authoritative check
            // anymore (drift audit finding #6) - `promote_projection_rebuild`
            // re-verifies for real under its own lock, so a `false`
            // return here is an expected, self-correcting outcome (a new
            // event landed in the gap between this snapshot and that
            // lock) rather than something this caller needs to react to;
            // the next tick retries.
            let _ =
                promote_projection_rebuild(pool, bounded_context, &rebuild.projection.name).await?;
        }
    }

    // issue #25 (docs/architecture.md §51) - sequential across
    // partitioned projections, not `for_each_concurrent`: the real
    // scale-out value comes from separate *instances* racing for
    // partitions, not from one instance's own intra-tick fan-out, and
    // stacking more concurrency here on top of this function's own
    // already-concurrent per-bounded-context caller
    // (`BACKGROUND_TASK_CONCURRENCY` in `skilj/src/lib.rs`) against a
    // pool whose default cap is modest (docs/architecture.md §35) risks
    // exhausting it for little gain.
    for (projection, partition_count) in partitioned_async_projections {
        catch_up_partitioned_projection(
            pool,
            bounded_context,
            &schema,
            dispatcher,
            projection,
            partition_count,
            latest,
        )
        .await?;
    }

    Ok(())
}

/// How many events `catch_up_bounded_context` folds per transaction
/// (docs/architecture.md §182). One per event paid, per event, a commit,
/// a lock and re-read of every projection row, and a read and a write of
/// every key it touched; a chunk pays them once, with each projection's
/// keys read and written in one statement. Bounded because the chunk's
/// transaction holds each folded projection's row lock throughout, which
/// a registration or promotion of that projection waits on.
const CATCH_UP_EVENTS_PER_TRANSACTION: usize = 100;

/// Why [`fold_catch_up_chunk`] failed, and how many of the chunk's events
/// came before the one it failed on - `0` when the failure isn't one
/// event's (the transaction itself, or reading or writing the chunk's
/// rows).
struct CatchUpChunkFailure {
    folded_before: usize,
    error: crate::error::Error,
}

/// One key's state while a chunk is folded: read and locked before the
/// chunk's events are folded into it, written back once after.
struct CatchUpChunkState {
    as_of_sequence: i64,
    state: String,
    owner: Option<String>,
    folded: bool,
}

/// One projection or `building` rebuild a chunk folds into.
struct CatchUpChunkTarget<'a> {
    name: &'a str,
    rebuild: bool,
    /// `caught_up_to` as read under the row's lock.
    locked: Option<i64>,
    /// `caught_up_to` once the chunk is folded.
    position: Option<i64>,
    /// Every key the chunk's events touch, in the order first touched.
    keys: Vec<String>,
    states: std::collections::HashMap<String, CatchUpChunkState>,
}

/// Folds `events` - a contiguous run of the bounded context's events,
/// the first one right after `previous` - into the unpartitioned async
/// `projections` and the `building` `rebuilds`, in one transaction.
/// Exactly what folding them one transaction per event did, only
/// committed together: every check the per-event loop made against a
/// re-read row is made once, under that row's lock, which the transaction
/// then holds to the end - so it can't change in between.
///
/// Locks are taken in the order the per-event loop took them and
/// promotion takes them (docs/architecture.md §156): every projection row
/// first, then every rebuild row, each by name so two instances' chunks
/// can't take two of them in opposite orders, then their state rows.
///
/// `FOR NO KEY UPDATE`, not `FOR UPDATE` (docs/architecture.md §195): it
/// still excludes another chunk and a promotion, but not the `KEY SHARE`
/// a sync projection's state insert takes on its projection row through
/// the foreign key. A row the caller saw as async may have turned sync
/// by the time it is locked, and a `FOR UPDATE` kept on it to the end of
/// the chunk stalled every write folding into it, under the sequence
/// lock. Promotion doesn't wait for a chunk either; see
/// [`promote_projection_rebuild`].
#[allow(clippy::too_many_arguments)]
async fn fold_catch_up_chunk(
    pool: &Pool,
    bounded_context: &str,
    schema: &str,
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    projections: &[&Projection],
    rebuilds: &[ProjectionRebuild],
    events: &[Event],
    previous: i64,
) -> Result<(), CatchUpChunkFailure> {
    let mut reached = 0;
    fold_catch_up_chunk_in_tx(
        pool,
        bounded_context,
        schema,
        dispatcher,
        projections,
        rebuilds,
        events,
        previous,
        &mut reached,
    )
    .await
    .map_err(|error| CatchUpChunkFailure {
        folded_before: reached,
        error,
    })
}

/// [`fold_catch_up_chunk`]'s body - `reached` is the index of the event
/// being folded, `0` outside the fold itself.
#[allow(clippy::too_many_arguments)]
async fn fold_catch_up_chunk_in_tx(
    pool: &Pool,
    bounded_context: &str,
    schema: &str,
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    projections: &[&Projection],
    rebuilds: &[ProjectionRebuild],
    events: &[Event],
    previous: i64,
    reached: &mut usize,
) -> crate::error::Result<()> {
    let Some(chunk_end) = events.last().map(|event| event.sequence) else {
        return Ok(());
    };
    let mut tx = pool.begin().await?;
    let mut targets: Vec<CatchUpChunkTarget> = Vec::new();

    // Re-read under the lock, a projection already past the chunk, turned
    // sync or gone since the caller's snapshot is left alone.
    let mut candidates: Vec<&Projection> = projections
        .iter()
        .copied()
        .filter(|p| p.caught_up_to.unwrap_or(-1) < chunk_end)
        .collect();
    candidates.sort_by(|a, b| a.name.cmp(&b.name));
    for projection in candidates {
        let current: Option<(Option<i64>, bool)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "SELECT caught_up_to, sync FROM {schema}.projections WHERE name = $1 \
             FOR NO KEY UPDATE"
        )))
        .bind(&projection.name)
        .fetch_optional(&mut *tx)
        .await?;
        if let Some((caught_up_to, false)) = current {
            targets.push(CatchUpChunkTarget {
                name: &projection.name,
                rebuild: false,
                locked: caught_up_to,
                position: caught_up_to,
                keys: Vec::new(),
                states: std::collections::HashMap::new(),
            });
        }
    }

    // docs/architecture.md §151: a rebuild promoted, gone or restarted
    // since the caller's snapshot is seen here, under its lock.
    let mut candidates: Vec<&ProjectionRebuild> = rebuilds
        .iter()
        .filter(|r| r.caught_up_to.unwrap_or(-1) < chunk_end)
        .collect();
    candidates.sort_by(|a, b| a.projection.name.cmp(&b.projection.name));
    for rebuild in candidates {
        let current: Option<(Option<i64>,)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "SELECT caught_up_to FROM {schema}.projection_rebuilds \
             WHERE projection_name = $1 AND status = 'building' FOR NO KEY UPDATE"
        )))
        .bind(&rebuild.projection.name)
        .fetch_optional(&mut *tx)
        .await?;
        if let Some((caught_up_to,)) = current {
            targets.push(CatchUpChunkTarget {
                name: &rebuild.projection.name,
                rebuild: true,
                locked: caught_up_to,
                position: caught_up_to,
                keys: Vec::new(),
                states: std::collections::HashMap::new(),
            });
        }
    }

    // Which target folds which event, and with which keys, in the order
    // the per-event loop folded them. A live projection folds every event
    // past its position; a rebuild only an event right after what it has
    // processed (§151) - and from then on every one, since it then has.
    let mut planned: Vec<(usize, usize, Vec<String>)> = Vec::new();
    let mut seen: Vec<std::collections::HashSet<String>> =
        vec![std::collections::HashSet::new(); targets.len()];
    let mut before = previous;
    for (index, event) in events.iter().enumerate() {
        for (slot, target) in targets.iter_mut().enumerate() {
            let folds = if target.rebuild {
                target.position.unwrap_or(-1) == before
            } else {
                target.position.unwrap_or(-1) < event.sequence
            };
            if !folds {
                continue;
            }
            // `Some(vec![])`/`None` both mean zero instances touched -
            // see `insert_event_and_update_sync_projections`'s own
            // identical comment.
            let keys = dispatcher
                .keys(bounded_context, target.name, event)
                .unwrap_or_default();
            for key in &keys {
                if seen[slot].insert(key.clone()) {
                    target.keys.push(key.clone());
                }
            }
            planned.push((index, slot, keys));
            target.position = Some(event.sequence);
        }
        before = event.sequence;
    }

    for target in &mut targets {
        if target.rebuild && target.locked.is_none() && target.position.is_some() {
            // The first fold of this build: state left by a build it
            // restarted is discarded - under the lock, so no instance can
            // be folding into it meanwhile.
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "DELETE FROM {schema}.projection_rebuild_state \
                 WHERE projection_name = $1 AND status = 'building'"
            )))
            .bind(target.name)
            .execute(&mut *tx)
            .await?;
        }
        if target.keys.is_empty() {
            continue;
        }
        let default_state_json = dispatcher
            .default_state(bounded_context, target.name)
            .unwrap_or_default();
        target.states = lock_chunk_states(
            &mut tx,
            schema,
            target.rebuild,
            target.name,
            &target.keys,
            &default_state_json,
        )
        .await?;
    }

    for (index, slot, keys) in &planned {
        *reached = *index;
        let event = &events[*index];
        let target = &mut targets[*slot];
        let owner = event_owner(
            dispatcher
                .owner_tag_key(bounded_context, target.name)
                .flatten(),
            event,
        );
        fold_into_chunk_states(
            dispatcher,
            bounded_context,
            target.name,
            &mut target.states,
            keys,
            event,
            &owner,
        )?;
    }
    *reached = 0;

    for target in &targets {
        write_chunk_states(&mut tx, schema, target.rebuild, target.name, &target.states).await?;

        if target.position == target.locked {
            continue;
        }
        // Never backwards: another instance's concurrent catch-up may
        // already have moved it further (docs/architecture.md §113). `AND
        // status = 'building'`: a coexisting pending row shares the
        // `projection_name`, and must keep its `caught_up_to` `None` until
        // it's promoted or discarded.
        let query = if target.rebuild {
            format!(
                "UPDATE {schema}.projection_rebuilds SET caught_up_to = $1 \
                 WHERE projection_name = $2 AND status = 'building' \
                 AND (caught_up_to IS NULL OR caught_up_to < $1)"
            )
        } else {
            format!(
                "UPDATE {schema}.projections SET caught_up_to = $1 \
                 WHERE name = $2 AND (caught_up_to IS NULL OR caught_up_to < $1)"
            )
        };
        sqlx::query(sqlx::AssertSqlSafe(query))
            .bind(target.position)
            .bind(target.name)
            .execute(&mut *tx)
            .await?;
    }

    tx.commit().await?;
    Ok(())
}

/// Get-or-create-with-lock of every one of `keys` at once, in the order
/// given - see `get_or_create_projection_state_for_update`. `rebuild`
/// picks the `building` rebuild's state table instead of the live one.
async fn lock_chunk_states(
    conn: &mut sqlx::PgConnection,
    schema: &str,
    rebuild: bool,
    projection_name: &str,
    keys: &[String],
    default_state_json: &str,
) -> crate::error::Result<std::collections::HashMap<String, CatchUpChunkState>> {
    let rows: Vec<(String, i64, String)> = if rebuild {
        sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.projection_rebuild_state \
             (projection_name, status, key, state, updated_at) \
             SELECT $1, 'building', key, $3, now() FROM unnest($2::text[]) AS key \
             ON CONFLICT (projection_name, status, key) DO UPDATE SET \
             state = {schema}.projection_rebuild_state.state \
             RETURNING key, as_of_sequence, state"
        )))
    } else {
        sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.projection_state (projection_name, key, state, updated_at) \
             SELECT $1, key, $3, now() FROM unnest($2::text[]) AS key \
             ON CONFLICT (projection_name, key) DO UPDATE SET \
             state = {schema}.projection_state.state \
             RETURNING key, as_of_sequence, state"
        )))
    }
    .bind(projection_name)
    .bind(keys)
    .bind(default_state_json)
    .fetch_all(&mut *conn)
    .await?;
    Ok(rows
        .into_iter()
        .map(|(key, as_of_sequence, state)| {
            let folded = CatchUpChunkState {
                as_of_sequence,
                state,
                owner: None,
                folded: false,
            };
            (key, folded)
        })
        .collect())
}

/// Folds `event` into each of `keys`' states, keeping the
/// `as_of_sequence` guard (issue #25): another instance may have
/// folded a row past `event` already. `owner` is the one `event` gives
/// (`event_owner`).
fn fold_into_chunk_states(
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    bounded_context: &str,
    projection_name: &str,
    states: &mut std::collections::HashMap<String, CatchUpChunkState>,
    keys: &[String],
    event: &Event,
    owner: &Option<String>,
) -> crate::error::Result<()> {
    for key in keys {
        let entry = states
            .get_mut(key)
            .expect("every planned key's row was just read");
        if entry.as_of_sequence >= event.sequence {
            continue;
        }
        if let Some(result) =
            dispatcher.project(bounded_context, projection_name, &entry.state, event, key)
        {
            entry.state = result?;
        }
        entry.as_of_sequence = event.sequence;
        if owner.is_some() {
            entry.owner.clone_from(owner);
        }
        entry.folded = true;
    }
    Ok(())
}

/// Writes every folded one of `states` back in one statement. A `NULL`
/// owner leaves the stored one as it is - see
/// `apply_projection_fold_update`.
async fn write_chunk_states(
    conn: &mut sqlx::PgConnection,
    schema: &str,
    rebuild: bool,
    projection_name: &str,
    states: &std::collections::HashMap<String, CatchUpChunkState>,
) -> crate::error::Result<()> {
    let mut keys = Vec::new();
    let mut folded_states = Vec::new();
    let mut owners = Vec::new();
    let mut as_of_sequences = Vec::new();
    for (key, folded) in states.iter().filter(|(_, s)| s.folded) {
        keys.push(key.as_str());
        folded_states.push(folded.state.as_str());
        owners.push(folded.owner.as_deref());
        as_of_sequences.push(folded.as_of_sequence);
    }
    if keys.is_empty() {
        return Ok(());
    }
    let (table, extra_where) = if rebuild {
        ("projection_rebuild_state", " AND s.status = 'building'")
    } else {
        ("projection_state", "")
    };
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.{table} AS s SET state = u.state, \
         owner = COALESCE(u.owner, s.owner), as_of_sequence = u.as_of_sequence, \
         updated_at = now() \
         FROM unnest($2::text[], $3::text[], $4::text[], $5::bigint[]) \
         AS u(key, state, owner, as_of_sequence) \
         WHERE s.projection_name = $1 AND s.key = u.key{extra_where}"
    )))
    .bind(projection_name)
    .bind(&keys)
    .bind(&folded_states)
    .bind(&owners)
    .bind(&as_of_sequences)
    .execute(&mut *conn)
    .await?;
    Ok(())
}

/// `catch_up_bounded_context`'s own per-tick body for one async
/// `Projection` whose `Projection::PARTITION_COUNT > 1` (issue
/// #25's investigation, docs/architecture.md §50/§51 - see that
/// section for the full design writeup). Reuses `keys()` itself as the
/// partitioning input - no separate "partition key" concept - hashing
/// each key `dispatcher.keys()` returns into one of `partition_count`
/// buckets via `partition_for_key` (a hand-written, cross-version-stable
/// FNV-1a, not `std::collections::hash_map::DefaultHasher`, which is
/// explicitly not guaranteed stable across Rust versions and would risk
/// two instances silently disagreeing on a key's own bucket).
///
/// Claiming is a non-blocking, per-tick race for each partition's own
/// `pg_try_advisory_xact_lock`, the identical primitive
/// `migrate_idempotency_keys_client_id_scoping` already establishes -
/// whichever instance wins a given partition this tick folds every
/// pending key in that bucket, inside the one transaction that holds
/// the lock; a losing instance simply skips that partition this tick,
/// with no lease/heartbeat/expiry machinery needed since a dead
/// instance just stops winning locks. **This lock is a pure
/// work-avoidance optimization, not a correctness mechanism**: every
/// fold below still goes through the exact same
/// `get_or_create_projection_state_for_update` → `as_of_sequence` guard
/// → `dispatcher.project()` → `apply_projection_fold_update` sequence
/// the unpartitioned loop above uses, so even a hash disagreement
/// between instances (a theoretical `hashtext` collision, or a rolling
/// deploy briefly running two different `PARTITION_COUNT` values) could
/// only ever cause wasted duplicate work, never a double-fold.
///
/// One transaction per `(partition, tick)`, not per-event: a
/// non-blocking lock re-acquired per event would force stopping at the
/// first lost race anyway, since a partition's own progress can only
/// advance contiguously in sequence order - far more lock round trips
/// for no real benefit. The real cost this trades away, relative to the
/// unpartitioned loop's own per-event transaction granularity, is
/// durability: a poison event anywhere in a partition's own batch this
/// tick rolls back that whole partition's tick, not just the offending
/// event - `MAX_EVENTS_PER_PARTITION_TICK` bounds the blast radius, and
/// the next tick's fresh, non-blocking race is self-healing regardless
/// of which instance (if any) previously held that partition.
///
/// Deliberately excludes a `ProjectionRebuild`'s own `building` fold and
/// `fold_history_into_new_sync_projection` - both stay single-instance,
/// exactly as before `PARTITION_COUNT` existed. Rebuilds are one-time,
/// bounded events (only `schema_changed`/`consumed_change_has_history`/
/// `becoming_sync` in `register_projection` ever stage one), not the
/// sustained-throughput concern issue #25 is actually about.
///
/// **Known accepted limitation**: after a rebuild promotes
/// (`promote_projection_rebuild`), this projection's own
/// `projection_partition_progress` rows can be stale relative to the
/// freshly-jumped `projections.caught_up_to` the rebuild just set - the
/// next tick(s) will re-scan the gap (capped, self-healing over a few
/// ticks by `MAX_EVENTS_PER_PARTITION_TICK`) purely as wasted work,
/// never a correctness risk, since `as_of_sequence` still skips every
/// already-folded key/event pair it re-scans. Not worth promotion-side
/// bookkeeping to close for what is a rare, self-correcting cost.
#[allow(clippy::too_many_arguments)]
async fn catch_up_partitioned_projection(
    pool: &Pool,
    bounded_context: &str,
    schema: &str,
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    projection: &Projection,
    partition_count: u32,
    latest: i64,
) -> crate::error::Result<()> {
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.projection_partition_progress \
         (projection_name, partition_index, caught_up_to, updated_at) \
         SELECT $1, gs, -1, now() FROM generate_series(0, $2::int - 1) AS gs \
         ON CONFLICT (projection_name, partition_index) DO NOTHING"
    )))
    .bind(&projection.name)
    .bind(partition_count as i32)
    .execute(pool)
    .await?;

    let mut progress = list_projection_partition_progress(pool, schema, &projection.name).await?;
    let min_caught_up = (0..partition_count)
        .map(|p| progress.get(&p).copied().unwrap_or(-1))
        .min()
        .unwrap_or(latest);

    let events = if min_caught_up >= latest {
        Vec::new()
    } else {
        list_events_for_bounded_context_from_limited(
            pool,
            bounded_context,
            min_caught_up,
            MAX_EVENTS_PER_PARTITION_TICK,
        )
        .await?
    };

    if !events.is_empty() {
        let batch_end = events
            .last()
            .expect("just checked events is non-empty")
            .sequence;
        let default_state_json = dispatcher
            .default_state(bounded_context, &projection.name)
            .unwrap_or_default();
        let owner_tag_key = dispatcher
            .owner_tag_key(bounded_context, &projection.name)
            .flatten();

        for partition_index in 0..partition_count {
            if progress.get(&partition_index).copied().unwrap_or(-1) >= batch_end {
                continue;
            }

            let mut tx = pool.begin().await?;
            let locked: bool =
                sqlx::query_scalar("SELECT pg_try_advisory_xact_lock(hashtext($1)::bigint)")
                    .bind(partition_lock_key(
                        bounded_context,
                        &projection.name,
                        partition_index,
                    ))
                    .fetch_one(&mut *tx)
                    .await?;
            if !locked {
                // Nothing was written under this transaction - dropping
                // it is a no-op rollback, not a partial commit to worry
                // about. Another instance (or this one, next tick) owns
                // this partition for now.
                continue;
            }

            // Every key of this partition read and locked once, folded
            // in memory, and written once (docs/architecture.md §197), as
            // the unpartitioned chunk does (§182). Keys are locked in
            // sorted order. The transaction was already all or nothing.
            let after = progress.get(&partition_index).copied().unwrap_or(-1);
            let mut planned: Vec<(&Event, Vec<String>)> = Vec::new();
            let mut keys: Vec<String> = Vec::new();
            for event in events.iter().filter(|e| e.sequence > after) {
                let event_keys: Vec<String> = dispatcher
                    .keys(bounded_context, &projection.name, event)
                    .unwrap_or_default()
                    .into_iter()
                    .filter(|key| partition_for_key(key, partition_count) == partition_index)
                    .collect();
                if !event_keys.is_empty() {
                    keys.extend(event_keys.iter().cloned());
                    planned.push((event, event_keys));
                }
            }
            keys.sort_unstable();
            keys.dedup();
            if !keys.is_empty() {
                let mut states = lock_chunk_states(
                    &mut tx,
                    schema,
                    false,
                    &projection.name,
                    &keys,
                    &default_state_json,
                )
                .await?;
                for (event, event_keys) in &planned {
                    fold_into_chunk_states(
                        dispatcher,
                        bounded_context,
                        &projection.name,
                        &mut states,
                        event_keys,
                        event,
                        &event_owner(owner_tag_key, event),
                    )?;
                }
                write_chunk_states(&mut tx, schema, false, &projection.name, &states).await?;
            }
            let this_partition_progress = after.max(batch_end);

            sqlx::query(sqlx::AssertSqlSafe(format!(
                "INSERT INTO {schema}.projection_partition_progress \
                 (projection_name, partition_index, caught_up_to, updated_at) \
                 VALUES ($1, $2, $3, now()) \
                 ON CONFLICT (projection_name, partition_index) DO UPDATE SET \
                    caught_up_to = GREATEST(\
                        {schema}.projection_partition_progress.caught_up_to, EXCLUDED.caught_up_to), \
                    updated_at = now()"
            )))
            .bind(&projection.name)
            .bind(partition_index as i32)
            .bind(this_partition_progress)
            .execute(&mut *tx)
            .await?;

            tx.commit().await?;
            progress.insert(partition_index, this_partition_progress);
        }
    }

    // Rolled up regardless of which partitions (if any) this instance
    // won this tick - any instance computing this is harmless, idempotent
    // work, and it's what keeps `projections.caught_up_to` (the single
    // external source of truth GraphQL's `caughtUpTo`/`wait_until_caught_up`
    // depend on) meaning exactly what it always has: every key of this
    // projection reflects every event up to this sequence. The
    // `partition_index < $2` filter excludes any row left over from a
    // since-decreased `PARTITION_COUNT`, so it can never wedge the
    // rollup on a stale high-index row nothing advances anymore.
    let rolled_up: Option<i64> = sqlx::query_scalar(sqlx::AssertSqlSafe(format!(
        "SELECT MIN(caught_up_to) FROM {schema}.projection_partition_progress \
         WHERE projection_name = $1 AND partition_index < $2"
    )))
    .bind(&projection.name)
    .bind(partition_count as i32)
    .fetch_one(pool)
    .await?;
    if let Some(rolled_up) = rolled_up {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "UPDATE {schema}.projections SET caught_up_to = $1 \
             WHERE name = $2 AND (caught_up_to IS NULL OR caught_up_to < $1)"
        )))
        .bind(rolled_up)
        .bind(&projection.name)
        .execute(pool)
        .await?;
    }

    Ok(())
}

/// A generous bound on how many events one partitioned projection's own
/// per-partition-per-tick transaction (`catch_up_partitioned_projection`)
/// spans - not a correctness requirement, but for a different reason
/// than `MAX_DUE_DEADLINES_PER_TICK`/`MAX_OCCURRENCES_PER_TICK`'s own
/// "don't starve other work sharing this tick": a partitioned
/// projection's own tick is a *single all-or-nothing transaction* per
/// partition (see `catch_up_partitioned_projection`'s own doc comment
/// for why), so without a cap, a poison event anywhere in a truly
/// enormous post-outage backlog would roll back that entire backlog's
/// worth of progress for that partition, not just the offending event -
/// the unpartitioned path's own per-event transaction granularity has no
/// such exposure. Events beyond this cap are simply left for the next
/// tick, which resumes from wherever this partition's own progress
/// landed - the same "recent window, not a hard limit on correctness"
/// register those two constants are already in.
const MAX_EVENTS_PER_PARTITION_TICK: i64 = 1000;

/// `catch_up_partitioned_projection`'s own key→partition assignment -
/// hand-written 64-bit FNV-1a rather than
/// `std::collections::hash_map::DefaultHasher` (explicitly not
/// guaranteed stable across Rust versions/std/build flags - unsuitable
/// for a scheme that must agree across every instance in a fleet,
/// possibly running slightly different builds during a rolling deploy)
/// or a new crate dependency (not judged worth it for a few lines of
/// well-known, public-domain algorithm). Computed in Rust, not pushed
/// into Postgres via `hashtext()`, since partition membership must be
/// known *before* deciding which partitions are even worth a lock
/// attempt this tick - `hashtext()` is still used, unrelated, for the
/// advisory lock key itself (`partition_lock_key` below).
fn partition_for_key(key: &str, partition_count: u32) -> u32 {
    const FNV_OFFSET_BASIS: u64 = 0xcbf29ce484222325;
    const FNV_PRIME: u64 = 0x100000001b3;
    let mut hash = FNV_OFFSET_BASIS;
    for byte in key.as_bytes() {
        hash ^= u64::from(*byte);
        hash = hash.wrapping_mul(FNV_PRIME);
    }
    (hash % u64::from(partition_count)) as u32
}

/// The `pg_try_advisory_xact_lock` key `catch_up_partitioned_projection`
/// races for one `(bounded_context, projection, partition)` triple -
/// bound via `hashtext($1)::bigint`, the same pattern
/// `migrate_idempotency_keys_client_id_scoping` already establishes. A
/// `hashtext` collision with an unrelated lock key is theoretically
/// possible (32-bit output) but harmless here: it would only ever cause
/// a spurious, self-healing missed attempt this tick - exactly why this
/// function's own caller uses the non-blocking `pg_try_advisory_xact_lock`
/// form rather than the blocking `pg_advisory_xact_lock` the migration
/// guard uses.
fn partition_lock_key(
    bounded_context: &str,
    projection_name: &str,
    partition_index: u32,
) -> String {
    format!("projection_partition:{bounded_context}:{projection_name}:{partition_index}")
}

/// `catch_up_partitioned_projection`'s own progress read - every
/// `projection_partition_progress` row for one projection, as a
/// `partition_index -> caught_up_to` map. A partition index with no row
/// yet (shouldn't happen once that function's own seed step has run,
/// but not assumed) is simply absent from the map - every caller already
/// treats a missing entry as `-1` via `.unwrap_or(-1)`, the same
/// "nothing folded yet" convention `projection_state.as_of_sequence`'s
/// own default uses.
async fn list_projection_partition_progress(
    pool: &Pool,
    schema: &str,
    projection_name: &str,
) -> crate::error::Result<std::collections::HashMap<u32, i64>> {
    let rows: Vec<(i32, i64)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT partition_index, caught_up_to \
         FROM {schema}.projection_partition_progress WHERE projection_name = $1"
    )))
    .bind(projection_name)
    .fetch_all(pool)
    .await?;
    Ok(rows
        .into_iter()
        .map(|(idx, seq)| (idx as u32, seq))
        .collect())
}

/// The values of `tag_key` `event` carries, each once, in the order it
/// carries them: the snapshot rows it folds into (docs/architecture.md
/// §202). A tag with no value has no row.
fn snapshot_tag_values<'e>(event: &'e Event, tag_key: &str) -> Vec<&'e str> {
    let mut values: Vec<&str> = Vec::new();
    for tag in &event.tags {
        if tag.key != tag_key {
            continue;
        }
        if let Some(value) = tag.value.as_deref() {
            if !values.contains(&value) {
                values.push(value);
            }
        }
    }
    values
}

/// One snapshot row's state while a chunk is folded: read and locked
/// before the chunk's events are folded into it, written back once after
/// (docs/architecture.md §197).
struct SnapshotChunkRow {
    as_of_sequence: i64,
    state: String,
    owner: Option<String>,
    /// The position its tag's history was refolded through, for a row
    /// created or reset by this chunk - see [`refold_snapshot_histories`].
    /// The chunk's events up to it are already in `state`.
    history_through: Option<i64>,
}

/// Folds the events of `events` past `after` into snapshot `name`'s rows,
/// on `conn` - the caller's transaction, which it commits. `partition`,
/// `(index, count)`, keeps only the tag values that hash to that
/// partition. Exactly what folding them one event at a time did, with
/// each row read and locked once and written once (docs/architecture.md
/// §197):
///
/// 1. Every tag value the events touch is locked, or created, in one
///    statement, sorted, so two instances' chunks lock them in the same
///    order. A row at an older `Snapshot::VERSION` is reset as part of it,
///    atomically, to the default state at `as_of_sequence` -1 - the
///    "model changed" case `CommandType::decide_from_snapshot`'s own doc
///    comment describes.
/// 2. A row created or reset here (`as_of_sequence` -1) is refolded from
///    its tag's whole history through its last event in the chunk - one
///    paged read for every such row at once ([`refold_snapshot_histories`]).
///    That's what folding the history at its first event and then each
///    later event did.
/// 3. The rest are folded in memory, keeping the `as_of_sequence` guard.
/// 4. Every folded row is written back in one `UPDATE ... FROM unnest`.
///    A row's owner is the last owner tag a folded event carried; one no
///    event gave an owner keeps the stored one.
///
/// `reached` is set to the index in `events` of the event a failing fold
/// was folding, and left alone otherwise - see
/// [`CatchUpChunkFailure`].
#[allow(clippy::too_many_arguments)]
async fn fold_snapshot_chunk_in_tx(
    conn: &mut sqlx::PgConnection,
    bc: &BoundedContext,
    schema: &str,
    dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    name: &str,
    events: &[Event],
    after: i64,
    partition: Option<(u32, u32)>,
    reached: &mut usize,
) -> crate::error::Result<()> {
    let bounded_context = bc.name.as_str();
    let Some(tag_key) = dispatcher.tag_key(bounded_context, name) else {
        return Ok(());
    };
    let version = stored_snapshot_version(dispatcher.version(bounded_context, name).unwrap_or(0));
    let default_state_json = dispatcher
        .default_state(bounded_context, name)
        .unwrap_or_default();
    let owner_tag_key = dispatcher.owner_tag_key(bounded_context, name).flatten();

    // The events this snapshot folds, with the tag value each one folds
    // into: every value of the key it carries (docs/architecture.md
    // §202), each once.
    let mut planned: Vec<(usize, &str)> = Vec::new();
    let mut values: Vec<&str> = Vec::new();
    for (index, event) in events.iter().enumerate() {
        if event.sequence <= after {
            continue;
        }
        for value in snapshot_tag_values(event, tag_key) {
            if let Some((partition_index, partition_count)) = partition {
                if partition_for_key(value, partition_count) != partition_index {
                    continue;
                }
            }
            planned.push((index, value));
            values.push(value);
        }
    }
    if planned.is_empty() {
        return Ok(());
    }
    values.sort_unstable();
    values.dedup();

    let locked: Vec<(String, i64, String)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.snapshots \
            (snapshot_name, tag_key, tag_value, snapshot_version, as_of_sequence, state, updated_at) \
         SELECT $1, $2, value, $4, -1, $5::jsonb, now() FROM unnest($3::text[]) AS value \
         ON CONFLICT (snapshot_name, tag_key, tag_value) DO UPDATE SET \
            snapshot_version = $4, \
            as_of_sequence = CASE WHEN {schema}.snapshots.snapshot_version = $4 \
                THEN {schema}.snapshots.as_of_sequence ELSE -1 END, \
            state = CASE WHEN {schema}.snapshots.snapshot_version = $4 \
                THEN {schema}.snapshots.state ELSE $5::jsonb END \
         RETURNING tag_value, as_of_sequence, state::text"
    )))
    .bind(name)
    .bind(tag_key)
    .bind(&values)
    .bind(version)
    .bind(&default_state_json)
    .fetch_all(&mut *conn)
    .await?;
    let mut rows: std::collections::HashMap<String, SnapshotChunkRow> = locked
        .into_iter()
        .map(|(value, as_of_sequence, state)| {
            let row = SnapshotChunkRow {
                as_of_sequence,
                state,
                owner: None,
                history_through: None,
            };
            (value, row)
        })
        .collect();

    // A row at -1 is refolded through its last event in the chunk. Each
    // keeps its events' `(sequence, index)`, in order, to say which event
    // a failing fold belongs to.
    let mut refold: std::collections::HashMap<&str, Vec<(i64, usize)>> =
        std::collections::HashMap::new();
    for (index, value) in &planned {
        if rows[*value].as_of_sequence == -1 {
            refold
                .entry(*value)
                .or_default()
                .push((events[*index].sequence, *index));
        }
    }
    if !refold.is_empty() {
        refold_snapshot_histories(
            conn,
            bc,
            dispatcher,
            name,
            tag_key,
            &default_state_json,
            &refold,
            &mut rows,
            reached,
        )
        .await?;
    }

    for (index, value) in &planned {
        let event = &events[*index];
        let row = rows
            .get_mut(*value)
            .expect("every planned value's row was just read");
        let refolded = row.history_through.is_some_and(|h| event.sequence <= h);
        if !refolded {
            // `as_of_sequence` guard (issue #25): another
            // instance may have folded this row past `event` already.
            if row.as_of_sequence >= event.sequence {
                continue;
            }
            if let Some(result) =
                dispatcher.fold_value(bounded_context, name, value, &row.state, event)
            {
                row.state = result.inspect_err(|_| *reached = *index)?;
            }
            row.as_of_sequence = event.sequence;
        }
        if let Some(owner) = event_owner(owner_tag_key, event) {
            row.owner = Some(owner);
        }
    }

    let mut written_values = Vec::new();
    let mut states = Vec::new();
    let mut owners = Vec::new();
    let mut as_of_sequences = Vec::new();
    for (value, row) in &rows {
        written_values.push(value.as_str());
        states.push(row.state.as_str());
        owners.push(row.owner.as_deref());
        as_of_sequences.push(row.as_of_sequence);
    }
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.snapshots AS s SET snapshot_version = $3, state = u.state::jsonb, \
         owner = COALESCE(u.owner, s.owner), as_of_sequence = u.as_of_sequence, \
         updated_at = now() \
         FROM unnest($4::text[], $5::text[], $6::text[], $7::bigint[]) \
         AS u(tag_value, state, owner, as_of_sequence) \
         WHERE s.snapshot_name = $1 AND s.tag_key = $2 AND s.tag_value = u.tag_value"
    )))
    .bind(name)
    .bind(tag_key)
    .bind(version)
    .bind(&written_values)
    .bind(&states)
    .bind(&owners)
    .bind(&as_of_sequences)
    .execute(&mut *conn)
    .await?;
    Ok(())
}

/// Folds `events` - a contiguous run of the bounded context's events -
/// into every unpartitioned snapshot in `names` that `progress` puts
/// before its end, and moves their progress to its end, in one
/// transaction (docs/architecture.md §197). Snapshots go by name, so two
/// instances' chunks lock their rows in the same order.
#[allow(clippy::too_many_arguments)]
async fn fold_snapshots_chunk(
    pool: &Pool,
    bc: &BoundedContext,
    schema: &str,
    dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    names: &[&str],
    progress: &std::collections::HashMap<&str, i64>,
    events: &[Event],
) -> Result<(), CatchUpChunkFailure> {
    let mut reached = 0;
    let folded: crate::error::Result<()> = async {
        let Some(chunk_end) = events.last().map(|event| event.sequence) else {
            return Ok(());
        };
        let mut sorted: Vec<&str> = names.to_vec();
        sorted.sort_unstable();
        let mut tx = pool.begin().await?;
        for name in sorted {
            let after = progress.get(name).copied().unwrap_or(-1);
            if after >= chunk_end {
                continue;
            }
            fold_snapshot_chunk_in_tx(
                &mut tx,
                bc,
                schema,
                dispatcher,
                name,
                events,
                after,
                None,
                &mut reached,
            )
            .await?;
            upsert_snapshot_progress(&mut *tx, schema, name, chunk_end).await?;
        }
        tx.commit().await?;
        Ok(())
    }
    .await;
    folded.map_err(|error| CatchUpChunkFailure {
        folded_before: reached,
        error,
    })
}

/// Refolds each row in `refold` - tag value to its chunk events'
/// `(sequence, index)`, in order - from nothing over every event carrying
/// that tag value up to and including its last chunk event, into `rows`
/// (docs/architecture.md §152, §197). One paged read covers every value
/// at once, instead of one read per value, through `event_tags` (§198):
/// its btree hands back each value's sequences in order, where the GIN
/// index on `events.tags` (since dropped, §210) rebuilt and sorted every value's whole bitmap
/// for each page - about four times slower for 100 values of 500 events.
/// The page is of distinct sequences: `event_tags` has a row per tag, so
/// an event carrying two of the values has two, and a limit on rows
/// returned a short page before the end, which ended the paging early.
/// A
/// fold that fails sets `reached` to the first of the value's chunk
/// events at or after the failing one: the event at which the per-event
/// loop would have reached it, and failed - the first chunk event for
/// history from before the chunk.
#[allow(clippy::too_many_arguments)]
async fn refold_snapshot_histories(
    conn: &mut sqlx::PgConnection,
    bc: &BoundedContext,
    dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    name: &str,
    tag_key: &str,
    default_state_json: &str,
    refold: &std::collections::HashMap<&str, Vec<(i64, usize)>>,
    rows: &mut std::collections::HashMap<String, SnapshotChunkRow>,
    reached: &mut usize,
) -> crate::error::Result<()> {
    const PAGE: i64 = 1000;
    let schema = schema_ident(&bc.name);
    let through_of = |planned: &[(i64, usize)]| {
        planned
            .last()
            .expect("a refolded value has a chunk event")
            .0
    };
    let through_all = refold
        .values()
        .map(|planned| through_of(planned))
        .max()
        .expect("refold is non-empty");
    let mut values: Vec<&str> = refold.keys().copied().collect();
    values.sort_unstable();
    for (value, planned) in refold {
        let row = rows.get_mut(*value).expect("every refolded row was read");
        row.state = default_state_json.to_string();
        row.as_of_sequence = through_of(planned);
        row.history_through = Some(through_of(planned));
    }

    let mut after = -1;
    loop {
        let page: Vec<EventRowAnyType> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, \
             metadata_client_id, metadata_created_at, metadata_correlation_id, \
             metadata_causation_id, tags, origin_kind, origin_source_content, \
             origin_source_context, origin_command_id FROM {schema}.events \
             WHERE sequence IN (SELECT DISTINCT sequence FROM {schema}.event_tags \
                 WHERE tag_key = $1 AND tag_value = ANY($2) \
                 AND sequence > $3 AND sequence <= $4 ORDER BY sequence LIMIT $5) \
             ORDER BY sequence"
        )))
        .bind(tag_key)
        .bind(&values)
        .bind(after)
        .bind(through_all)
        .bind(PAGE)
        .fetch_all(&mut *conn)
        .await?;
        let full = page.len() as i64 == PAGE;
        let page = events_from_rows(&mut *conn, bc, page, None).await?;
        for event in &page {
            for value in snapshot_tag_values(event, tag_key) {
                let Some(planned) = refold.get(value) else {
                    continue;
                };
                let Some(&(_, index)) = planned.iter().find(|(seq, _)| *seq >= event.sequence)
                else {
                    continue;
                };
                let row = rows.get_mut(value).expect("every refolded row was read");
                if let Some(result) =
                    dispatcher.fold_value(&bc.name, name, value, &row.state, event)
                {
                    row.state = result.inspect_err(|_| *reached = index)?;
                }
            }
        }
        match page.last() {
            Some(last) if full => after = last.sequence,
            _ => return Ok(()),
        }
    }
}

/// [docs/architecture.md §19](../../../docs/architecture.md#optional-snapshotting-matching-events)'s "Problem 2" - the background half of
/// `Snapshot`: one poll tick, for one bounded context, folding every
/// committed event not yet reflected in any registered snapshot.
/// Deliberately its own function, not folded into `catch_up_bounded_context`
/// above even though the shape closely mirrors it - see `Snapshot`'s own
/// doc comment for why the two stay structurally separate. Called in a
/// loop, on a timer, by its own shared background task
/// `SkiljBuilder::build()` spawns.
///
/// Unlike `Projection` (discovered via the `projections` metadata
/// table), which snapshots exist is asked of `dispatcher` directly -
/// `SnapshotDispatcher::snapshot_names` - since there is deliberately no
/// metadata table for `Snapshot` (see that trait's own doc comment).
/// Progress is tracked per `snapshot_name` in `snapshot_progress`
/// (`Projection`'s own `caught_up_to` column isn't reused, for the same
/// separation reason), and, per event, at most one tag *value*'s own row
/// is touched - `Snapshot::TAG_KEY` names a single tag key, so `event.tags`
/// either does or doesn't carry it, no `keys()`-equivalent fan-out the
/// way a multi-instance `Projection` needs.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn catch_up_snapshots(
    pool: &Pool,
    bounded_context: &str,
    dispatcher: &dyn crate::plugin::SnapshotDispatcher,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    let latest = latest_sequence(pool, bounded_context).await?.unwrap_or(-1);

    let all_snapshot_names = dispatcher.snapshot_names(bounded_context);
    // issue #25 (docs/architecture.md §52) - split by
    // `Snapshot::PARTITION_COUNT` (via the dispatcher, the only place
    // this Rust-only config lives, exactly like `Projection`'s own
    // split in `catch_up_bounded_context`). `unpartitioned_snapshot_names`
    // (`<= 1`, the default, and every snapshot that predates this
    // feature) feeds the exact same loop this function has always had,
    // completely unchanged below.
    let unpartitioned_snapshot_names: Vec<&str> = all_snapshot_names
        .iter()
        .filter(|name| {
            dispatcher
                .partition_count(bounded_context, name)
                .unwrap_or(1)
                .max(1)
                <= 1
        })
        .copied()
        .collect();
    let partitioned_snapshot_names: Vec<(&str, u32)> = all_snapshot_names
        .iter()
        .filter_map(|name| {
            let partition_count = dispatcher
                .partition_count(bounded_context, name)
                .unwrap_or(1)
                .max(1);
            (partition_count > 1).then_some((*name, partition_count))
        })
        .collect();
    if unpartitioned_snapshot_names.is_empty() && partitioned_snapshot_names.is_empty() {
        return Ok(());
    }

    let progress_from_db =
        list_snapshot_progress_for_bounded_context(pool, bounded_context).await?;
    let mut progress: std::collections::HashMap<&str, i64> = unpartitioned_snapshot_names
        .iter()
        .map(|name| (*name, progress_from_db.get(*name).copied().unwrap_or(-1)))
        .collect();

    let min_caught_up = progress.values().copied().min().unwrap_or(latest);
    let events = if unpartitioned_snapshot_names.is_empty() || min_caught_up >= latest {
        Vec::new()
    } else {
        // At most `MAX_EVENTS_PER_CATCH_UP_TICK`: progress persists per
        // event, so a new projection/rebuild/snapshot over a long history
        // catches up over several ticks instead of loading it whole.
        list_events_for_bounded_context_from_limited(
            pool,
            bounded_context,
            min_caught_up,
            MAX_EVENTS_PER_CATCH_UP_TICK,
        )
        .await?
    };

    // A chunk of events per transaction, not one (docs/architecture.md
    // §197), as projection catch-up does (§182).
    if let Some(first) = events.first() {
        let bc = &first.bounded_context;
        for chunk in events.chunks(CATCH_UP_EVENTS_PER_TRANSACTION) {
            let folded = fold_snapshots_chunk(
                pool,
                bc,
                &schema,
                dispatcher,
                &unpartitioned_snapshot_names,
                &progress,
                chunk,
            )
            .await;
            if let Err(failure) = folded {
                // A failing event doesn't take the events before it in
                // its chunk down with it - see `catch_up_bounded_context`.
                // Shortened again if a shorter run fails earlier - a
                // refolded row's history, or another snapshot, can fail
                // before the event blamed (docs/architecture.md §200).
                let mut end = failure.folded_before;
                while end > 0 {
                    match fold_snapshots_chunk(
                        pool,
                        bc,
                        &schema,
                        dispatcher,
                        &unpartitioned_snapshot_names,
                        &progress,
                        &chunk[..end],
                    )
                    .await
                    {
                        Ok(()) => break,
                        Err(retry) if retry.folded_before < end => end = retry.folded_before,
                        Err(retry) => return Err(retry.error),
                    }
                }
                return Err(failure.error);
            }
            let chunk_end = chunk.last().expect("chunks are never empty").sequence;
            for position in progress.values_mut() {
                *position = (*position).max(chunk_end);
            }
        }
    }

    // issue #25 (docs/architecture.md §52) - sequential across
    // partitioned snapshots, not `for_each_concurrent`, the identical
    // reasoning `catch_up_bounded_context`'s own partitioned-projection
    // loop already documents (§51): the real scale-out value comes from
    // separate *instances* racing for partitions, not from one
    // instance's own intra-tick fan-out.
    for (name, partition_count) in partitioned_snapshot_names {
        catch_up_partitioned_snapshot(
            pool,
            bounded_context,
            &schema,
            dispatcher,
            name,
            partition_count,
            latest,
        )
        .await?;
    }

    Ok(())
}

/// `catch_up_snapshots`'s own per-tick body for one `Snapshot` whose
/// `Snapshot::PARTITION_COUNT > 1` (issue #25, docs/architecture.md
/// §52 - the `Snapshot` twin of `catch_up_partitioned_projection`, see
/// that function's own doc comment for the full design writeup, not
/// repeated in full here). The one structural difference: `Snapshot`
/// derives at most *one* tag value per event (there's no `keys()`-style
/// fan-out - see `Snapshot`'s own doc comment), so partitioning hashes
/// that single derived tag value instead of iterating several keys per
/// event.
///
/// Same primitives throughout: `partition_for_key` (the identical
/// FNV-1a §51 established), a non-blocking
/// `pg_try_advisory_xact_lock` per `(snapshot_name, partition)` per
/// tick (`snapshot_partition_lock_key`), one transaction per
/// `(partition, tick)`, `MAX_EVENTS_PER_PARTITION_TICK`-capped batches
/// via the existing `list_events_for_bounded_context_from_limited`, and
/// a monotonic-only rollup into `snapshot_progress.caught_up_to` (the
/// single external source of truth, unchanged in shape - `Snapshot` has
/// no GraphQL-exposed `caughtUpTo` field the way `Projection` does, but
/// `resolve_snapshot_context`'s own correctness already depends on
/// `snapshots.as_of_sequence` per row, untouched by any of this).
#[allow(clippy::too_many_arguments)]
async fn catch_up_partitioned_snapshot(
    pool: &Pool,
    bounded_context: &str,
    schema: &str,
    dispatcher: &dyn crate::plugin::SnapshotDispatcher,
    name: &str,
    partition_count: u32,
    latest: i64,
) -> crate::error::Result<()> {
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.snapshot_partition_progress \
         (snapshot_name, partition_index, caught_up_to, updated_at) \
         SELECT $1, gs, -1, now() FROM generate_series(0, $2::int - 1) AS gs \
         ON CONFLICT (snapshot_name, partition_index) DO NOTHING"
    )))
    .bind(name)
    .bind(partition_count as i32)
    .execute(pool)
    .await?;

    let mut progress = list_snapshot_partition_progress(pool, schema, name).await?;
    let min_caught_up = (0..partition_count)
        .map(|p| progress.get(&p).copied().unwrap_or(-1))
        .min()
        .unwrap_or(latest);

    let events = if min_caught_up >= latest {
        Vec::new()
    } else {
        list_events_for_bounded_context_from_limited(
            pool,
            bounded_context,
            min_caught_up,
            MAX_EVENTS_PER_PARTITION_TICK,
        )
        .await?
    };

    if !events.is_empty() {
        let batch_end = events
            .last()
            .expect("just checked events is non-empty")
            .sequence;
        if dispatcher.tag_key(bounded_context, name).is_none() {
            return Ok(());
        }
        let bc = require_bounded_context(pool, bounded_context).await?;

        for partition_index in 0..partition_count {
            if progress.get(&partition_index).copied().unwrap_or(-1) >= batch_end {
                continue;
            }

            let mut tx = pool.begin().await?;
            let locked: bool =
                sqlx::query_scalar("SELECT pg_try_advisory_xact_lock(hashtext($1)::bigint)")
                    .bind(snapshot_partition_lock_key(
                        bounded_context,
                        name,
                        partition_index,
                    ))
                    .fetch_one(&mut *tx)
                    .await?;
            if !locked {
                // Nothing was written under this transaction - dropping
                // it is a no-op rollback. Another instance (or this
                // one, next tick) owns this partition for now.
                continue;
            }

            // Every event of this partition in one fold, each row read
            // and written once (docs/architecture.md §197). The
            // transaction was already all or nothing.
            let after = progress.get(&partition_index).copied().unwrap_or(-1);
            let mut reached = 0;
            fold_snapshot_chunk_in_tx(
                &mut tx,
                &bc,
                schema,
                dispatcher,
                name,
                &events,
                after,
                Some((partition_index, partition_count)),
                &mut reached,
            )
            .await?;
            let this_partition_progress = after.max(batch_end);

            sqlx::query(sqlx::AssertSqlSafe(format!(
                "INSERT INTO {schema}.snapshot_partition_progress \
                 (snapshot_name, partition_index, caught_up_to, updated_at) \
                 VALUES ($1, $2, $3, now()) \
                 ON CONFLICT (snapshot_name, partition_index) DO UPDATE SET \
                    caught_up_to = GREATEST(\
                        {schema}.snapshot_partition_progress.caught_up_to, EXCLUDED.caught_up_to), \
                    updated_at = now()"
            )))
            .bind(name)
            .bind(partition_index as i32)
            .bind(this_partition_progress)
            .execute(&mut *tx)
            .await?;

            tx.commit().await?;
            progress.insert(partition_index, this_partition_progress);
        }
    }

    // Rolled up regardless of which partitions (if any) this instance
    // won this tick - see `catch_up_partitioned_projection`'s own
    // identical comment. `partition_index < $2` excludes any row left
    // over from a since-decreased `PARTITION_COUNT`.
    let rolled_up: Option<i64> = sqlx::query_scalar(sqlx::AssertSqlSafe(format!(
        "SELECT MIN(caught_up_to) FROM {schema}.snapshot_partition_progress \
         WHERE snapshot_name = $1 AND partition_index < $2"
    )))
    .bind(name)
    .bind(partition_count as i32)
    .fetch_one(pool)
    .await?;
    if let Some(rolled_up) = rolled_up {
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "INSERT INTO {schema}.snapshot_progress (snapshot_name, caught_up_to) \
             VALUES ($1, $2) \
             ON CONFLICT (snapshot_name) DO UPDATE SET \
                caught_up_to = GREATEST({schema}.snapshot_progress.caught_up_to, EXCLUDED.caught_up_to)"
        )))
        .bind(name)
        .bind(rolled_up)
        .execute(pool)
        .await?;
    }

    Ok(())
}

/// `catch_up_partitioned_snapshot`'s own lock key - `partition_lock_key`'s
/// identical `hashtext(...)::bigint` pattern, namespaced by `"snapshot_partition"`
/// rather than `"projection_partition"` so the two families can never
/// collide with each other even if a projection and a snapshot happened
/// to share a name.
fn snapshot_partition_lock_key(
    bounded_context: &str,
    snapshot_name: &str,
    partition_index: u32,
) -> String {
    format!("snapshot_partition:{bounded_context}:{snapshot_name}:{partition_index}")
}

/// `catch_up_partitioned_snapshot`'s own progress read - `list_projection_partition_progress`'s
/// identical shape, for `snapshot_partition_progress` instead.
async fn list_snapshot_partition_progress(
    pool: &Pool,
    schema: &str,
    snapshot_name: &str,
) -> crate::error::Result<std::collections::HashMap<u32, i64>> {
    let rows: Vec<(i32, i64)> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT partition_index, caught_up_to \
         FROM {schema}.snapshot_partition_progress WHERE snapshot_name = $1"
    )))
    .bind(snapshot_name)
    .fetch_all(pool)
    .await?;
    Ok(rows
        .into_iter()
        .map(|(idx, seq)| (idx as u32, seq))
        .collect())
}

/// `RegisterProjection`'s own synchronous counterpart to
/// `catch_up_bounded_context`'s async walk - drift audit finding #3
/// (2026-08-20, see project memory `skilj-drift-audit-2026-08-20` and
/// `ProjectionRegistration::Created`'s own `needs_history_fold` doc
/// comment). Called exactly once, immediately after `upsert_projection`,
/// whenever `register_projection` reports `needs_history_fold: true` -
/// never for a re-registration (that path already goes through
/// `RebuildStaged`/`promote_projection_rebuild` instead) and never for an
/// async projection (`catch_up_bounded_context`'s own periodic walk
/// already backfills those correctly, `caught_up_to.unwrap_or(-1)`
/// treating a freshly created row exactly like a stale one).
///
/// Walks every event the bounded context has ever committed, not just
/// ones matching `projection.consumed_event_types` - the same "let the
/// dispatcher decide" shape `catch_up_bounded_context` itself uses, so
/// this can never disagree with what the async path would have produced
/// had the projection been async instead. One transaction per event,
/// same as `catch_up_bounded_context`'s own per-event loop; this only
/// ever runs once, at first-time registration, so the cost is paid once
/// per projection, not on every poll tick.
///
/// Returns the given `Projection` with `caught_up_to` set to the highest
/// sequence folded - always `Some` when this is called at all, since the
/// caller only calls it when `needs_history_fold` was true, which itself
/// requires at least one matching event to exist.
#[tracing::instrument(skip_all)]
pub async fn fold_history_into_new_sync_projection(
    pool: &Pool,
    projection: &Projection,
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
) -> crate::error::Result<Projection> {
    let bounded_context = &projection.bounded_context.name;
    let default_state_json = dispatcher
        .default_state(bounded_context, &projection.name)
        .unwrap_or_default();
    let owner_tag_key = dispatcher
        .owner_tag_key(bounded_context, &projection.name)
        .flatten();

    let mut caught_up_to = None;
    // History a chunk at a time rather than all at once; each event still
    // commits in its own transaction, exactly as before.
    let mut after = -1;
    loop {
        let events = list_events_for_bounded_context_from_limited(
            pool,
            bounded_context,
            after,
            MAX_EVENTS_PER_CATCH_UP_TICK,
        )
        .await?;
        let exhausted = (events.len() as i64) < MAX_EVENTS_PER_CATCH_UP_TICK;
        if let Some(last) = events.last() {
            after = last.sequence;
        }
        for event in &events {
            let mut tx = pool.begin().await?;
            fold_event_into_new_projection(
                &mut tx,
                projection,
                event,
                dispatcher,
                &default_state_json,
                owner_tag_key,
            )
            .await?;
            tx.commit().await?;
            caught_up_to = Some(event.sequence);
        }
        if exhausted {
            break;
        }
    }

    Ok(Projection {
        caught_up_to,
        ..projection.clone()
    })
}

/// Folds one event into a projection being brought up to date by
/// [`fold_history_into_new_sync_projection`] or
/// [`register_new_sync_projection`]'s locked tail, inside the caller's
/// transaction, and advances its `caught_up_to` (never backwards).
async fn fold_event_into_new_projection(
    tx: &mut Transaction<'_, Postgres>,
    projection: &Projection,
    event: &Event,
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
    default_state_json: &str,
    owner_tag_key: Option<&str>,
) -> crate::error::Result<()> {
    let bounded_context = &projection.bounded_context.name;
    let schema = schema_ident(bounded_context);
    // docs/architecture.md §156: the projection row before any of its
    // state rows, the order catch-up and promotion take them in. The
    // projection is stored async while its history is folded, so
    // catch-up folds it at the same time; taking a state row first could
    // deadlock against a catch-up chunk holding the projection row
    // (§182).
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "SELECT 1 FROM {schema}.projections WHERE name = $1 FOR UPDATE"
    )))
    .bind(&projection.name)
    .execute(&mut **tx)
    .await?;
    let keys = dispatcher
        .keys(bounded_context, &projection.name, event)
        .unwrap_or_default();
    for key in &keys {
        // `as_of_sequence` guard - see `catch_up_bounded_context`'s
        // identical comment. Two instances both registering the same
        // brand-new projection (`register_projection`'s `existing = None`
        // read-then-decide has no claim mechanism) fold the same history
        // at once: whichever commits a key's row first, the other's own
        // `RETURNING` here sees `as_of_sequence` already at
        // `event.sequence` and skips instead of folding again.
        let (as_of_sequence, current_state) = get_or_create_projection_state_for_update(
            &mut **tx,
            &schema,
            &projection.name,
            key,
            default_state_json,
        )
        .await?;
        if as_of_sequence >= event.sequence {
            continue;
        }

        let new_state = match dispatcher.project(
            bounded_context,
            &projection.name,
            &current_state,
            event,
            key,
        ) {
            Some(result) => result?,
            None => current_state,
        };

        apply_projection_fold_update(
            &mut **tx,
            &schema,
            "projection_state",
            "",
            &projection.name,
            key,
            &new_state,
            owner_tag_key,
            event,
        )
        .await?;
    }

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.projections SET caught_up_to = $1 \
         WHERE name = $2 AND (caught_up_to IS NULL OR caught_up_to < $1)"
    )))
    .bind(event.sequence)
    .bind(&projection.name)
    .execute(&mut **tx)
    .await?;
    Ok(())
}

/// Persists a `ProjectionRegistration::Created` - every caller's one
/// entry point for it. An async projection is just stored:
/// `catch_up_bounded_context` backfills it. A sync one goes through
/// [`register_new_sync_projection`].
pub async fn create_projection(
    pool: &Pool,
    projection: &Projection,
    needs_history_fold: bool,
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
) -> crate::error::Result<Projection> {
    if !projection.sync {
        upsert_projection(pool, projection).await?;
        return Ok(projection.clone());
    }
    register_new_sync_projection(pool, projection, needs_history_fold, dispatcher).await
}

/// Registers a brand-new sync projection so that no event is folded out
/// of order or missed (docs/architecture.md §113).
///
/// Live writes fold every event into each *sync* projection they find
/// once they hold the bounded context's sequence lock. Storing the
/// projection as sync and then folding its history left two races:
///
/// - a write landing before the history fold reached a key created that
///   key's row at the new event's sequence, and the fold's
///   `as_of_sequence` guard then skipped every earlier event for it - the
///   key's history silently lost;
/// - a write that had already read the projection list before the row
///   appeared committed a matching event the projection never saw.
///
/// So when there is history to fold, the projection is first stored as
/// *async* - which live writes ignore - and its history folded without
/// holding any lock, one event per transaction as before. Then one
/// transaction takes the sequence lock (the one `promote_projection_rebuild`
/// takes for the same reason), folds the consumed-type events committed
/// since, and stores the projection as sync. Every event at or below the
/// locked sequence is folded by then, and every later write sees the
/// projection. With no history to fold, only that locked step runs; its
/// tail is whatever matching event slipped in after the caller's history
/// check - normally nothing.
pub async fn register_new_sync_projection(
    pool: &Pool,
    projection: &Projection,
    needs_history_fold: bool,
    dispatcher: &dyn crate::plugin::ProjectionDispatcher,
) -> crate::error::Result<Projection> {
    let bounded_context = &projection.bounded_context.name;
    let mut folded_through = None;
    if needs_history_fold {
        let hidden = Projection {
            sync: false,
            caught_up_to: None,
            ..projection.clone()
        };
        upsert_projection(pool, &hidden).await?;
        folded_through = fold_history_into_new_sync_projection(pool, &hidden, dispatcher)
            .await?
            .caught_up_to;
    }

    let default_state_json = dispatcher
        .default_state(bounded_context, &projection.name)
        .unwrap_or_default();
    let owner_tag_key = dispatcher
        .owner_tag_key(bounded_context, &projection.name)
        .flatten();

    let mut tx = pool.begin().await?;
    if needs_history_fold {
        // docs/architecture.md §195: the hidden async row is one a catch-up
        // chunk folds into and holds for a whole chunk. Wait for it before
        // the sequence lock, not under it, where every write to the
        // bounded context would wait too. Nothing takes the sequence lock
        // and then waits on this row: live writes fold only sync
        // projections, and promotion doesn't wait.
        sqlx::query(sqlx::AssertSqlSafe(format!(
            "SELECT 1 FROM {}.projections WHERE name = $1 FOR NO KEY UPDATE",
            schema_ident(bounded_context)
        )))
        .bind(&projection.name)
        .execute(&mut *tx)
        .await?;
    }
    let locked_highest = lock_bounded_context_sequence(&mut tx, bounded_context).await?;
    // With the lock held no event can commit, so this sees the complete
    // tail. Read on `tx` itself: every writer to this bounded context now
    // waits on the lock holding a pooled connection, so a second one might
    // never come (docs/architecture.md §117).
    let consumed_types: std::collections::HashMap<String, EventType> = projection
        .consumed_event_types
        .iter()
        .map(|et| (et.name.clone(), et.clone()))
        .collect();
    let consumed_names: Vec<&str> = consumed_types.keys().map(String::as_str).collect();
    let schema = schema_ident(bounded_context);
    let mut tail = Vec::new();
    let mut after = folded_through.unwrap_or(-1);
    loop {
        let rows: Vec<EventRowAnyType> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
            "SELECT event_type_name, sequence, payload, metadata_type, metadata_version, \
             metadata_client_id, metadata_created_at, metadata_correlation_id, \
             metadata_causation_id, tags, origin_kind, origin_source_content, \
             origin_source_context, origin_command_id FROM {schema}.events \
             WHERE event_type_name = ANY($1) AND sequence > $2 ORDER BY sequence LIMIT $3"
        )))
        .bind(&consumed_names)
        .bind(after)
        .bind(MAX_EVENTS_PER_CATCH_UP_TICK)
        .fetch_all(&mut *tx)
        .await?;
        let exhausted = (rows.len() as i64) < MAX_EVENTS_PER_CATCH_UP_TICK;
        let chunk = events_from_rows(
            &mut tx,
            &projection.bounded_context,
            rows,
            Some(&consumed_types),
        )
        .await?;
        if let Some(last) = chunk.last() {
            after = last.sequence;
        }
        tail.extend(chunk);
        if exhausted {
            break;
        }
    }

    // Every event up to the locked sequence is accounted for once the
    // tail is folded. Left unset when nothing was ever folded, as a new
    // projection with no history always was.
    let stored = Projection {
        sync: true,
        caught_up_to: (folded_through.is_some() || !tail.is_empty() || needs_history_fold)
            .then_some(locked_highest),
        ..projection.clone()
    };
    if !needs_history_fold {
        // The row doesn't exist yet, and `projection_state` rows need it.
        upsert_projection_in_tx(&mut tx, &stored).await?;
    }
    for event in &tail {
        fold_event_into_new_projection(
            &mut tx,
            &stored,
            event,
            dispatcher,
            &default_state_json,
            owner_tag_key,
        )
        .await?;
    }
    upsert_projection_in_tx(&mut tx, &stored).await?;
    tx.commit().await?;
    notify_registration_changed(pool).await;
    Ok(stored)
}

/// SQLSTATE `lock_not_available`: a `NOWAIT` lock found its row taken.
const LOCK_NOT_AVAILABLE: &str = "55P03";

/// Promotes a `building` `ProjectionRebuild` that has caught up to its
/// bounded context's latest committed sequence - `catch_up_bounded_context`'s
/// own last step for each rebuild it walks. One transaction: the rebuild's
/// `schema`/`schema_version`/`sync`/`caught_up_to` replace the live
/// `Projection` row's own, `projection_consumed_event_types` is replaced
/// wholesale from `projection_rebuild_consumed_event_types`, and
/// `projection_rebuild_state`'s content replaces `projection_state`'s
/// (the live projection's old state is discarded - the note above
/// `RegisterProjection`) - then every rebuild-side row is deleted. A
/// rebuild the dispatcher never once resolved (see `catch_up_bounded_context`'s
/// own doc comment) still promotes on schedule; its `projection_rebuild_state`
/// row, if one was ever written, is copied as-is - `"{}"` included.
///
/// Drift audit finding #6 (2026-08-20, see project memory
/// `skilj-drift-audit-2026-08-20`): the caller's own `caught_up_to ==
/// latest` pre-check is only a snapshot taken before this call, not a
/// lock - without one, a new event could commit in the gap between that
/// check and this function's own writes, invisible to both sides
/// forever after (never folded into the rebuild, which this promotes
/// away from `building` before it can be; never folded inline either,
/// since the live projection was still `sync = false` when it arrived).
/// Closed the same way `submit_command`'s own DCB re-check is: locking
/// the bounded context's `{schema}.sequence` row first
/// (`SELECT ... FOR UPDATE`, the identical query, since `next_value`
/// already *is* the latest committed sequence per
/// `SequenceIsGaplessPerBoundedContext` - no separate lookup needed),
/// then re-verifying eligibility under that lock rather than trusting
/// the pre-lock snapshot. This is also what makes
/// `insert_event_and_update_sync_projections_in_tx`'s own
/// `sync_projections` read safe to leave running on the bare pool,
/// outside its own `tx` - see that function's doc comment: every
/// event-insert path already takes this exact lock before reaching that
/// read, so once promotion takes it too, the two can never interleave.
#[tracing::instrument(skip_all, fields(bounded_context = %bounded_context))]
pub async fn promote_projection_rebuild(
    pool: &Pool,
    bounded_context: &str,
    projection_name: &str,
) -> crate::error::Result<bool> {
    let schema = schema_ident(bounded_context);
    let mut tx = pool.begin().await?;

    // The lock this whole fix hinges on - see this function's own doc
    // comment. A read-only peek, not `next_sequence`'s increment: this
    // never allocates a sequence number of its own.
    let (locked_highest,): (i64,) = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT next_value FROM {schema}.sequence FOR UPDATE"
    )))
    .fetch_one(&mut *tx)
    .await?;

    // Every rebuild-side statement below is scoped to `status = 'building'`
    // - promotion only ever ends the building row. A coexisting pending
    // row (the deliberate case `UniqueRebuildPerProjectionAndStatus`
    // names - a non-trivial registration that arrived mid-build) must
    // survive this call untouched: it is still waiting on its own future
    // `RebuildProjection` trigger, unrelated to whichever build just
    // finished.
    let building = projection_rebuild_status_to_str(ProjectionRebuildStatus::Building);

    // docs/architecture.md §195: a catch-up chunk holds these rows for up
    // to `CATCH_UP_EVENTS_PER_TRANSACTION` events. Waiting for it here,
    // with the sequence lock held, stalled every write to the bounded
    // context for that long. So take them without waiting, in the
    // chunk's order, and defer to the next tick when one is busy - the
    // same `false` as a rebuild that isn't caught up yet.
    for lock in [
        format!("SELECT 1 FROM {schema}.projections WHERE name = $1 FOR UPDATE NOWAIT"),
        format!(
            "SELECT 1 FROM {schema}.projection_rebuilds \
             WHERE projection_name = $1 AND status = 'building' FOR UPDATE NOWAIT"
        ),
    ] {
        match sqlx::query(sqlx::AssertSqlSafe(lock))
            .bind(projection_name)
            .execute(&mut *tx)
            .await
        {
            Ok(_) => {}
            Err(sqlx::Error::Database(e)) if e.code().as_deref() == Some(LOCK_NOT_AVAILABLE) => {
                return Ok(false);
            }
            Err(e) => return Err(e.into()),
        }
    }

    let rebuild_row: ProjectionRebuildRow = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT {PROJECTION_REBUILD_COLUMNS} FROM {schema}.projection_rebuilds \
         WHERE projection_name = $1 AND status = $2"
    )))
    .bind(projection_name)
    .bind(building)
    .fetch_one(&mut *tx)
    .await?;

    if rebuild_row.caught_up_to.unwrap_or(-1) != locked_highest {
        // A new event committed after this bounded context's last fold
        // pass but before this lock was acquired - promoting now would
        // strand it. Defer: the next catch_up_bounded_context tick folds
        // it into this still-building rebuild and retries promotion
        // then. `tx` drops here, rolling back the no-op peek lock -
        // nothing was written, nothing to undo.
        return Ok(false);
    }

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.projections SET schema = $1, schema_version = $2, sync = $3, \
         caught_up_to = $4 WHERE name = $5"
    )))
    .bind(&rebuild_row.schema)
    .bind(rebuild_row.schema_version)
    .bind(rebuild_row.sync)
    .bind(rebuild_row.caught_up_to)
    .bind(projection_name)
    .execute(&mut *tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.projection_consumed_event_types WHERE projection_name = $1"
    )))
    .bind(projection_name)
    .execute(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.projection_consumed_event_types (projection_name, event_type_name) \
         SELECT projection_name, event_type_name \
         FROM {schema}.projection_rebuild_consumed_event_types \
         WHERE projection_name = $1 AND status = $2"
    )))
    .bind(projection_name)
    .bind(building)
    .execute(&mut *tx)
    .await?;

    // Every instance the rebuild accumulated replaces every live one -
    // not just one row anymore (§9's "keyed / multi-row Projections"
    // pass): delete the live set for this projection wholesale, then
    // copy the rebuild's own set across in its place, the identical
    // "delete then bulk `INSERT ... SELECT`" shape
    // `projection_consumed_event_types` just above already uses. A
    // rebuild whose dispatcher never resolved even once (see this
    // function's own doc comment) has no rebuild-side rows to copy at
    // all - the live set is simply left empty, not clobbered with
    // nothing pretending to be something.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.projection_state WHERE projection_name = $1"
    )))
    .bind(projection_name)
    .execute(&mut *tx)
    .await?;
    // `owner` carried across too - a promoted rebuild keeps whatever
    // ownership it derived while building, exactly as `state` does
    // (cross-tenant projection read fix, docs/architecture.md's own
    // write-up of this pass). `as_of_sequence` carried across for the
    // identical reason (issue #25's investigation finding) -
    // and load-bearing here, not just consistency: leaving it out would
    // have every promoted row's `as_of_sequence` default back to `-1`
    // while `state` already reflects the rebuild's full replay, so the
    // very next `catch_up_bounded_context` tick would see "never folded"
    // and replay every historical event into already-folded state a
    // second time - the exact bug this whole pass fixes, reintroduced
    // right here if this column were dropped from the copy.
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.projection_state \
         (projection_name, key, state, owner, as_of_sequence, updated_at) \
         SELECT projection_name, key, state, owner, as_of_sequence, updated_at \
         FROM {schema}.projection_rebuild_state WHERE projection_name = $1 AND status = $2"
    )))
    .bind(projection_name)
    .bind(building)
    .execute(&mut *tx)
    .await?;

    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.projection_rebuild_state WHERE projection_name = $1 AND status = $2"
    )))
    .bind(projection_name)
    .bind(building)
    .execute(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.projection_rebuild_consumed_event_types \
         WHERE projection_name = $1 AND status = $2"
    )))
    .bind(projection_name)
    .bind(building)
    .execute(&mut *tx)
    .await?;
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "DELETE FROM {schema}.projection_rebuilds WHERE projection_name = $1 AND status = $2"
    )))
    .bind(projection_name)
    .bind(building)
    .execute(&mut *tx)
    .await?;

    tx.commit().await?;
    // The live `schema` just changed, so every instance's GraphQL type
    // for this projection is stale - this one's included (#69).
    notify_registration_changed(pool).await;
    Ok(true)
}

// --- AccessToken (three of its four variants - see this module's own doc comment) ---

/// `AccessToken.purpose`'s four values, mirroring the Rust `AccessToken`
/// sum type in `access_control` - used by `skilj-rest`'s auth layer to
/// tell "no token with this id exists at all" (401 - an unrecognised
/// credential) from "one does, but not of the variant this route needs"
/// (403 - docs/architecture.md §7.2's "presenting the wrong token
/// variant... is a 403, not a 404") without needing three separate
/// lookups to find out which.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum AccessTokenKind {
    ExternalEvent,
    DirectCreation,
    EventRead,
    Command,
}

impl AccessTokenKind {
    fn as_str(self) -> &'static str {
        match self {
            AccessTokenKind::ExternalEvent => "external_event",
            AccessTokenKind::DirectCreation => "direct_creation",
            AccessTokenKind::EventRead => "event_read",
            AccessTokenKind::Command => "command",
        }
    }

    fn from_str(s: &str) -> Self {
        match s {
            "direct_creation" => AccessTokenKind::DirectCreation,
            "event_read" => AccessTokenKind::EventRead,
            "command" => AccessTokenKind::Command,
            _ => AccessTokenKind::ExternalEvent,
        }
    }
}

/// The one thing a bearer credential's bare `id` can resolve on its own,
/// before anything else: which bounded context's schema actually holds
/// it. See `migrations/0001_init.sql`'s own doc comment on
/// `access_token_index` for why this index has to exist at all now that
/// `access_tokens` itself lives per-context.
async fn resolve_token_bounded_context(
    pool: &Pool,
    id: &str,
) -> crate::error::Result<Option<String>> {
    let row: Option<(String,)> =
        sqlx::query_as("SELECT bounded_context FROM access_token_index WHERE id = $1")
            .bind(id)
            .fetch_optional(pool)
            .await?;
    Ok(row.map(|(bounded_context,)| bounded_context))
}

async fn insert_token_index(
    pool: &Pool,
    id: &str,
    bounded_context: &str,
) -> crate::error::Result<()> {
    sqlx::query("INSERT INTO access_token_index (id, bounded_context) VALUES ($1, $2)")
        .bind(id)
        .bind(bounded_context)
        .execute(pool)
        .await?;
    Ok(())
}

#[derive(sqlx::FromRow)]
struct AccessTokenColumns {
    id: String,
    kind: String,
    secret: String,
    status: String,
    created_at: DateTime<Utc>,
    revoked_at: Option<DateTime<Utc>>,
    event_type_name: Option<String>,
    command_type_name: Option<String>,
    /// One column, all four kinds - see `EventReadToken.scope`'s own doc
    /// comment for the read-side reasoning and
    /// `ExternalEventToken.scope`'s for the write-side one.
    scope: Option<String>,
    /// One column, all four kinds, meaningful only for `event_read` -
    /// see `EventReadToken.start_from`'s own doc comment.
    /// `event_read_start_position_from_str` only ever gets called on
    /// this for a genuine `event_read` row; the other three kinds carry
    /// whatever the column's own `DEFAULT` gave it, read here but never
    /// interpreted.
    start_from: String,
    /// `EventReadToken.start_at_sequence`/`.start_at_time` - two more
    /// columns, all four kinds, meaningful only for `event_read` on the
    /// identical terms `start_from` above already is.
    start_at_sequence: Option<i64>,
    start_at_time: Option<DateTime<Utc>>,
}

struct AccessTokenRow {
    columns: AccessTokenColumns,
    bounded_context: String,
}

/// Resolves the index first (see `resolve_token_bounded_context`), then
/// the token's own full row from that context's schema. `None` when
/// either step finds nothing - a bare `id` genuinely unrecognised either
/// way, the same "doesn't distinguish which" treatment
/// `RestError::UnrecognisedCredential` already gives on the wire.
async fn fetch_access_token_row(
    pool: &Pool,
    id: &str,
) -> crate::error::Result<Option<AccessTokenRow>> {
    // docs/architecture.md §199: a token never moves to another bounded
    // context, so which one holds it is remembered, and every REST request
    // after a token's first reads its row in one round trip instead of
    // two. Only the location is remembered, never the row: status and
    // revocation are read every time. A remembered location with no row
    // (the token or its bounded context deleted since) is forgotten and
    // the index read again, so a stale entry corrects itself.
    if let Some(bounded_context) = remembered_token_context(id) {
        match read_access_token_columns(pool, &bounded_context, id).await {
            Ok(Some(columns)) => {
                return Ok(Some(AccessTokenRow {
                    columns,
                    bounded_context,
                }))
            }
            Ok(None) => forget_token_context(id),
            Err(crate::error::Error::Database(sqlx::Error::Database(e)))
                if e.code().as_deref() == Some("42P01") =>
            {
                forget_token_context(id)
            }
            Err(e) => return Err(e),
        }
    }
    let Some(bounded_context) = resolve_token_bounded_context(pool, id).await? else {
        return Ok(None);
    };
    let columns = read_access_token_columns(pool, &bounded_context, id).await?;
    if columns.is_some() {
        remember_token_context(id, &bounded_context);
    }
    Ok(columns.map(|columns| AccessTokenRow {
        columns,
        bounded_context,
    }))
}

/// One token's own row from `bounded_context`'s schema.
async fn read_access_token_columns(
    pool: &Pool,
    bounded_context: &str,
    id: &str,
) -> crate::error::Result<Option<AccessTokenColumns>> {
    let schema = schema_ident(bounded_context);
    Ok(sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT id, kind, secret, status, created_at, revoked_at, event_type_name, \
         command_type_name, scope, start_from, start_at_sequence, start_at_time \
         FROM {schema}.access_tokens WHERE id = $1"
    )))
    .bind(id)
    .fetch_optional(pool)
    .await?)
}

/// How many token locations [`fetch_access_token_row`] remembers before it
/// starts over - a bound on memory, not a tuning knob: a forgotten
/// location only costs the index read again.
const REMEMBERED_TOKEN_CONTEXTS: usize = 10_000;

/// Token id -> the bounded context whose schema holds it.
fn token_contexts() -> &'static std::sync::Mutex<std::collections::HashMap<String, String>> {
    static CONTEXTS: std::sync::OnceLock<
        std::sync::Mutex<std::collections::HashMap<String, String>>,
    > = std::sync::OnceLock::new();
    CONTEXTS.get_or_init(Default::default)
}

fn remembered_token_context(id: &str) -> Option<String> {
    token_contexts()
        .lock()
        .unwrap_or_else(|e| e.into_inner())
        .get(id)
        .cloned()
}

fn remember_token_context(id: &str, bounded_context: &str) {
    let mut contexts = token_contexts().lock().unwrap_or_else(|e| e.into_inner());
    if contexts.len() >= REMEMBERED_TOKEN_CONTEXTS {
        contexts.clear();
    }
    contexts.insert(id.to_string(), bounded_context.to_string());
}

fn forget_token_context(id: &str) {
    token_contexts()
        .lock()
        .unwrap_or_else(|e| e.into_inner())
        .remove(id);
}

/// See `AccessTokenKind`'s own doc comment - the one lookup `skilj-rest`'s
/// auth layer needs before deciding 401 vs 403.
#[tracing::instrument(skip_all)]
pub async fn access_token_kind(
    pool: &Pool,
    id: &str,
) -> crate::error::Result<Option<AccessTokenKind>> {
    Ok(fetch_access_token_row(pool, id)
        .await?
        .map(|r| AccessTokenKind::from_str(&r.columns.kind)))
}

/// [`access_token_kind`], but only for a token whose stored secret
/// `hashed_secret` (the presented secret, already through
/// `shared::hash_secret`) matches - so the kind, and that the id exists
/// at all, is told only to a caller holding the whole credential
/// (docs/architecture.md §142).
#[tracing::instrument(skip_all)]
pub async fn access_token_kind_for_credential(
    pool: &Pool,
    id: &str,
    hashed_secret: &str,
) -> crate::error::Result<Option<AccessTokenKind>> {
    Ok(fetch_access_token_row(pool, id)
        .await?
        .filter(|r| crate::shared::secret_matches(hashed_secret, &r.columns.secret))
        .map(|r| AccessTokenKind::from_str(&r.columns.kind)))
}

/// Persists a `revoke_token` outcome - a status-only update, addressed by
/// `id` alone (unambiguous: `access_tokens.id` is that schema's own
/// primary key). Resolves which schema holds the row the same way
/// `fetch_access_token_row` does, via `access_token_index`, rather than
/// asking every call site to already know the bounded context -
/// `revoke_token`'s own `token` parameter carries a whole `EventType`/
/// `CommandType`, not a bare name, so re-deriving it here is simpler than
/// threading an extra parameter through. A no-op (not an error) for an
/// `id` that resolves to nothing - unreachable in practice, since the
/// caller already loaded this exact row to build the `AccessToken` it
/// passed to `revoke_token` in the first place.
#[tracing::instrument(skip_all)]
pub async fn revoke_access_token(
    pool: &Pool,
    id: &str,
    revoked_at: DateTime<Utc>,
) -> crate::error::Result<()> {
    let Some(bounded_context) = resolve_token_bounded_context(pool, id).await? else {
        return Ok(());
    };
    let schema = schema_ident(&bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.access_tokens SET status = 'revoked', revoked_at = $1 WHERE id = $2"
    )))
    .bind(revoked_at)
    .bind(id)
    .execute(pool)
    .await?;
    Ok(())
}

/// One insert shared by `insert_external_event_token`/
/// `insert_direct_creation_token`/`insert_event_read_token` below - same
/// "genuinely this wide, not a struct that exists only to satisfy the
/// lint" reasoning `event_store::process_command`'s own `#[allow]` gives.
/// Writes the token's full row into its own context's schema, then the
/// global index entry that makes it findable by `id` alone - in that
/// order, so a failure partway leaves an unreachable orphan row rather
/// than a dangling index entry pointing at nothing. `secret` is the
/// caller's plaintext (`generate_token_secret`'s own output, still held
/// in memory by the caller to hand back once) - only `hash_secret`'s
/// output of it is ever written, per `AccessToken.secret`'s own "stored
/// hashed and never compared in plaintext" text.
#[allow(clippy::too_many_arguments)]
async fn insert_access_token_row(
    pool: &Pool,
    id: &str,
    kind: AccessTokenKind,
    secret: &str,
    status: TokenStatus,
    created_at: DateTime<Utc>,
    revoked_at: Option<DateTime<Utc>>,
    bounded_context: &str,
    event_type_name: &str,
    scope: Option<&str>,
) -> crate::error::Result<()> {
    let schema = schema_ident(bounded_context);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.access_tokens (id, kind, secret, status, created_at, revoked_at, \
         event_type_name, scope) VALUES ($1,$2,$3,$4,$5,$6,$7,$8)"
    )))
    .bind(id)
    .bind(kind.as_str())
    .bind(crate::shared::hash_secret(secret))
    .bind(token_status_to_str(status))
    .bind(created_at)
    .bind(revoked_at)
    .bind(event_type_name)
    .bind(scope)
    .execute(pool)
    .await?;
    insert_token_index(pool, id, bounded_context).await
}

#[tracing::instrument(skip_all)]
pub async fn insert_external_event_token(
    pool: &Pool,
    token: &ExternalEventToken,
) -> crate::error::Result<()> {
    insert_access_token_row(
        pool,
        &token.id,
        AccessTokenKind::ExternalEvent,
        &token.secret,
        token.status,
        token.created_at,
        token.revoked_at,
        &token.event_type.bounded_context.name,
        &token.event_type.name,
        token.scope.as_deref(),
    )
    .await
}

#[tracing::instrument(skip_all)]
pub async fn insert_direct_creation_token(
    pool: &Pool,
    token: &DirectCreationToken,
) -> crate::error::Result<()> {
    insert_access_token_row(
        pool,
        &token.id,
        AccessTokenKind::DirectCreation,
        &token.secret,
        token.status,
        token.created_at,
        token.revoked_at,
        &token.event_type.bounded_context.name,
        &token.event_type.name,
        token.scope.as_deref(),
    )
    .await
}

/// Not built on `insert_access_token_row` - `EventReadToken` is the only
/// one of the three event-type-scoped kinds that also carries
/// `start_from`, so this hand-writes its own `INSERT` the same way
/// `insert_command_token` already does for its own divergent shape (see
/// that function's own doc comment).
#[tracing::instrument(skip_all)]
pub async fn insert_event_read_token(
    pool: &Pool,
    token: &EventReadToken,
) -> crate::error::Result<()> {
    let schema = schema_ident(&token.event_type.bounded_context.name);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.access_tokens (id, kind, secret, status, created_at, revoked_at, \
         event_type_name, scope, start_from, start_at_sequence, start_at_time) \
         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)"
    )))
    .bind(&token.id)
    .bind(AccessTokenKind::EventRead.as_str())
    .bind(crate::shared::hash_secret(&token.secret))
    .bind(token_status_to_str(token.status))
    .bind(token.created_at)
    .bind(token.revoked_at)
    .bind(&token.event_type.name)
    .bind(token.scope.as_deref())
    .bind(event_read_start_position_to_str(token.start_from))
    .bind(token.start_at_sequence)
    .bind(token.start_at_time)
    .execute(pool)
    .await?;
    insert_token_index(pool, &token.id, &token.event_type.bounded_context.name).await
}

/// See `insert_access_token_row` above - not built on it directly, since
/// a `CommandToken` fills `command_type_name` instead of the
/// `event_type_name` every other variant does (see the migration's own
/// `access_tokens` `CHECK` constraint), and the same insert-row-then-index
/// ordering. `token.secret` is hashed before storage the same way
/// `insert_access_token_row` does.
#[tracing::instrument(skip_all)]
pub async fn insert_command_token(pool: &Pool, token: &CommandToken) -> crate::error::Result<()> {
    let schema = schema_ident(&token.command_type.bounded_context.name);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.access_tokens (id, kind, secret, status, created_at, revoked_at, \
         command_type_name, scope) VALUES ($1,$2,$3,$4,$5,$6,$7,$8)"
    )))
    .bind(&token.id)
    .bind(AccessTokenKind::Command.as_str())
    .bind(crate::shared::hash_secret(&token.secret))
    .bind(token_status_to_str(token.status))
    .bind(token.created_at)
    .bind(token.revoked_at)
    .bind(&token.command_type.name)
    .bind(token.scope.as_deref())
    .execute(pool)
    .await?;
    insert_token_index(pool, &token.id, &token.command_type.bounded_context.name).await
}

/// `None` when either no token has this `id` at all, or one does but
/// isn't the expected kind - callers that need to tell those two apart
/// (for the 401-vs-403 split - see `AccessTokenKind`'s own doc comment)
/// call `access_token_kind` first. Covers `get_external_event_token`/
/// `get_direct_creation_token`, identical apart from the `kind` string
/// and return type - both resolve `event_type_name` against
/// `event_types` into an `event_type` field and carry `scope` alike
/// (cross-tenant read/write fix, docs/architecture.md's own write-up of
/// these passes). `get_event_read_token` used to share this shape too,
/// back when all three carried nothing but `scope` beyond the common
/// base - `start_from` (this pass's own write-up) broke that symmetry,
/// so it now stays hand-written below the same way `get_command_token`
/// already does for its own divergent shape.
macro_rules! get_event_type_access_token {
    ($fn_name:ident, $return_type:ident, $kind:literal) => {
        #[tracing::instrument(skip_all)]
        pub async fn $fn_name(pool: &Pool, id: &str) -> crate::error::Result<Option<$return_type>> {
            let Some(row) = fetch_access_token_row(pool, id).await? else {
                return Ok(None);
            };
            if row.columns.kind != $kind {
                return Ok(None);
            }
            let event_type_name = row
                .columns
                .event_type_name
                .expect(concat!($kind, " access_tokens row without event_type_name"));
            let event_type =
                require_event_type(pool, &row.bounded_context, &event_type_name).await?;
            Ok(Some($return_type {
                id: row.columns.id,
                secret: row.columns.secret,
                status: token_status_from_str(&row.columns.status),
                created_at: row.columns.created_at,
                revoked_at: row.columns.revoked_at,
                event_type,
                scope: row.columns.scope,
            }))
        }
    };
}
get_event_type_access_token!(
    get_external_event_token,
    ExternalEventToken,
    "external_event"
);
get_event_type_access_token!(
    get_direct_creation_token,
    DirectCreationToken,
    "direct_creation"
);

/// See `get_external_event_token`'s own doc comment's note on why this
/// one stays hand-written - the only difference from what the macro
/// generates is the extra `start_from` field, read via
/// `event_read_start_position_from_str`.
#[tracing::instrument(skip_all)]
pub async fn get_event_read_token(
    pool: &Pool,
    id: &str,
) -> crate::error::Result<Option<EventReadToken>> {
    let Some(row) = fetch_access_token_row(pool, id).await? else {
        return Ok(None);
    };
    if row.columns.kind != "event_read" {
        return Ok(None);
    }
    let event_type_name = row
        .columns
        .event_type_name
        .expect("event_read access_tokens row without event_type_name");
    let event_type = require_event_type(pool, &row.bounded_context, &event_type_name).await?;
    Ok(Some(EventReadToken {
        id: row.columns.id,
        secret: row.columns.secret,
        status: token_status_from_str(&row.columns.status),
        created_at: row.columns.created_at,
        revoked_at: row.columns.revoked_at,
        event_type,
        scope: row.columns.scope,
        start_from: event_read_start_position_from_str(&row.columns.start_from),
        start_at_sequence: row.columns.start_at_sequence,
        start_at_time: row.columns.start_at_time,
    }))
}

/// See `get_external_event_token`'s own doc comment - same shape and
/// `None` reasoning, resolving `command_type_name` against
/// `command_types` instead of `event_type_name` against `event_types`.
#[tracing::instrument(skip_all)]
pub async fn get_command_token(
    pool: &Pool,
    id: &str,
) -> crate::error::Result<Option<CommandToken>> {
    let Some(row) = fetch_access_token_row(pool, id).await? else {
        return Ok(None);
    };
    if row.columns.kind != "command" {
        return Ok(None);
    }
    let command_type_name = row
        .columns
        .command_type_name
        .expect("command access_tokens row without command_type_name");
    let command_type = require_command_type(pool, &row.bounded_context, &command_type_name).await?;
    Ok(Some(CommandToken {
        id: row.columns.id,
        secret: row.columns.secret,
        status: token_status_from_str(&row.columns.status),
        created_at: row.columns.created_at,
        revoked_at: row.columns.revoked_at,
        command_type,
        scope: row.columns.scope,
    }))
}

// --- ReadCursor ---

#[derive(sqlx::FromRow)]
struct ReadCursorRow {
    ack_mode: String,
    sequence: i64,
    updated_at: DateTime<Utc>,
    checked_out_at: Option<DateTime<Utc>>,
}

/// Unlike `access_tokens`, no index/bounded-context-resolution step is
/// needed here: every caller already holds the full `EventReadToken` (and
/// so its own `event_type.bounded_context.name`) by the time this is
/// called - token resolution (which does need the index) already
/// happened first, in `get_event_read_token` above. Generic over `impl
/// sqlx::PgExecutor` (the same generalisation `insert_event` itself
/// already has) so `GET /v1/events/consume?mode=manual` can call this
/// inside the same transaction `lock_read_cursor_for_consume`'s own
/// advisory lock spans (issue #25's investigation,
/// docs/architecture.md §53) - see that function's own doc comment for
/// why a plain call against `&Pool` here wouldn't actually be protected
/// by a lock taken on a different pooled connection.
#[tracing::instrument(skip_all)]
pub async fn get_read_cursor(
    executor: impl sqlx::PgExecutor<'_>,
    token: &EventReadToken,
) -> crate::error::Result<Option<ReadCursor>> {
    let schema = schema_ident(&token.event_type.bounded_context.name);
    let row: Option<ReadCursorRow> = sqlx::query_as(sqlx::AssertSqlSafe(format!(
        "SELECT ack_mode, sequence, updated_at, checked_out_at \
         FROM {schema}.read_cursors WHERE token_id = $1"
    )))
    .bind(&token.id)
    .fetch_optional(executor)
    .await?;
    Ok(row.map(|r| ReadCursor {
        token: token.clone(),
        ack_mode: ack_mode_from_str(&r.ack_mode),
        sequence: r.sequence,
        updated_at: r.updated_at,
        checked_out_at: r.checked_out_at,
    }))
}

/// The primitive that actually closes the `manual_ack` claim race
/// (issue #25's investigation, docs/architecture.md §53) - not
/// a row lock on `read_cursors` (a `SELECT ... FOR UPDATE` protects
/// nothing for a token's very first-ever call, before any row exists to
/// lock - proven by a real concurrent test that failed exactly there
/// before this fix, not assumed). `pg_advisory_xact_lock`, the identical
/// primitive `migrate_idempotency_keys_client_id_scoping` already
/// establishes - deliberately blocking, not `pg_try_advisory_xact_lock`:
/// two callers racing the same token should serialize (one waits a few
/// milliseconds for the other's short transaction to commit), not have
/// one immediately give up. Held for the rest of the caller's own
/// transaction, released automatically on commit or rollback. Must be
/// called on the SAME transaction whose own later `get_read_cursor`/
/// `apply_cursor_update` calls it's meant to protect - a bare
/// `pg_advisory_lock` against a `&Pool` would make this meaningless (the
/// lock and the work it protects could each land on a different pooled
/// connection entirely), the identical failure mode that function's own
/// doc comment already warns about for the migration guard.
#[tracing::instrument(skip_all)]
pub async fn lock_read_cursor_for_consume(
    tx: &mut Transaction<'_, Postgres>,
    token: &EventReadToken,
) -> crate::error::Result<()> {
    let key = format!(
        "read_cursor:{}:{}",
        token.event_type.bounded_context.name, token.id
    );
    sqlx::query("SELECT pg_advisory_xact_lock(hashtext($1)::bigint)")
        .bind(key)
        .execute(&mut **tx)
        .await?;
    Ok(())
}

async fn upsert_read_cursor(
    executor: impl sqlx::PgExecutor<'_>,
    cursor: &ReadCursor,
) -> crate::error::Result<()> {
    let schema = schema_ident(&cursor.token.event_type.bounded_context.name);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "INSERT INTO {schema}.read_cursors (token_id, ack_mode, sequence, updated_at, checked_out_at) \
         VALUES ($1,$2,$3,$4,$5) \
         ON CONFLICT (token_id) DO UPDATE SET \
            ack_mode = EXCLUDED.ack_mode, sequence = EXCLUDED.sequence, \
            updated_at = EXCLUDED.updated_at, checked_out_at = EXCLUDED.checked_out_at"
    )))
    .bind(&cursor.token.id)
    .bind(ack_mode_to_str(cursor.ack_mode))
    .bind(cursor.sequence)
    .bind(cursor.updated_at)
    .bind(cursor.checked_out_at)
    .execute(executor)
    .await?;
    Ok(())
}

/// Persists whatever `event_store::consume_events` decided to do to a
/// token's `ReadCursor` - see `CursorUpdate`'s own doc comment for why
/// that decision and this persistence step are two separate functions
/// (the pure/no-I/O split every rule in this crate keeps). Generic over
/// `impl sqlx::PgExecutor` (the same generalisation `insert_event` itself
/// already has) so `GET /v1/events/consume?mode=manual` can call this
/// inside the same transaction `get_read_cursor_for_update`'s own row
/// lock spans (issue #25's investigation, docs/architecture.md
/// §53) - without that, the read and this write would each be free to
/// land on a different pooled connection, making the lock meaningless
/// (the identical failure mode `migrate_idempotency_keys_client_id_scoping`'s
/// own doc comment warns about for a bare `pg_advisory_lock`).
#[tracing::instrument(skip_all)]
pub async fn apply_cursor_update(
    executor: impl sqlx::PgExecutor<'_>,
    token: &EventReadToken,
    update: &CursorUpdate,
) -> crate::error::Result<()> {
    match update {
        CursorUpdate::Created(cursor) => upsert_read_cursor(executor, cursor).await,
        CursorUpdate::Advanced {
            sequence,
            updated_at,
        } => {
            let schema = schema_ident(&token.event_type.bounded_context.name);
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "UPDATE {schema}.read_cursors SET sequence = $1, updated_at = $2 WHERE token_id = $3"
            )))
            .bind(sequence)
            .bind(updated_at)
            .bind(&token.id)
            .execute(executor)
            .await?;
            Ok(())
        }
        // issue #25's investigation (docs/architecture.md §53) -
        // `sequence`/`updated_at` deliberately untouched: a claim alone
        // never moves the cursor's own position, only `AcknowledgeEvents`
        // does.
        CursorUpdate::Claimed { checked_out_at } => {
            let schema = schema_ident(&token.event_type.bounded_context.name);
            sqlx::query(sqlx::AssertSqlSafe(format!(
                "UPDATE {schema}.read_cursors SET checked_out_at = $1 WHERE token_id = $2"
            )))
            .bind(checked_out_at)
            .bind(&token.id)
            .execute(executor)
            .await?;
            Ok(())
        }
        CursorUpdate::Unchanged => Ok(()),
    }
}

/// Persists an `AcknowledgeEvents` outcome directly - `acknowledge_events`
/// itself only returns the new `(sequence, updated_at)` pair (it has no
/// `CursorUpdate` variant of its own; see its doc comment), so there's no
/// enum to dispatch on the way `apply_cursor_update` above does.
/// `checked_out_at` is cleared unconditionally alongside `sequence`/
/// `updated_at` - `rule AcknowledgeEvents`' own `ensures` block does the
/// same, unconditionally, regardless of whether a live claim was even
/// held (issue #25's investigation, docs/architecture.md §53).
#[tracing::instrument(skip_all)]
pub async fn record_acknowledgement(
    executor: impl sqlx::PgExecutor<'_>,
    token: &EventReadToken,
    sequence: i64,
    updated_at: DateTime<Utc>,
) -> crate::error::Result<()> {
    let schema = schema_ident(&token.event_type.bounded_context.name);
    sqlx::query(sqlx::AssertSqlSafe(format!(
        "UPDATE {schema}.read_cursors SET sequence = $1, updated_at = $2, checked_out_at = NULL \
         WHERE token_id = $3"
    )))
    .bind(sequence)
    .bind(updated_at)
    .bind(&token.id)
    .execute(executor)
    .await?;
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::{effective_statement_cache_capacity, schema_ident};

    #[test]
    fn the_statement_cache_capacity_is_explicit_then_the_urls_then_sqlxs() {
        let url = "postgres://u@h/d?sslmode=disable&statement-cache-capacity=250";
        assert_eq!(effective_statement_cache_capacity(url, Some(7)), 7);
        assert_eq!(effective_statement_cache_capacity(url, None), 250);
        assert_eq!(
            effective_statement_cache_capacity(&format!("{url}&statement-cache-capacity=3"), None),
            3
        );
        assert_eq!(
            effective_statement_cache_capacity("postgres://u@h/d?sslmode=disable", None),
            100
        );
        assert_eq!(
            effective_statement_cache_capacity("postgres://u@h/d", None),
            100
        );
    }

    #[test]
    fn schema_ident_quotes_and_escapes() {
        assert_eq!(schema_ident("banking"), "\"bc_banking\"");
        assert_eq!(
            schema_ident("x\"; DROP SCHEMA public; --"),
            "\"bc_x\"\"; DROP SCHEMA public; --\""
        );
    }

    #[test]
    fn the_capability_limit_is_one_number() {
        // `access_control::MAX_CAPABILITIES` (the pure check) and
        // `MAX_CAPABILITIES_PER_MAPPING` (the atomic SQL guard) are the one
        // `invariant CapabilitiesAreWellFormed` limit stated in two places;
        // this keeps them from drifting apart.
        assert_eq!(
            crate::access_control::MAX_CAPABILITIES,
            super::MAX_CAPABILITIES_PER_MAPPING
        );
    }
}