yeti_types/resource/

context.rs

//! `Context` — the request pipeline object, restructured into 5 typed blocks
//! per ADR-011 (Stage 2/3/6).
//!
//! The five blocks:
//!
//! - **Required:** `request`, `lineage`
//! - **Optional middleware-derived:** `routing`, `identity`
//! - **Host-only** (not crossing the WIT ABI): `backend_manager`, `pubsub_lookup`,
//!   `requested_format`, `json_body`, `root_directory`
//!
//! `Response` is **not** a field of Context — it's instantiated alongside Context
//! by the request pipeline and threaded through dispatch separately. In WIT it's
//! an owned resource handle; here it's a value-typed [`Response`].

use ecow::EcoString;
use std::collections::HashMap;
use std::sync::Arc;
// `OnceLock` (not `OnceCell`) so `Context: Sync` holds — customer
// resource bodies routinely pass `&Context` across `.await` points,
// which requires `Sync`. wasm32-wasip2 is single-threaded so the
// internal lock is uncontended; cost is negligible.
#[cfg(target_arch = "wasm32")]
use std::sync::OnceLock;

use bytes::Bytes;

use super::permission::TablePermission;
use crate::auth::{Access, AuthIdentity};
use crate::error::{Result, YetiError};

// ============================================================================
// Lazy WIT backing (wasm32 only)
//
// On the wasm guest side, the host hands the customer's dispatch
// function an owned `Context` handle (mirrors wasi:http). The
// guest-side bindgen-generated handle type doesn't live in
// yeti-types — but yeti-types' `Context` needs to defer field
// materialization until the customer reads a field. To square that,
// we define an abstract `WitContextHandle` trait here and let the
// `lib_gen_wasm`-emitted glue impl it on the bindgen-generated type.
// Customer-facing `Context` accessors then call through `Box<dyn
// WitContextHandle>` with one-time caching via `OnceCell`.
// ============================================================================

/// Wasm-guest-only: abstracts the WIT `borrow<context>` handle.
/// `lib_gen_wasm`-generated guest code implements this on the
/// bindgen-generated `Context` resource type so `yeti_types::resource::
/// Context` can hold a trait-object handle and lazy-fetch fields via
/// canonical-ABI accessor crossings.
///
/// Each `fetch_*` method is called at most once per Context (cached
/// in [`LazyBacking`] `OnceCell`s).
#[cfg(target_arch = "wasm32")]
pub trait WitContextHandle: Send + Sync {
    fn fetch_request(&self) -> Request;
    fn fetch_routing(&self) -> Option<Routing>;
    fn fetch_lineage(&self) -> Lineage;
    fn fetch_identity(&self) -> Option<Identity>;
}

/// Wasm-guest-only: the per-Context lazy backing. Holds the WIT
/// handle behind `Box<dyn>` and per-field `OnceCell`s that cache the
/// first fetch. Only `request` and `routing` are lazy — `lineage`
/// and `identity` are eager-fetched at construction because they're
/// tiny and almost universally read (logging/authz).
///
/// Construction is via [`Context::from_wit_handle`] (called by
/// `lib_gen_wasm`-generated `invoke_service`). Accessor methods on
/// `Context` check `lazy` first; if present and the relevant
/// `OnceCell` is uninitialized, they call through `handle` and cache.
/// If `lazy` is `None`, the eager fields on `Context` are used
/// (e.g., for `placeholder()` contexts used in queue-fn invocations).
#[cfg(target_arch = "wasm32")]
pub(crate) struct LazyBacking {
    pub(crate) handle: Box<dyn WitContextHandle>,
    pub(crate) request: OnceLock<Request>,
    pub(crate) routing: OnceLock<Option<Routing>>,
}

#[cfg(target_arch = "wasm32")]
impl std::fmt::Debug for LazyBacking {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("LazyBacking")
            .field("handle", &"<dyn WitContextHandle>")
            .finish_non_exhaustive()
    }
}

// ============================================================================
// Sub-records — the five typed blocks
// ============================================================================

/// Inbound request block: verb, protocol, path, body, headers, and parsed query.
///
/// `path` and `headers` are stored as `Arc` so that `Context::clone()` —
/// which fires in WebSocket dispatch — is a refcount bump rather than a deep
/// copy. The initial allocation per request is identical; the gain is on the
/// clone path (WS upgrade, auth middleware that clones context, etc.).
#[derive(Clone, Debug)]
pub struct Request {
    /// HTTP method (or the protocol-equivalent verb for non-HTTP transports).
    pub verb: http::Method,
    /// Wire protocol the request arrived on (REST / `WebSocket` / MQTT / …).
    pub protocol: crate::schema::Protocol,
    /// Request path, app-prefix included (e.g. `/yeti-auth/Users/alice`).
    /// `EcoString`: inline (zero heap) for paths ≤ 15 bytes, Arc-backed clone
    /// for longer paths. Either way `Context::clone()` is O(1).
    pub path: EcoString,
    /// Raw request body bytes (refcounted; cheap to clone).
    pub body: Bytes,
    /// Inbound request headers.
    /// `Arc` so `Context::clone()` is a refcount bump, not a full `HeaderMap` copy.
    pub headers: Arc<http::HeaderMap>,
    /// Parsed query string, plus synthetic keys routing injects downstream.
    pub query: HashMap<String, String>,
}

