castrum 0.9.8 → 0.9.9

package/rust/ffi/task.rs

@@ -18,7 +18,8 @@ pub extern "C" fn castrum_task_init(threads: u32) -> u32 {
 }
 
 /// Submit `op` with `args_len` packed arg bytes, completing under `task_id`.
-/// Returns `1` accepted, `0` rejected (null args with a non-zero length).
+/// Returns `1` accepted, `2` overloaded (the bounded work queue is full), or
+/// `0` invalid args (null args with a non-zero length) / panic.
 ///
 /// # Safety
 /// `args` must be valid for reads of `args_len` bytes.
@@ -39,7 +40,11 @@ pub unsafe extern "C" fn castrum_task_submit(
             } else {
                 slice::from_raw_parts(args, args_len).to_vec()
             };
-            u32::from(task::submit_op(op, owned, task_id as u64))
+            if task::submit_op(op, owned, task_id as u64) {
+                1
+            } else {
+                2
+            }
         },
         0,
     )
@@ -72,7 +77,7 @@ pub extern "C" fn castrum_task_pending() -> u32 {
 /// (UNSUPPORTED) means the op has no `_into` form and the caller should fall
 /// back to `castrum_task_submit`.
 ///
-/// Returns `1` accepted, `0` rejected.
+/// Returns `1` accepted, `2` overloaded (bounded queue full), `0` invalid args.
 ///
 /// # Safety
 /// `args` must be valid for reads of `args_len` bytes. `out` must be valid for
@@ -97,13 +102,11 @@ pub unsafe extern "C" fn castrum_task_submit_out(
             } else {
                 slice::from_raw_parts(args, args_len).to_vec()
             };
-            u32::from(task::submit_op_into(
-                op,
-                owned,
-                task_id as u64,
-                out as usize,
-                out_cap,
-            ))
+            if task::submit_op_into(op, owned, task_id as u64, out as usize, out_cap) {
+                1
+            } else {
+                2
+            }
         },
         0,
     )
@@ -121,7 +124,7 @@ pub extern "C" fn castrum_task_cancel(task_id: usize) -> u32 {
 /// compression costs a full-size copy on the JS thread and measured WORSE than
 /// the synchronous built-in (docs/RND-CONCURRENCY.md §7b).
 ///
-/// Returns `1` accepted, `0` rejected.
+/// Returns `1` accepted, `2` overloaded (bounded queue full), `0` invalid args.
 ///
 /// # Safety
 /// `hdr` must be valid for reads of `hdr_len` bytes. `data` must be valid for
@@ -148,13 +151,11 @@ pub unsafe extern "C" fn castrum_task_submit_slice(
             } else {
                 slice::from_raw_parts(hdr, hdr_len).to_vec()
             };
-            u32::from(task::submit_slice_op(
-                op,
-                owned,
-                data as usize,
-                data_len,
-                task_id as u64,
-            ))
+            if task::submit_slice_op(op, owned, data as usize, data_len, task_id as u64) {
+                1
+            } else {
+                2
+            }
         },
         0,
     )

package/rust/ingress/api.rs

@@ -85,11 +85,13 @@ impl Ingress {
                 .map_err(|e| Error::new(Status::InvalidArg, format!("Schema JSON error: {}", e)))?;
             // Compile BOTH the authoritative jsonschema validator and the
             // zero-DOM fast path once at construction — no per-request schema
-            // work (see IngressSchema in pipeline.rs).
-            let compiled = IngressSchema::compile(&schema_value).map_err(|e| {
-                Error::new(Status::InvalidArg, format!("Schema compile error: {}", e))
-            })?;
-            Some(Arc::new(compiled))
+            // work (see IngressSchema in pipeline.rs). Identical schema bytes
+            // are shared process-wide via the compiled-schema cache.
+            let compiled =
+                crate::ingress::schema_cache::get_or_compile(&schema_value).map_err(|e| {
+                    Error::new(Status::InvalidArg, format!("Schema compile error: {}", e))
+                })?;
+            Some(compiled)
         } else {
             None
         };