impl Default for Request {
    fn default() -> Self {
        Self {
            verb: http::Method::GET,
            protocol: crate::schema::Protocol::default(),
            path: EcoString::new(),
            body: Bytes::new(),
            headers: Arc::new(http::HeaderMap::new()),
            query: HashMap::new(),
        }
    }
}

/// Outbound response block: status, headers, and body bytes.
#[derive(Clone, Debug, Default)]
pub struct Response {
    /// HTTP status code.
    pub status: u16,
    /// Response headers.
    pub headers: http::HeaderMap,
    /// Response body bytes (refcounted; cheap to clone).
    pub body: Bytes,
}

/// Request-lineage block: identifiers and clock stamp for tracing/correlation.
#[derive(Clone, Debug, Default)]
pub struct Lineage {
    /// Request id (`UUIDv7`), stamped by the inbound router.
    pub request_id: String,
    /// Parent request id when triggered by another request; `None` at the root.
    pub parent: Option<String>,
    /// Cross-request correlation id (e.g. inbound `X-Correlation-Id`).
    pub correlation: Option<String>,
    /// Deployment hash of the producing yeti-fabric node (`"local"` in dev).
    pub deployment: String,
    /// Hybrid Logical Clock stamp at request receipt.
    pub hlc: Hlc,
}

/// Hybrid Logical Clock stamp — physical time plus a logical tiebreaker and node id.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct Hlc {
    /// Physical time component (milliseconds since the Unix epoch).
    pub physical: u64,
    /// Logical counter, incremented for events sharing a `physical` tick.
    pub logical: u32,
    /// Originating node id, breaking ties across nodes.
    pub node_id: u32,
}

/// Routing block: app/resource/database identifiers settled at request-routing time.
#[derive(Clone, Debug)]
pub struct Routing {
    /// Application id — first URL segment, e.g. `"yeti-auth"`.
    pub app: Arc<str>,
    /// Resource id — second URL segment, e.g. `"Users"`. For table-backed
    /// resources this is the table name.
    pub resource: Arc<str>,
    /// Database name — settled at request-routing time from the
    /// `TableDefinition.database` (or app default `"data"` when the
    /// table doesn't specify). **Distinct from `app`**: the
    /// `@database` schema directive can point a table at a database
    /// shared across apps. Permission checks read this field.
    pub database: Arc<str>,
    /// `None` = collection-level operation; `Some(k)` = single-record operation.
    pub key: Option<String>,
}

/// Resolved identity block — the post-auth view that crosses the WIT ABI.
#[derive(Clone, Debug)]
pub struct Identity {
    /// Authenticated principal (username / email / service id); `None` if anonymous.
    pub principal: Option<String>,
    /// Resolved role names.
    pub roles: Vec<String>,
    /// Resolved permission bundle (`super_user` bit + per-resource op masks).
    pub permissions: Permissions,
    /// Authentication method that produced this identity.
    pub auth_method: AuthMethod,
}

/// Resolved permission bundle: a `super_user` override plus per-resource op masks.
#[derive(Clone, Debug, Default)]
pub struct Permissions {
    /// When set, grants all operations on all resources (bypasses `per_resource`).
    pub super_user: bool,
    /// Per-resource operation grants.
    pub per_resource: Vec<ResourcePerm>,
}

/// One resource's operation grant within a [`Permissions`] bundle.
#[derive(Clone, Debug)]
pub struct ResourcePerm {
    /// Resource (table) name the mask applies to.
    pub resource: String,
    /// Allowed operations on `resource`.
    pub ops: OpsMask,
}

/// Per-resource operation permission bitfield. Plain u8 wrapper to avoid
/// a workspace-level bitflags dep at the foundation layer.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub struct OpsMask(pub u8);

impl OpsMask {
    /// Create / insert a record.
    pub const CREATE: Self = Self(1 << 0);
    /// Read / query a record.
    pub const READ: Self = Self(1 << 1);
    /// Update an existing record.
    pub const UPDATE: Self = Self(1 << 2);
    /// Delete a record.
    pub const DELETE: Self = Self(1 << 3);
    /// Subscribe to a record/collection change stream.
    pub const SUBSCRIBE: Self = Self(1 << 4);
    /// Publish to a topic/collection.
    pub const PUBLISH: Self = Self(1 << 5);
    /// Open a connection (`WebSocket` / MQTT).
    pub const CONNECT: Self = Self(1 << 6);

    /// An empty mask (no operations granted).
    #[must_use]
    pub const fn empty() -> Self {
        Self(0)
    }
    /// `true` if `self` grants every bit set in `other`.
    #[must_use]
    pub const fn contains(self, other: Self) -> bool {
        self.0 & other.0 == other.0
    }
    /// Set the bits in `other`.
    pub const fn insert(&mut self, other: Self) {
        self.0 |= other.0;
    }
    /// Clear the bits in `other`.
    pub const fn remove(&mut self, other: Self) {
        self.0 &= !other.0;
    }
}

impl std::ops::BitOr for OpsMask {
    type Output = Self;
    fn bitor(self, rhs: Self) -> Self {
        Self(self.0 | rhs.0)
    }
}