@@ -353,3 +355,17 @@ impl Ingress {
         inner.handle_packed(&packed, body, out)
     }
 }
+
+/// Clear the process-wide compiled-schema cache — the dedupe store that shares
+/// one compiled `IngressSchema` across every `Ingress`/`NativeRoute` built from
+/// identical schema bytes.
+///
+/// Maintenance hook for the public `flushMemory()` (napi export name:
+/// `clearSchemaCache`). Idempotent; safe to call at any time, including before
+/// any schema has ever been compiled. Dropping the cache only releases the
+/// native validators — already-constructed ingress/route instances keep their
+/// own `Arc<IngressSchema>`, so live routes are unaffected.
+#[napi]
+pub fn clear_schema_cache() {
+    crate::ingress::schema_cache::clear_schema_cache();
+}

package/rust/ingress/mod.rs

@@ -22,6 +22,9 @@ mod tests;
 
 pub(crate) mod options;
 pub(crate) mod packed;
+// Process-wide compiled-schema cache: dedupes identical `IngressSchema`
+// compiles across `Ingress` / `NativeRoute` instances (schema_cache.rs).
+pub(crate) mod schema_cache;
 pub(crate) mod time;
 
 pub(crate) mod cors;
@@ -40,6 +43,10 @@ pub(crate) mod terminal;
 #[cfg(test)]
 pub(crate) use self::api::clamp_output_size;
 pub use self::api::Ingress;
+// napi maintenance export (`clearSchemaCache`) — re-exported so it is a
+// crate-reachable item (dead-code analysis) while the `#[napi]` macro does the
+// JS-side registration.
+pub use self::api::clear_schema_cache;
 pub(crate) use self::api::IngressInner;
 pub(crate) use self::native_route::NativeRoute;
 pub(crate) use self::options::{IngressOptions, Limits};

package/rust/ingress/native_route.rs

@@ -177,9 +177,11 @@ impl NativeRoute {
                     .map_err(|_| "route descriptor: body schema is not valid UTF-8".to_string())?;
                 let schema_value: serde_json::Value = sonic_rs::from_str(schema_str)
                     .map_err(|e| format!("route descriptor: body schema JSON error: {e}"))?;
-                let compiled = IngressSchema::compile(&schema_value)
+                // Shared process-wide: identical schema bytes compile once even
+                // across routes/instances (see ingress/schema_cache.rs).
+                let compiled = super::schema_cache::get_or_compile(&schema_value)
                     .map_err(|e| format!("route descriptor: body schema compile error: {e}"))?;
-                Some(Arc::new(compiled))
+                Some(compiled)
             }
             None => None,
         };

package/rust/ingress/schema_cache.rs