/// The authentication scheme that produced a request's identity.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum AuthMethod {
    /// Unauthenticated (anonymous / public endpoint).
    #[default]
    None,
    /// HTTP Basic credentials.
    Basic,
    /// JWT bearer token.
    Jwt,
    /// OAuth session.
    OAuth,
    /// API key.
    ApiKey,
    /// Internal service token.
    ServiceToken,
}

// ============================================================================
// AuthBlock — aggregates the three authentication/authorization fields.
// ============================================================================

/// Authentication and authorization state aggregated into one nested block.
///
/// Holds the three host-side auth-related fields that flow through the
/// request pipeline. Each sub-field carries distinct semantic content:
///
/// - [`identity_input`](Self::identity_input) — INPUT from a credential
///   provider (Basic/JWT/OAuth/mTLS). Set by the auth pipeline's
///   `AuthProvider::authenticate()`. Represents WHO the wire claims to
///   be, before role resolution. Renamed from the flat `auth_identity`
///   field to disambiguate from [`Context::identity`] (the WIT-mirrored
///   *output* shape exposed to wasm apps).
/// - [`access`](Self::access) — OUTPUT after the auth middleware
///   resolves `identity_input` into a `User` + `Role`. Closed enum
///   ([`Access`]). All RBAC helpers (`can_read_table`,
///   `can_update_table`, attribute filtering) dispatch through this.
/// - [`permission`](Self::permission) — Per-request cached
///   [`TablePermission`] computed once by the auth layer for the
///   currently-routed table and consumed on the dispatch hot path.
///   `FullAccess` (super-user / dev mode / wildcard) or
///   `AttributeRestricted` (narrow read/write lists). `Public`
///   short-circuits all RBAC for `@export(public:[...])` tables.
///
/// **Relationship to `Context.identity`**: That top-level field is the
/// pure-WIT *resolved* view (principal + roles + permissions bitmask
/// shape) crossing the WIT boundary to wasm apps. `AuthBlock` is the
/// host-side intermediate state used during dispatch. They overlap in
/// content but differ in lifetime and WIT surface.
#[derive(Clone, Debug)]
pub struct AuthBlock {
    /// Wire-level authentication claim, set by the auth pipeline before
    /// role resolution. `None` for unauthenticated requests.
    pub identity_input: Option<AuthIdentity>,
    /// Resolved user + role after the auth middleware. `Access::None`
    /// when unauthenticated.
    pub access: Access,
    /// Pre-computed table permission for the routed table, cached on
    /// the request hot path.
    pub permission: TablePermission,
}

impl Default for AuthBlock {
    fn default() -> Self {
        Self {
            identity_input: None,
            access: Access::None,
            permission: TablePermission::FullAccess,
        }
    }
}

/// Result of dispatching a request: either a final response or a delegation.
#[derive(Debug)]
pub enum Outcome {
    /// Terminal response — send it to the client.
    Respond(Response),
    /// Re-dispatch to another app/resource per the [`DelegateSpec`].
    Delegate(DelegateSpec),
}

/// Target of an [`Outcome::Delegate`] — the app/resource/key to re-dispatch to.
#[derive(Clone, Debug)]
pub struct DelegateSpec {
    /// Target application id.
    pub app: String,
    /// Target resource (table) name.
    pub resource: String,
    /// Target record key; `None` for a collection-level operation.
    pub key: Option<String>,
}

// ============================================================================
// Context — five-block, with host-only side-channel fields
// ============================================================================

/// Request context. Five typed blocks per ADR-011 plus host-only side fields.
///
/// The shape after Wave-3 collapse (2026-05-25):
///
/// - **WIT-mirrored blocks** crossing the ABI: `request`, `lineage`,
///   `routing` (optional), `identity` (optional — the resolved view).
/// - **Host-side auth state** consumed by the dispatch pipeline:
///   [`auth: AuthBlock`](AuthBlock) holding `identity_input` (wire-level
///   credential), `access` (resolved `User`+`Role`), and `permission`
///   (per-request `TablePermission` cache).
/// - **Host-only side-channel** for backend manager, pubsub lookup,
///   parsed JSON body, requested content-type, and rootDirectory.
///
/// `auth.identity_input` is renamed from the old flat `auth_identity`
/// field to avoid colliding with the WIT-side `identity` block above
/// (which is the post-auth *resolved* shape that crosses the ABI).
///
/// `Clone` is implemented manually so the wasm-only `LazyBacking`
/// field can be reset on clone (the underlying `Box<dyn
/// WitContextHandle>` isn't itself `Clone`). Cloned wasm Contexts
/// inherit eager fields only — host code paths use Clone freely.
pub struct Context {
    // ── 5-block shape (mirrors WIT yeti:types/core record context) ──
    // ── WIT-backed fields ───────────────────────────────────────────────
    //
    // These four cross the WIT canonical-ABI boundary on wasm32
    // (lazy-fetched via WitContextHandle for request/routing, eager
    // for lineage/identity). Access through the accessor methods on
    // this impl — direct field access is `pub(crate)` only so the
    // host crate's bridge can construct/mutate them. Migration debt
    // tracker: all external reads route through accessors per the
    // wasi:http resource pattern.
    pub(crate) request: Request,
    pub(crate) lineage: Lineage,
    pub(crate) routing: Option<Routing>,
    pub(crate) identity: Option<Identity>,

    /// Host-side authentication/authorization state consumed by the dispatch pipeline.
    pub auth: AuthBlock,

    // ── Host-only side-channel — not crossing the WIT ABI ──
    /// Negotiated response content-type (from the `Accept` header).
    pub requested_format: crate::content_type::ContentType,
    /// Request body parsed as JSON — lazily on first access and cached.
    /// Read via [`Context::json_body`] / `require_json_body`; requests that
    /// never touch it (e.g. public/super-user writes) never pay the parse.
    /// Boxed so the cell is one pointer wide: `OnceLock<Option<Box<_>>>` is
    /// smaller than the bare `Option<Value>` it replaced, keeping the read
    /// path (which never parses) from paying for a fatter `Context`.
    json_body: std::sync::OnceLock<Option<Box<serde_json::Value>>>,
    /// Backend manager for table access; `None` on contexts without storage.
    pub backend_manager: Option<Arc<crate::backend::BackendManager>>,
    /// Deployment root directory (rootDirectory), used to resolve on-disk paths.
    pub root_directory: Arc<str>,
    /// Lookup for a table's `PubSub` manager; `None` when pub/sub is unavailable.
    pub pubsub_lookup: Option<crate::plugins::PubSubLookupFn>,

    // ── Wasm-guest lazy backing — only present when constructed via
    //    [`Context::from_wit_handle`]. Accessor methods (`path`,
    //    `headers`, `routing`, ...) check this first and lazy-fetch
    //    if set. `None` means the Context uses the eager fields above
    //    (host build, or wasm-side placeholder).
    #[cfg(target_arch = "wasm32")]
    pub(crate) lazy: Option<LazyBacking>,
}

impl std::fmt::Debug for Context {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Context")
            .field("request", &self.request)
            .field("lineage", &self.lineage)
            .field("routing", &self.routing)
            .field("identity", &self.identity)
            .field("auth", &self.auth)
            .field("requested_format", &self.requested_format)
            .field("json_body", &self.json_body.get())
            .field("root_directory", &self.root_directory)
            .finish_non_exhaustive()
    }
}

impl Clone for Context {
    fn clone(&self) -> Self {
        Self {
            request: self.request.clone(),
            lineage: self.lineage.clone(),
            routing: self.routing.clone(),
            identity: self.identity.clone(),
            auth: self.auth.clone(),
            requested_format: self.requested_format,
            json_body: self.json_body.clone(),
            backend_manager: self.backend_manager.clone(),
            root_directory: Arc::clone(&self.root_directory),
            pubsub_lookup: self.pubsub_lookup.clone(),
            // Wasm-only: lazy backing is NOT cloned — the
            // `Box<dyn WitContextHandle>` has unique ownership of
            // the WIT resource handle, and a clone would result in
            // double-drop of the canonical-ABI resource. Cloned
            // wasm Contexts behave as if constructed from the eager
            // fields only.
            #[cfg(target_arch = "wasm32")]
            lazy: None,
        }
    }
}

impl Context {
    /// Create a Context from a raw inbound request. Subsequent layers fill in
    /// `routing` (router), `identity` (auth pipeline), and other side fields.
    pub fn from_request(
        method: http::Method,
        path: impl Into<EcoString>,
        body: Bytes,
        headers: http::HeaderMap,
    ) -> Self {
        Self {
            // Nested 5-block shape
            request: Request {
                verb: method,
                protocol: crate::schema::Protocol::default(),
                path: path.into(),
                body,
                headers: Arc::new(headers),
                query: HashMap::new(),
            },
            lineage: Lineage::default(),
            routing: None,
            identity: None,
            auth: AuthBlock::default(),
            // Host-only side fields
            requested_format: crate::content_type::ContentType::Json,
            json_body: std::sync::OnceLock::new(),
            backend_manager: None,
            root_directory: Arc::from(""),
            pubsub_lookup: None,
            #[cfg(target_arch = "wasm32")]
            lazy: None,
        }
    }

    /// Wasm-guest constructor: wraps an owned WIT handle for lazy
    /// field fetching. Eager fields default-empty; accessor methods
    /// fetch + cache via the handle on first call.
    ///
    /// Emitted by `lib_gen_wasm`'s `invoke_service` so the customer's
    /// resource handler receives a Context that only crosses the WIT
    /// boundary for fields it actually reads.
    #[cfg(target_arch = "wasm32")]
    #[must_use]
    pub fn from_wit_handle(handle: Box<dyn WitContextHandle>) -> Self {
        // Lineage + identity are small and almost always touched
        // (logging, authz) — eager-fetch them at construction.
        // Request + routing carry headers/body/query and are the
        // real lazy win, so they go behind `OnceCell` and only
        // cross the WIT ABI when the customer actually reads them.
        let lineage = handle.fetch_lineage();
        let identity = handle.fetch_identity();
        Self {
            request: Request {
                verb: http::Method::GET,
                protocol: crate::schema::Protocol::default(),
                path: EcoString::new(),
                body: Bytes::new(),
                headers: Arc::new(http::HeaderMap::new()),
                query: HashMap::new(),
            },
            lineage,
            routing: None,
            identity,
            auth: AuthBlock::default(),
            requested_format: crate::content_type::ContentType::Json,
            json_body: std::sync::OnceLock::new(),
            backend_manager: None,
            root_directory: Arc::from(""),
            pubsub_lookup: None,
            lazy: Some(LazyBacking {
                handle,
                request: OnceLock::new(),
                routing: OnceLock::new(),
            }),
        }
    }