@@ -0,0 +1,266 @@
+// rust/ingress/schema_cache.rs — Process-wide compiled-schema cache.
+//
+// `Ingress` and `NativeRoute` compile a request-body schema once at
+// construction (`IngressSchema::compile`). When an application builds N routes
+// over the SAME schema bytes, that is N identical compiles at startup and N
+// copies retained at runtime. This module dedupes them: identical schema JSON
+// yields ONE shared `Arc<IngressSchema>`, bounded by an LRU (default 128
+// entries, override with `CASTRUM_SCHEMA_CACHE_MAX`).
+//
+// Key = a stable 64-bit hash of the raw serialized schema bytes (exact bytes:
+// a different key order is a different key and simply compiles a second time).
+// The hash only selects a bucket — it is NOT the identity: each entry stores
+// its serialized bytes alongside the compiled schema, and a hit is returned
+// only when those bytes EQUAL the requested bytes. `xxh3_64` is
+// non-cryptographic, so trusting the hash alone would let a craftable collision
+// reuse the wrong validator (a validation-bypass class bug); the byte compare
+// makes collisions a safe miss (compile + replace the colliding bucket) rather
+// than a wrong-schema hit.
+//
+// Only SUCCESSFUL compiles are cached. `IngressSchema` is immutable after
+// compile (`Arc<jsonschema::Validator>` + optional `Arc<FastNode>`), so sharing
+// the `Arc` across routes and threads is sound; mutable state is per-call
+// (`Cursor`/`Ctx`), never on the schema.
+//
+// Concurrency: double-checked locking — the cache lock is released before the
+// (slow) compile and re-taken for insert, so one slow compile never serializes
+// other schema lookups.
+
+use std::num::NonZeroUsize;
+use std::sync::{Arc, OnceLock};
+
+use lru::LruCache;
+use parking_lot::Mutex;
+
+use super::pipeline::IngressSchema;
+
+/// Default cache capacity (distinct schema byte strings).
+const DEFAULT_SCHEMA_CACHE_MAX: usize = 128;
+/// Upper clamp on the configured capacity — an absurd env value must not size
+/// an unbounded LRU (each entry retains a compiled validator + its bytes).
+const MAX_SCHEMA_CACHE_MAX: usize = 4096;
+
+/// Cache entry: the exact serialized schema bytes (collision disambiguation)
+/// plus the shared compiled schema.
+type CacheEntry = (Vec<u8>, Arc<IngressSchema>);
+
+/// Cache map: schema-hash → (schema bytes, shared compiled schema).
+type SchemaMap = Mutex<LruCache<u64, CacheEntry>>;
+
+/// Process-wide compiled-schema cache (lazily initialized on first compile).
+static SCHEMA_CACHE: OnceLock<SchemaMap> = OnceLock::new();
+
+/// Resolve a capacity from the raw env value: unset/unparseable/zero →
+/// [`DEFAULT_SCHEMA_CACHE_MAX`], otherwise clamped to
+/// `1..=MAX_SCHEMA_CACHE_MAX` (an LRU needs a nonzero capacity).
+fn resolve_cap(raw: Option<&str>) -> usize {
+    raw.and_then(|v| v.trim().parse::<usize>().ok())
+        .filter(|n| *n > 0)
+        .map(|n| n.min(MAX_SCHEMA_CACHE_MAX))
+        .unwrap_or(DEFAULT_SCHEMA_CACHE_MAX)
+}
+
+/// Resolve the configured cache capacity (`CASTRUM_SCHEMA_CACHE_MAX`).
+fn cache_cap() -> usize {
+    resolve_cap(std::env::var("CASTRUM_SCHEMA_CACHE_MAX").ok().as_deref())
+}
+
+/// Hash the serialized schema bytes with the crate's XXH3-64 helper (stable and
+/// well-distributed). The exact byte string is the identity: serialization
+/// preserves key insertion order (`serde_json` is built with `preserve_order`),
+/// so whitespace/key-order differences compile separately rather than collide.
+#[inline]
+fn schema_key(bytes: &[u8]) -> u64 {
+    crate::crypto::hashing::fast_hash_bytes(bytes)
+}
+
+/// Look up (or compile and insert) the shared `IngressSchema` for
+/// `schema_value`. Only successes are cached; a compile error is returned
+/// verbatim (identical message to a direct `IngressSchema::compile`).
+fn get_or_compile_in(
+    cache: &SchemaMap,
+    schema_value: &serde_json::Value,
+) -> std::result::Result<Arc<IngressSchema>, String> {
+    let bytes = serde_json::to_vec(schema_value).map_err(|e| e.to_string())?;
+    let key = schema_key(&bytes);
+
+    // Fast path: a hash hit is only trusted when the bytes MATCH (a colliding
+    // hash falls through to a real compile, never a wrong-schema hit).
+    if let Some((stored, existing)) = cache.lock().get(&key) {
+        if stored.as_slice() == bytes.as_slice() {
+            return Ok(Arc::clone(existing));
+        }
+    }
+
+    // Miss: compile WITHOUT holding the lock (a slow compile must not block
+    // other schema lookups/inserts).
+    let compiled = Arc::new(IngressSchema::compile(schema_value)?);
+
+    // Re-check under the lock: a concurrent thread may have compiled the same
+    // schema while we were outside it — prefer the first inserter's Arc (same
+    // bytes) so all callers share one instance. A colliding entry with
+    // different bytes is REPLACED (the bucket holds exactly one schema).
+    let mut guard = cache.lock();
+    if let Some((stored, existing)) = guard.get(&key) {
+        if stored.as_slice() == bytes.as_slice() {
+            return Ok(Arc::clone(existing));
+        }
+    }
+    let _ = guard.put(key, (bytes, Arc::clone(&compiled)));
+    drop(guard);
+    Ok(compiled)
+}
+
+/// Return the shared compiled schema for `schema_value`, compiling it on first
+/// use. Errors are NOT cached (a fixed schema compiles on the next attempt).
+pub(crate) fn get_or_compile(
+    schema_value: &serde_json::Value,
+) -> std::result::Result<Arc<IngressSchema>, String> {
+    let cache = SCHEMA_CACHE.get_or_init(|| {
+        Mutex::new(LruCache::new(
+            NonZeroUsize::new(cache_cap()).expect("cache cap is nonzero"),
+        ))
+    });
+    get_or_compile_in(cache, schema_value)
+}
+
+/// Drop every retained compiled schema. Idempotent and safe to call before
+/// any schema has ever been compiled (the cache is then simply uninitialized).
+/// Maintenance hook for the public `flushMemory()`.
+pub fn clear_schema_cache() {
+    if let Some(cache) = SCHEMA_CACHE.get() {
+        cache.lock().clear();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn local_cache(cap: usize) -> SchemaMap {
+        Mutex::new(LruCache::new(
+            NonZeroUsize::new(cap).expect("test cap is nonzero"),
+        ))
+    }
+
+    #[test]
+    fn same_schema_bytes_share_one_arc() {
+        let cache = local_cache(4);
+        let schema = json!({
+            "type": "object",
+            "required": ["x"],
+            "properties": { "x": { "type": "string" } }
+        });
+
+        let first = get_or_compile_in(&cache, &schema).unwrap();
+        let second = get_or_compile_in(&cache, &schema).unwrap();
+
+        assert!(Arc::ptr_eq(&first, &second));
+        assert_eq!(cache.lock().len(), 1);
+    }
+
+    #[test]
+    fn different_schema_bytes_compile_separately() {
+        let cache = local_cache(4);
+        let object = get_or_compile_in(&cache, &json!({ "type": "object" })).unwrap();
+        let string = get_or_compile_in(&cache, &json!({ "type": "string" })).unwrap();
+
+        assert!(!Arc::ptr_eq(&object, &string));
+        assert_eq!(cache.lock().len(), 2);
+    }
+
+    #[test]
+    fn compile_errors_are_not_cached() {
+        let cache = local_cache(4);
+        // `type` must be a string or array of strings — jsonschema rejects this
+        // at build time, so it never reaches the cache.
+        let invalid = json!({ "type": 42 });
+
+        assert!(get_or_compile_in(&cache, &invalid).is_err());
+        assert_eq!(cache.lock().len(), 0);
+    }
+
+    #[test]
+    fn cache_is_bounded_by_capacity() {
+        let cache = local_cache(2);
+        for i in 0..3 {
+            let schema = json!({
+                "type": "object",
+                "properties": { format!("k{i}"): { "type": "string" } }
+            });
+            get_or_compile_in(&cache, &schema).unwrap();
+        }
+        assert!(cache.lock().len() <= 2);
+    }
+
+    #[test]
+    fn clear_empties_the_cache() {
+        let cache = local_cache(4);
+        let schema = json!({ "type": "object" });
+        let first = get_or_compile_in(&cache, &schema).unwrap();
+
+        cache.lock().clear();
+
+        assert_eq!(cache.lock().len(), 0);
+        let second = get_or_compile_in(&cache, &schema).unwrap();
+        // A cleared cache recompiles: a fresh Arc, not the old shared one.
+        assert!(!Arc::ptr_eq(&first, &second));
+    }
+
+    #[test]
+    fn cap_defaults_clamps_and_rejects_bad_values() {
+        assert_eq!(resolve_cap(None), DEFAULT_SCHEMA_CACHE_MAX);
+        assert_eq!(resolve_cap(Some("")), DEFAULT_SCHEMA_CACHE_MAX);
+        assert_eq!(resolve_cap(Some("abc")), DEFAULT_SCHEMA_CACHE_MAX);
+        assert_eq!(resolve_cap(Some("0")), DEFAULT_SCHEMA_CACHE_MAX);
+        assert_eq!(resolve_cap(Some("256")), 256);
+        assert_eq!(resolve_cap(Some(" 64 ")), 64);
+        // Absurd values are clamped so the LRU cannot be sized unboundedly.
+        assert_eq!(resolve_cap(Some("999999999")), MAX_SCHEMA_CACHE_MAX);
+    }
+
+    #[test]
+    fn hash_collision_returns_the_correct_schema() {
+        let cache = local_cache(4);
+        let schema_a = json!({ "type": "object", "required": ["a"] });
+        let schema_b = json!({ "type": "object", "required": ["b"] });
+        let bytes_b = serde_json::to_vec(&schema_b).unwrap();
+        let key_b = schema_key(&bytes_b);
+
+        // Simulate an xxh3 collision: an entry under B's key that actually holds
+        // A's bytes + compiled validator. Under a hash-only cache this would be
+        // returned for B (wrong-schema validation bypass).
+        let a = get_or_compile_in(&cache, &schema_a).unwrap();
+        let bytes_a = serde_json::to_vec(&schema_a).unwrap();
+        let _ = cache.lock().put(key_b, (bytes_a, Arc::clone(&a)));
+
+        // The byte compare must reject the collision and compile the REAL B.
+        let b = get_or_compile_in(&cache, &schema_b).unwrap();
+        assert!(!Arc::ptr_eq(&a, &b));
+        assert!(b.validate(br#"{"b":1}"#));
+        assert!(!b.validate(br#"{"a":1}"#));
+        // A itself still resolves correctly (its own bucket is intact).
+        let a_again = get_or_compile_in(&cache, &schema_a).unwrap();
+        assert!(Arc::ptr_eq(&a, &a_again));
+    }
+
+    #[test]
+    fn global_get_or_compile_and_clear() {
+        // Use a schema unique to this test so parallel tests cannot repopulate
+        // the key between the clear and the recompile.
+        let schema = json!({
+            "type": "object",
+            "properties": { "schema_cache_global_probe": { "type": "integer" } }
+        });
+
+        clear_schema_cache();
+        let first = get_or_compile(&schema).unwrap();
+        let again = get_or_compile(&schema).unwrap();
+        assert!(Arc::ptr_eq(&first, &again));
+
+        clear_schema_cache();
+        let recompiled = get_or_compile(&schema).unwrap();
+        assert!(!Arc::ptr_eq(&first, &recompiled));
+    }
+}

package/rust/task/mod.rs

@@ -30,6 +30,7 @@ pub use runtime::{init, shutdown, threads};
 ///
 /// The pool auto-starts (default worker count) on first use, so callers do not
 /// have to sequence `init` before `submit`. `args` is moved onto the worker.
+/// Returns `false` when the bounded admission queue is full (`OVERLOADED`).
 pub fn submit_op(op: u32, args: Vec<u8>, id: u64) -> bool {
     runtime::submit(move || ops::execute_guarded(op, &args, id))
 }

package/rust/task/runtime.rs

@@ -10,7 +10,7 @@
 
 use parking_lot::{Condvar, Mutex};
 use std::collections::VecDeque;
-use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicUsize, Ordering};
 use std::sync::OnceLock;
 use std::time::Duration;
 
@@ -25,6 +25,11 @@ const SPIN_ROUNDS: u32 = 64;
 /// Idle park timeout. A bounded wait (instead of an indefinite one) means a
 /// missed wakeup costs at most this much latency and can never wedge a worker.
 const PARK_TIMEOUT: Duration = Duration::from_micros(200);
+/// Default admission bound for the work queue. A submission that would exceed
+/// it is rejected (the C ABI returns `2 = overloaded`) instead of growing
+/// memory without bound. Overridable with `CASTRUM_TASK_QUEUE_MAX` (minimum 1)
+/// when the pool is first created.
+pub const DEFAULT_QUEUE_MAX: usize = 4096;
 
 /// A unit of offloaded work. Owns its input bytes (`'static`, `Send`).
 pub type Job = Box<dyn FnOnce() + Send + 'static>;
@@ -35,6 +40,9 @@ pub struct TaskPool {
     cv: Condvar,
     running: AtomicBool,
     threads: AtomicU32,
+    /// Admission bound for `queue`; read once when the pool is created (tests
+    /// override it through [`set_queue_max`]).
+    queue_max: AtomicUsize,
 }
 
 static POOL: OnceLock<TaskPool> = OnceLock::new();
@@ -46,6 +54,7 @@ impl TaskPool {
             cv: Condvar::new(),
             running: AtomicBool::new(false),
             threads: AtomicU32::new(0),
+            queue_max: AtomicUsize::new(default_queue_max()),
         }
     }
 
@@ -121,9 +130,17 @@ impl TaskPool {
         }
     }
 
-    fn enqueue(&'static self, job: Job) {
-        self.queue.lock().push_back(job);
+    /// Push `job` only while the queue is below its admission bound. Returns
+    /// `false` when full — the caller drops the job (overload).
+    fn try_enqueue(&'static self, job: Job) -> bool {
+        let mut q = self.queue.lock();
+        if q.len() >= self.queue_max.load(Ordering::Relaxed) {
+            return false;
+        }
+        q.push_back(job);
+        drop(q);
         self.cv.notify_one();
+        true
     }
 
     fn shutdown(&self) {
@@ -173,6 +190,16 @@ pub fn default_threads() -> usize {
         })
 }
 
+/// Default admission bound: `CASTRUM_TASK_QUEUE_MAX` when set to a valid value
+/// `>= 1`, else {@link DEFAULT_QUEUE_MAX}.
+fn default_queue_max() -> usize {
+    std::env::var("CASTRUM_TASK_QUEUE_MAX")
+        .ok()
+        .and_then(|v| v.parse::<usize>().ok())
+        .filter(|&n| n > 0)
+        .unwrap_or(DEFAULT_QUEUE_MAX)
+}
+
 /// Start the pool with `threads` workers (`None`/`0` → {@link default_threads}).
 ///
 /// Returns `0` when this call started the pool and `1` when it was already
@@ -190,8 +217,9 @@ pub fn init(threads: Option<u32>) -> u32 {
     0
 }
 
-/// Enqueue `job`, auto-starting the pool on first use. Always accepted in v1
-/// (the queue is unbounded; admission/backpressure is a later milestone).
+/// Enqueue `job`, auto-starting the pool on first use. Returns `false` (the C
+/// ABI's `2 = overloaded`) when the bounded work queue is full — admission is
+/// capped by `CASTRUM_TASK_QUEUE_MAX` (default {@link DEFAULT_QUEUE_MAX}).
 pub fn submit<F>(job: F) -> bool
 where
     F: FnOnce() + Send + 'static,
@@ -201,8 +229,28 @@ where
         let n = default_threads();
         p.start(n);
     }
-    p.enqueue(Box::new(job));
-    true
+    p.try_enqueue(Box::new(job))
+}
+
+/// Jobs queued but not yet started (monitoring / tests).
+pub fn queue_depth() -> usize {
+    POOL.get_or_init(TaskPool::new).queue.lock().len()
+}
+
+/// Configured admission bound for the work queue (monitoring / tests).
+pub fn queue_max() -> usize {
+    POOL.get_or_init(TaskPool::new)
+        .queue_max
+        .load(Ordering::Relaxed)
+}
+
+/// Override the admission bound. TEST ONLY: production reads
+/// `CASTRUM_TASK_QUEUE_MAX` once when the pool is created.
+#[cfg(test)]
+pub fn set_queue_max(max: usize) {
+    POOL.get_or_init(TaskPool::new)
+        .queue_max
+        .store(max.max(1), Ordering::Relaxed);
 }
 
 /// Configured worker count (0 before the pool starts).