    /// Vacant Context used as a swap target for Tower `Service<Context>` chains.
    #[must_use]
    pub fn placeholder() -> Self {
        Self::from_request(
            http::Method::GET,
            String::new(),
            Bytes::new(),
            http::HeaderMap::new(),
        )
    }

    /// Context for `on_ready` / queue-worker / scheduled dispatch.
    #[must_use]
    pub fn for_service(
        app_id: Arc<str>,
        root_directory: Arc<str>,
        backend_manager: Option<Arc<crate::backend::BackendManager>>,
        pubsub_lookup: Option<crate::plugins::PubSubLookupFn>,
    ) -> Self {
        let mut ctx = Self::placeholder();
        ctx.set_routing(Some(Routing {
            app: app_id,
            resource: Arc::from(""),
            database: Arc::from(""),
            key: None,
        }));
        ctx.root_directory = root_directory;
        ctx.backend_manager = backend_manager;
        ctx.pubsub_lookup = pubsub_lookup;
        ctx
    }

    // ── Lazy field-fetch helpers (wasm guest only) ──
    //
    // On wasm32 with a `lazy` backing set (via [`Context::from_wit_handle`]),
    // these resolve fields by calling the bindgen-generated WIT
    // accessors through `Box<dyn WitContextHandle>` and caching in
    // per-field `OnceCell`s. Without a backing (host build, or
    // wasm-side `placeholder()`), they return the eager fields.

    #[cfg(target_arch = "wasm32")]
    #[inline]
    fn request_ref(&self) -> &Request {
        if let Some(lazy) = &self.lazy {
            lazy.request.get_or_init(|| lazy.handle.fetch_request())
        } else {
            &self.request
        }
    }
    #[cfg(not(target_arch = "wasm32"))]
    #[inline]
    const fn request_ref(&self) -> &Request {
        &self.request
    }

    #[cfg(target_arch = "wasm32")]
    #[inline]
    fn routing_ref(&self) -> Option<&Routing> {
        if let Some(lazy) = &self.lazy {
            lazy.routing
                .get_or_init(|| lazy.handle.fetch_routing())
                .as_ref()
        } else {
            self.routing.as_ref()
        }
    }
    #[cfg(not(target_arch = "wasm32"))]
    #[inline]
    const fn routing_ref(&self) -> Option<&Routing> {
        self.routing.as_ref()
    }

    // ── Migration accessors — match old flat-field names as methods ──
    //
    // These read through `request_ref()`, which is `const` on the host
    // but not on wasm32 (it lazy-fetches via `get_or_init`). They
    // therefore can't be `const fn` across all targets; the host-build
    // `missing_const_for_fn` is allowed per-accessor.

    /// The request HTTP method.
    #[inline]
    #[allow(clippy::missing_const_for_fn)]
    pub fn method(&self) -> &http::Method {
        &self.request_ref().verb
    }
    /// The wire protocol the request arrived on.
    #[inline]
    #[allow(clippy::missing_const_for_fn)]
    pub fn protocol(&self) -> crate::schema::Protocol {
        self.request_ref().protocol
    }
    /// The request path (app-prefix included).
    #[inline]
    pub fn path(&self) -> &str {
        &self.request_ref().path
    }
    /// The raw request body bytes.
    #[inline]
    #[allow(clippy::missing_const_for_fn)]
    pub fn body(&self) -> &Bytes {
        &self.request_ref().body
    }
    /// The inbound request headers.
    #[inline]
    #[allow(clippy::missing_const_for_fn)]
    pub fn headers(&self) -> &http::HeaderMap {
        &self.request_ref().headers
    }
    /// The routing block, when the router has populated it. `None`
    /// only on raw-request contexts that bypassed the router (e.g.
    /// test fixtures, queue-worker dispatch). Most call sites should
    /// reach for the flat accessors (`app_id()`, `resource_id()`,
    /// `database()`, etc.) instead.
    #[inline]
    pub const fn routing(&self) -> Option<&Routing> {
        self.routing.as_ref()
    }

    /// Mutable access to the query-param map. Used by routing code
    /// that augments the parsed query with synthetic keys (`_search`,
    /// path-extracted values, etc.) before downstream handlers
    /// observe it.
    #[inline]
    pub const fn query_params_mut(&mut self) -> &mut HashMap<String, String> {
        &mut self.request.query
    }

    /// The parsed query-param map.
    #[inline]
    #[allow(clippy::missing_const_for_fn)]
    pub fn query_params(&self) -> &HashMap<String, String> {
        &self.request_ref().query
    }