package/rust/task/tests.rs

@@ -5,7 +5,9 @@
 // threads.
 
 use parking_lot::Mutex;
-use std::sync::atomic::{AtomicU32, Ordering};
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicUsize, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
 
 use super::completion::{self, Completion};
 use super::ops::{
@@ -259,3 +261,98 @@ fn pool_starts_with_a_nonzero_thread_count() {
     runtime::init(None);
     assert!(runtime::threads() >= 1);
 }
+
+/// Block until `counter` reaches `target` (10 s guard).
+fn wait_for_counter(counter: &AtomicUsize, target: usize) {
+    let deadline = std::time::Instant::now() + Duration::from_secs(10);
+    while counter.load(Ordering::SeqCst) < target {
+        assert!(
+            std::time::Instant::now() < deadline,
+            "counter never reached {target}"
+        );
+        std::thread::sleep(Duration::from_millis(1));
+    }
+}
+
+/// Block until the admission queue is empty (10 s guard).
+fn wait_for_drained_queue() {
+    let deadline = std::time::Instant::now() + Duration::from_secs(10);
+    while runtime::queue_depth() != 0 {
+        assert!(std::time::Instant::now() < deadline, "queue never drained");
+        std::thread::sleep(Duration::from_millis(1));
+    }
+}
+
+/// The queue is a hard-bounded admission gate: once every worker is occupied
+/// and the queue holds `queue_max` jobs, further submits are rejected rather
+/// than growing memory; releasing the workers restores capacity.
+#[test]
+fn queue_admission_is_bounded_and_recovers() {
+    let _g = LOCK.lock();
+    completion::clear();
+    runtime::init(None);
+    let workers = runtime::threads().max(1) as usize;
+
+    const CAP: usize = 4;
+    runtime::set_queue_max(CAP);
+
+    let started = Arc::new(AtomicUsize::new(0));
+    let finished = Arc::new(AtomicUsize::new(0));
+    let release = Arc::new(AtomicBool::new(false));
+
+    let make_blocker = || {
+        let started = Arc::clone(&started);
+        let finished = Arc::clone(&finished);
+        let release = Arc::clone(&release);
+        move || {
+            started.fetch_add(1, Ordering::SeqCst);
+            while !release.load(Ordering::SeqCst) {
+                std::thread::sleep(Duration::from_millis(1));
+            }
+            finished.fetch_add(1, Ordering::SeqCst);
+        }
+    };
+
+    // Occupy every worker, one submission at a time, waiting for each to START
+    // so it has left the queue. (Submitting them all at once would let one
+    // worker batch-pop several, which still occupies it but muddies the depth
+    // arithmetic this test asserts.)
+    for i in 0..workers {
+        assert!(
+            runtime::submit(make_blocker()),
+            "worker {i} submit rejected"
+        );
+        wait_for_counter(&started, i + 1);
+    }
+    assert_eq!(runtime::queue_depth(), 0);
+    assert_eq!(runtime::queue_max(), CAP);
+
+    // Every worker is busy: fill the queue to the cap.
+    for i in 0..CAP {
+        assert!(
+            runtime::submit(make_blocker()),
+            "queued submit {i} rejected"
+        );
+    }
+    assert_eq!(runtime::queue_depth(), CAP);
+
+    // The cap is a HARD bound — the next submit is rejected, not queued.
+    assert!(
+        !runtime::submit(make_blocker()),
+        "submit accepted at the cap"
+    );
+    assert_eq!(runtime::queue_depth(), CAP);
+
+    // Release: the queue drains and admission recovers.
+    release.store(true, Ordering::SeqCst);
+    wait_for_counter(&finished, workers + CAP);
+    wait_for_drained_queue();
+    assert!(
+        runtime::submit(make_blocker()),
+        "capacity did not recover after drain"
+    );
+    wait_for_counter(&finished, workers + CAP + 1);
+
+    // Restore the default bound so a later test cannot inherit the tiny cap.
+    runtime::set_queue_max(4096);
+}