    /// Application id from routing, or empty `Arc<str>` when unrouted.
    #[inline]
    pub fn app_id(&self) -> Arc<str> {
        self.routing_ref()
            .map_or_else(|| Arc::from(""), |r| Arc::clone(&r.app))
    }
    /// Resource (table) id from routing, or empty `Arc<str>` when unrouted.
    #[inline]
    pub fn resource_id(&self) -> Arc<str> {
        self.routing_ref()
            .map_or_else(|| Arc::from(""), |r| Arc::clone(&r.resource))
    }
    /// Record key from routing, or `""` for a collection-level operation.
    #[inline]
    pub fn path_id(&self) -> &str {
        self.routing_ref()
            .and_then(|r| r.key.as_deref())
            .unwrap_or("")
    }
    /// `true` when this is a collection-level operation (no record key).
    #[inline]
    pub fn is_collection(&self) -> bool {
        self.routing_ref().is_none_or(|r| r.key.is_none())
    }
    /// Database name. Settled at request-routing time from
    /// `TableDefinition.database` (or the default `"data"` when the
    /// table doesn't specify). **Distinct from `app_id`** — the
    /// `@database` schema directive can point a table at a database
    /// shared across apps. Returns empty string when no routing.
    #[inline]
    pub fn database(&self) -> Arc<str> {
        self.routing_ref()
            .map_or_else(|| Arc::from(""), |r| Arc::clone(&r.database))
    }
    /// Table name. For table-backed resources the resource name IS the
    /// table name.
    #[inline]
    pub fn table_name(&self) -> Arc<str> {
        self.routing_ref()
            .map_or_else(|| Arc::from(""), |r| Arc::clone(&r.resource))
    }

    // ── Mutators (for setter call sites) ──

    /// Set the request method.
    pub fn set_method(&mut self, m: http::Method) {
        self.request.verb = m;
    }
    /// Set the request path.
    pub fn set_path(&mut self, p: impl Into<EcoString>) {
        self.request.path = p.into();
    }
    /// Set the request body.
    pub fn set_body(&mut self, b: Bytes) {
        self.request.body = b;
    }
    /// Set the request headers.
    pub fn set_headers(&mut self, h: http::HeaderMap) {
        self.request.headers = Arc::new(h);
    }
    /// Set the wire protocol.
    pub const fn set_protocol(&mut self, p: crate::schema::Protocol) {
        self.request.protocol = p;
    }
    /// Replace the parsed query-param map.
    pub fn set_query_params(&mut self, q: HashMap<String, String>) {
        self.request.query = q;
    }
    /// Set the routing app id (creating a `Routing` block if absent).
    pub fn set_app_id(&mut self, app_id: Arc<str>) {
        match &mut self.routing {
            Some(r) => r.app = app_id,
            None => {
                self.set_routing(Some(Routing {
                    app: app_id,
                    resource: Arc::from(""),
                    database: Arc::from(""),
                    key: None,
                }));
            },
        }
    }
    /// Set the routing resource id (creating a `Routing` block if absent).
    pub fn set_resource_id(&mut self, resource_id: Arc<str>) {
        match &mut self.routing {
            Some(r) => r.resource = resource_id,
            None => {
                self.set_routing(Some(Routing {
                    app: Arc::from(""),
                    resource: resource_id,
                    database: Arc::from(""),
                    key: None,
                }));
            },
        }
    }
    /// Set the routing record key (empty string clears it to collection-level).
    pub fn set_path_id(&mut self, key: impl Into<String>) {
        let key_s = key.into();
        let key_opt = if key_s.is_empty() { None } else { Some(key_s) };
        match &mut self.routing {
            Some(r) => r.key = key_opt,
            None => {
                self.set_routing(Some(Routing {
                    app: Arc::from(""),
                    resource: Arc::from(""),
                    database: Arc::from(""),
                    key: key_opt,
                }));
            },
        }
    }
    /// Clear the record key when `is_coll` is `true` (makes the op collection-level).
    pub fn set_is_collection(&mut self, is_coll: bool) {
        if is_coll && let Some(r) = &mut self.routing {
            r.key = None;
        }
        // Setting is_collection=false without a key is meaningless; ignore.
    }
    /// Set the `database` field on the current `Routing` (creating a
    /// `Routing` block if none exists). Called by the router after it
    /// resolves the target table's `@database` directive.
    pub fn set_database(&mut self, db: Arc<str>) {
        match &mut self.routing {
            Some(r) => r.database = db,
            None => {
                self.set_routing(Some(Routing {
                    app: Arc::from(""),
                    resource: Arc::from(""),
                    database: db,
                    key: None,
                }));
            },
        }
    }
    /// Set the routing table name (aliases the resource id for table-backed resources).
    pub fn set_table_name(&mut self, name: Arc<str>) {
        // Table name aliases resource for table-backed resources.
        match &mut self.routing {
            Some(r) => r.resource = name,
            None => {
                self.set_routing(Some(Routing {
                    app: Arc::from(""),
                    resource: name,
                    database: Arc::from(""),
                    key: None,
                }));
            },
        }
    }

    // ── Convenience accessors carried over from the old shape ──

    /// Root directory accessor.
    #[inline]
    pub fn root_dir(&self) -> &str {
        &self.root_directory
    }

    /// Application ID as `&str`.
    #[inline]
    pub fn app_id_str(&self) -> &str {
        self.routing.as_ref().map_or("", |r| &r.app)
    }

    /// Resource ID as `&str` — borrow-returning counterpart to
    /// `resource_id()` (which returns an owned `Arc<str>`).
    #[inline]
    pub fn resource_id_str(&self) -> &str {
        self.routing.as_ref().map_or("", |r| &r.resource)
    }

    /// `PubSub` manager for a named table.
    pub fn pubsub(&self, table_name: &str) -> Option<Arc<crate::pubsub::PubSubManager>> {
        self.pubsub_lookup.as_ref().and_then(|f| f(table_name))
    }

    /// Raw table backend accessor.
    pub fn backend(&self, name: &str) -> Option<Arc<dyn crate::backend::KvBackend>> {
        self.backend_manager
            .as_ref()
            .and_then(|bm| bm.get_backend_for_table(name).ok())
    }

    /// Raw table backend accessor that errors when missing.
    ///
    /// # Errors
    /// `YetiError::Internal` when no backend is attached or registered for `name`.
    pub fn require_backend(&self, name: &str) -> Result<Arc<dyn crate::backend::KvBackend>> {
        self.backend_manager
            .as_ref()
            .ok_or_else(|| YetiError::Internal("backend_manager not available".to_owned()))?
            .get_backend_for_table(name)
    }

    /// A named query parameter, or `None` when absent.
    #[inline]
    pub fn query(&self, name: &str) -> Option<&str> {
        self.request.query.get(name).map(String::as_str)
    }

    /// A named query parameter parsed as `i64`, falling back to `default`.
    #[inline]
    pub fn query_int(&self, name: &str, default: i64) -> i64 {
        self.query(name)
            .and_then(|v| v.parse().ok())
            .unwrap_or(default)
    }

    /// A named query parameter parsed as a bool (`true`/`1`/`yes`/`on`),
    /// falling back to `default`.
    #[inline]
    pub fn query_bool(&self, name: &str, default: bool) -> bool {
        self.query(name).map_or(default, |v| {
            matches!(v.to_lowercase().as_str(), "true" | "1" | "yes" | "on")
        })
    }

    /// Get the database and table name as a pair (for permission checks).
    /// Database comes from `routing.database` (settled at routing time
    /// from the table's `@database` directive); table comes from
    /// `routing.resource`.
    #[inline]
    pub fn table_context(&self) -> (&str, &str) {
        self.routing
            .as_ref()
            .map_or(("", ""), |r| (&r.database, &r.resource))
    }

    /// Database name as `&str`. See [`Self::database`] for the full
    /// distinction between `database` and `app_id`.
    #[inline]
    pub fn database_str(&self) -> &str {
        self.routing.as_ref().map_or("", |r| &r.database)
    }

    /// Table name as `&str`. For table-backed resources, the resource name
    /// IS the table name.
    #[inline]
    pub fn table_name_str(&self) -> &str {
        self.routing.as_ref().map_or("", |r| &r.resource)
    }

    /// The request body parsed as JSON — lazily on first call, cached
    /// thereafter. `None` for an empty or non-JSON body. Requests that
    /// never read it (e.g. public/super-user writes that skip
    /// attribute-level permission checks) never pay the parse. Goes
    /// through `body()` so the wasm lazy backing materializes `request`
    /// first.
    #[must_use]
    pub fn json_body(&self) -> Option<&serde_json::Value> {
        self.json_body
            .get_or_init(|| {
                let body = self.body();
                if body.is_empty() {
                    None
                } else {
                    serde_json::from_slice::<serde_json::Value>(body.as_ref())
                        .ok()
                        .map(Box::new)
                }
            })
            .as_deref()
    }

    /// Force the lazy [`Context::json_body`] parse now. Useful when a
    /// later `&self` reader shouldn't pay the cost, or to pre-warm the
    /// cache. No-op once cached or for an empty body.
    pub fn parse_body(&mut self) {
        let _ = self.json_body();
    }

    // ── AuthBlock accessors — borrow-returning helpers for the
    //    common read paths. Setters write directly into `ctx.auth.*`.
    //    Callers needing the owned `Access` clone reach via `ctx.auth.access`.

    /// Resolved [`Access`] for this request. Defaults to [`Access::None`]
    /// when unauthenticated.
    #[inline]
    pub const fn access(&self) -> &Access {
        &self.auth.access
    }

    /// Cached per-request [`TablePermission`] decision.
    #[inline]
    pub const fn permission(&self) -> &TablePermission {
        &self.auth.permission
    }

    /// Wire-level authentication claim produced by an
    /// `AuthProvider::authenticate()` call. `None` for unauthenticated
    /// requests.
    #[inline]
    pub const fn auth_identity(&self) -> Option<&AuthIdentity> {
        self.auth.identity_input.as_ref()
    }

    // ── Lineage accessors ────────────────────────────────────────────────
    //
    // The `lineage` field is eager-materialized at construction (small,
    // near-universal reads — logging, request_id). Accessors here are
    // the canonical surface; direct `ctx.lineage.*` access is migration
    // debt counting down to zero.

    /// Request id (`UUIDv7`) — stamped by the inbound router, propagates
    /// through HLC + logs.
    #[inline]
    pub fn request_id(&self) -> &str {
        &self.lineage.request_id
    }

    /// Parent request id when this request was triggered by another
    /// (e.g. queue worker dispatching a job's child call).
    #[inline]
    pub fn parent_id(&self) -> Option<&str> {
        self.lineage.parent.as_deref()
    }

    /// Cross-request correlation id (e.g. customer's `X-Correlation-Id`
    /// header). `None` when no correlation was passed.
    #[inline]
    pub fn correlation_id(&self) -> Option<&str> {
        self.lineage.correlation.as_deref()
    }

    /// Deployment hash — identifies the yeti-fabric node that produced
    /// this request. Defaults to `"local"` for single-tenant dev.
    #[inline]
    pub fn deployment(&self) -> &str {
        &self.lineage.deployment
    }

    /// Hybrid Logical Clock stamp at request receipt. `Copy`, so
    /// returned by value.
    #[inline]
    #[must_use]
    pub const fn hlc(&self) -> Hlc {
        self.lineage.hlc
    }

    // ── Identity accessors ───────────────────────────────────────────────
    //
    // Eager-materialized at construction. `identity` is `Option<Identity>`
    // — the accessor exposes it as `Option<&Identity>` so call sites can
    // chain `.map(...)` without cloning, or pattern-match with
    // `if let Some(id) = ctx.identity() { ... }`.

    /// Resolved request identity — `None` for unauthenticated requests
    /// or paths that bypass the auth pipeline (public endpoints).
    #[inline]
    pub const fn identity(&self) -> Option<&Identity> {
        self.identity.as_ref()
    }

    /// Convenience: the authenticated principal (username / email /
    /// service id) when the request resolved an identity. Equivalent
    /// to `ctx.identity().and_then(|i| i.principal.as_deref())`.
    #[inline]
    pub fn principal(&self) -> Option<&str> {
        self.identity.as_ref().and_then(|i| i.principal.as_deref())
    }

    /// Convenience: the authenticated role set, or empty slice when
    /// unauthenticated. Always-safe-to-iterate shape; for permission
    /// checks prefer [`Self::permissions`] which carries the resolved
    /// `super_user` bit + per-resource ops mask.
    #[inline]
    pub fn roles(&self) -> &[String] {
        self.identity
            .as_ref()
            .map_or(&[][..], |i| i.roles.as_slice())
    }

    /// Convenience: the resolved permission bundle (`super_user` +
    /// per-resource op mask). Returns a default-empty `Permissions`
    /// when unauthenticated so call sites can chain `.super_user`
    /// without an outer `Option` dance.
    #[inline]
    pub fn permissions(&self) -> Option<&Permissions> {
        self.identity.as_ref().map(|i| &i.permissions)
    }

    /// Convenience: the authentication method (basic / jwt / oauth /
    /// api-key / service-token / none).
    #[inline]
    #[must_use]
    pub fn auth_method(&self) -> AuthMethod {
        self.identity
            .as_ref()
            .map_or(AuthMethod::None, |i| i.auth_method)
    }

    // ── Lineage setters ─────────────────────────────────────────────────
    //
    // Test fixtures + dispatch glue need to stamp lineage fields after
    // construction. The setters keep the field-write surface contained
    // so the underlying `lineage` field can move to `pub(crate)`.

    /// Set the request id.
    pub fn set_request_id(&mut self, id: impl Into<String>) {
        self.lineage.request_id = id.into();
    }

    /// Set the parent request id.
    pub fn set_parent_id(&mut self, parent: Option<String>) {
        self.lineage.parent = parent;
    }

    /// Set the cross-request correlation id.
    pub fn set_correlation_id(&mut self, c: Option<String>) {
        self.lineage.correlation = c;
    }

    /// Set the deployment hash.
    pub fn set_deployment(&mut self, d: impl Into<String>) {
        self.lineage.deployment = d.into();
    }

    /// Set the HLC stamp.
    pub const fn set_hlc(&mut self, hlc: Hlc) {
        self.lineage.hlc = hlc;
    }

    // ── Identity / auth setters ─────────────────────────────────────────
    //
    // Auth pipeline middleware writes through these after resolving the
    // inbound credential into a User + Role. Test fixtures also stamp
    // these to simulate authenticated requests.

    /// Set the resolved identity block.
    pub fn set_identity(&mut self, identity: Option<Identity>) {
        self.identity = identity;
    }

    /// Set the routing block.
    pub fn set_routing(&mut self, routing: Option<Routing>) {
        self.routing = routing;
    }

    /// Set the resolved [`Access`].
    pub fn set_access(&mut self, access: Access) {
        self.auth.access = access;
    }

    /// Set the cached [`TablePermission`] decision.
    pub fn set_permission(&mut self, p: TablePermission) {
        self.auth.permission = p;
    }

    /// Set the wire-level authentication claim.
    pub fn set_auth_identity(&mut self, id: Option<AuthIdentity>) {
        self.auth.identity_input = id;
    }

    /// Mutable [`Access`] for the auth pipeline's save/restore pattern:
    /// `std::mem::take(ctx.access_mut())` swaps in `Access::default()`
    /// so the resolver runs against a clean slate, then restoration
    /// writes back via [`Self::set_access`].
    #[inline]
    pub const fn access_mut(&mut self) -> &mut Access {
        &mut self.auth.access
    }

    /// Mutable wire-level authentication claim (companion to
    /// [`Self::access_mut`] for the same save/restore pattern).
    #[inline]
    pub const fn auth_identity_mut(&mut self) -> &mut Option<AuthIdentity> {
        &mut self.auth.identity_input
    }
}