Skip to main content

stateknot_core/
model_runtime.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Runtime-neutral callable model boundary contracts.
5
6use std::{
7    error::Error as StdError,
8    fmt,
9    future::{Future, pending},
10    pin::Pin,
11    sync::Arc,
12    time::{Duration, Instant},
13};
14
15use futures_core::Stream;
16use schemars::JsonSchema;
17use serde::{Deserialize, Serialize};
18use thiserror::Error;
19
20use crate::{
21    AttemptId, BudgetRemaining, CapabilityIdentity, Failure, ModelCapabilities, ModelDescriptor,
22    ModelEvent, ModelProviderModelId, ModelProviderRequestId, ModelProviderResponseId,
23    ModelRequest, ModelResponse, ModelResponseMode, ModelUsage, RunId, SchemaReference, TenantId,
24    ThreadId, Timestamp, TokenCount,
25};
26
27/// A heap-allocated, `Send` future whose implementation is independent of an async executor.
28pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
29
30/// A heap-allocated, `Send` stream whose implementation is independent of an async executor.
31pub type BoxStream<'a, T> = Pin<Box<dyn Stream<Item = T> + Send + 'a>>;
32
33/// Runtime-provided observation of a permanent cooperative cancellation request.
34///
35/// Implementations must make [`Self::is_cancelled`] non-blocking and monotonic:
36/// once it returns `true`, it must never return `false`. Every future returned
37/// by [`Self::cancelled`] must resolve after cancellation without losing a wake
38/// that races with future creation. Dropping a wait future must not cancel or
39/// consume the shared signal.
40pub trait CancellationObserver: Send + Sync + 'static {
41    /// Returns whether cancellation has already been requested.
42    fn is_cancelled(&self) -> bool;
43
44    /// Returns a cancellation-safe future that resolves once cancellation is requested.
45    fn cancelled(&self) -> BoxFuture<'_, ()>;
46}
47
48/// Cloneable, runtime-neutral handle to cooperative cancellation state.
49///
50/// Cancellation is best effort. Observing this signal never proves that a
51/// provider did not receive, process, or bill a request. The runtime remains
52/// responsible for recording the actual outcome and explicit retry advice.
53#[derive(Clone)]
54pub struct CancellationSignal {
55    observer: Arc<dyn CancellationObserver>,
56}
57
58impl CancellationSignal {
59    /// Wraps one runtime-specific observer.
60    #[must_use]
61    pub fn new<O>(observer: O) -> Self
62    where
63        O: CancellationObserver,
64    {
65        Self {
66            observer: Arc::new(observer),
67        }
68    }
69
70    /// Wraps an observer that is already shared by the runtime.
71    #[must_use]
72    pub fn from_shared(observer: Arc<dyn CancellationObserver>) -> Self {
73        Self { observer }
74    }
75
76    /// Returns a signal that never requests cancellation.
77    ///
78    /// Production runtimes normally supply a real observer. This value is
79    /// useful for deterministic tests and bounded operations whose enclosing
80    /// lifetime cannot be cancelled independently.
81    #[must_use]
82    pub fn never() -> Self {
83        Self::new(NeverCancelled)
84    }
85
86    /// Returns whether cancellation has already been requested.
87    #[must_use]
88    pub fn is_cancelled(&self) -> bool {
89        self.observer.is_cancelled()
90    }
91
92    /// Waits asynchronously for cancellation without selecting an executor.
93    pub fn cancelled(&self) -> BoxFuture<'_, ()> {
94        self.observer.cancelled()
95    }
96}
97
98impl Default for CancellationSignal {
99    fn default() -> Self {
100        Self::never()
101    }
102}
103
104impl fmt::Debug for CancellationSignal {
105    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
106        formatter
107            .debug_struct("CancellationSignal")
108            .field("cancelled", &self.is_cancelled())
109            .finish_non_exhaustive()
110    }
111}
112
113struct NeverCancelled;
114
115impl CancellationObserver for NeverCancelled {
116    fn is_cancelled(&self) -> bool {
117        false
118    }
119
120    fn cancelled(&self) -> BoxFuture<'_, ()> {
121        Box::pin(pending())
122    }
123}
124
125/// Reason a model boundary must stop before producing another result.
126#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
127#[non_exhaustive]
128pub enum ModelStopReason {
129    /// The enclosing run requested cooperative cancellation.
130    Cancelled,
131    /// The finite monotonic invocation deadline was reached.
132    DeadlineExceeded,
133}
134
135/// Ephemeral, capability-limited context for exactly one model attempt.
136///
137/// The context intentionally is not serializable. It carries stable execution
138/// identity, a finite remaining run-budget view, a wall-clock deadline for
139/// durable evidence, the equivalent monotonic deadline for timeout enforcement,
140/// and a cooperative cancellation signal. It contains no prompt, tool argument,
141/// bearer token, credential value, provider SDK client, or mutable property bag.
142///
143/// Model adapters must treat cancellation and deadline enforcement as separate
144/// from provider outcome certainty. Cancellation wins when both conditions are
145/// observed together, but neither condition proves that in-flight provider work
146/// did not complete or incur usage.
147#[derive(Clone)]
148pub struct ModelContext {
149    tenant_id: TenantId,
150    run_id: RunId,
151    thread_id: ThreadId,
152    attempt_id: AttemptId,
153    budget: BudgetRemaining,
154    observed_at: Timestamp,
155    deadline_instant: Instant,
156    cancellation: CancellationSignal,
157}
158
159impl ModelContext {
160    /// Constructs an ephemeral attempt context from one paired wall/monotonic observation.
161    ///
162    /// `observed_at` and `observed_instant` must represent the same runtime
163    /// observation. The constructor converts the durable budget deadline into
164    /// a monotonic deadline so wall-clock adjustments cannot lengthen an active
165    /// provider call.
166    ///
167    /// # Errors
168    ///
169    /// Returns [`ModelContextError`] when the durable deadline is already
170    /// reached or the platform cannot represent the corresponding monotonic
171    /// deadline.
172    #[allow(clippy::too_many_arguments)]
173    pub fn new(
174        tenant_id: TenantId,
175        run_id: RunId,
176        thread_id: ThreadId,
177        attempt_id: AttemptId,
178        budget: BudgetRemaining,
179        observed_at: Timestamp,
180        observed_instant: Instant,
181        cancellation: CancellationSignal,
182    ) -> Result<Self, ModelContextError> {
183        let deadline = budget.deadline();
184        let remaining_micros = i128::from(deadline.unix_micros())
185            .checked_sub(i128::from(observed_at.unix_micros()))
186            .expect("subtracting two i64 timestamps cannot overflow i128");
187        if remaining_micros <= 0 {
188            return Err(ModelContextError::DeadlineReached {
189                deadline,
190                observed_at,
191            });
192        }
193        let remaining_micros = u64::try_from(remaining_micros)
194            .expect("the supported timestamp range fits into u64 microseconds");
195        let remaining = Duration::from_micros(remaining_micros);
196        let deadline_instant = observed_instant
197            .checked_add(remaining)
198            .ok_or(ModelContextError::MonotonicDeadlineOutOfRange { remaining })?;
199
200        Ok(Self {
201            tenant_id,
202            run_id,
203            thread_id,
204            attempt_id,
205            budget,
206            observed_at,
207            deadline_instant,
208            cancellation,
209        })
210    }
211
212    /// Returns the tenant boundary for storage, policy, and audit correlation.
213    #[must_use]
214    pub const fn tenant_id(&self) -> &TenantId {
215        &self.tenant_id
216    }
217
218    /// Returns the durable enclosing run identifier.
219    #[must_use]
220    pub const fn run_id(&self) -> RunId {
221        self.run_id
222    }
223
224    /// Returns the durable conversation thread identifier.
225    #[must_use]
226    pub const fn thread_id(&self) -> ThreadId {
227        self.thread_id
228    }
229
230    /// Returns the exact attempt identifier required on every response and event.
231    #[must_use]
232    pub const fn attempt_id(&self) -> AttemptId {
233        self.attempt_id
234    }
235
236    /// Returns the finite remaining run capacity captured for this attempt.
237    #[must_use]
238    pub const fn budget(&self) -> &BudgetRemaining {
239        &self.budget
240    }
241
242    /// Returns the wall-clock observation paired with the monotonic clock.
243    #[must_use]
244    pub const fn observed_at(&self) -> Timestamp {
245        self.observed_at
246    }
247
248    /// Returns the durable absolute wall-clock deadline.
249    #[must_use]
250    pub const fn deadline(&self) -> Timestamp {
251        self.budget.deadline()
252    }
253
254    /// Returns the equivalent process-local monotonic deadline.
255    #[must_use]
256    pub const fn deadline_instant(&self) -> Instant {
257        self.deadline_instant
258    }
259
260    /// Returns the shared cooperative cancellation signal.
261    #[must_use]
262    pub const fn cancellation(&self) -> &CancellationSignal {
263        &self.cancellation
264    }
265
266    /// Returns remaining monotonic time, or `None` at and after the deadline.
267    #[must_use]
268    pub fn remaining_time_at(&self, observed_instant: Instant) -> Option<Duration> {
269        self.deadline_instant
270            .checked_duration_since(observed_instant)
271            .filter(|remaining| !remaining.is_zero())
272    }
273
274    /// Returns the deterministic stop reason observed at one monotonic instant.
275    ///
276    /// Explicit cancellation wins if cancellation and deadline are both
277    /// observable. This precedence matches the run state-machine contract for
278    /// work that has not committed a result.
279    #[must_use]
280    pub fn stop_reason_at(&self, observed_instant: Instant) -> Option<ModelStopReason> {
281        if self.cancellation.is_cancelled() {
282            Some(ModelStopReason::Cancelled)
283        } else if observed_instant >= self.deadline_instant {
284            Some(ModelStopReason::DeadlineExceeded)
285        } else {
286            None
287        }
288    }
289}
290
291impl fmt::Debug for ModelContext {
292    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
293        formatter
294            .debug_struct("ModelContext")
295            .field("tenant_id", &self.tenant_id)
296            .field("run_id", &self.run_id)
297            .field("thread_id", &self.thread_id)
298            .field("attempt_id", &self.attempt_id)
299            .field("observed_at", &self.observed_at)
300            .field("deadline", &self.deadline())
301            .field("cancelled", &self.cancellation.is_cancelled())
302            .finish_non_exhaustive()
303    }
304}
305
306/// Failure to construct a finite model-attempt context.
307#[derive(Clone, Debug, Eq, Error, PartialEq)]
308#[non_exhaustive]
309pub enum ModelContextError {
310    /// The wall-clock observation reached or passed the durable deadline.
311    #[error("model context deadline {deadline} was reached at {observed_at}")]
312    DeadlineReached {
313        /// Durable absolute deadline.
314        deadline: Timestamp,
315        /// Wall-clock observation used to construct the context.
316        observed_at: Timestamp,
317    },
318    /// The platform monotonic clock could not represent the finite deadline.
319    #[error("model context monotonic deadline is out of range after {remaining:?}")]
320    MonotonicDeadlineOutOfRange {
321        /// Positive duration between the wall-clock observation and deadline.
322        remaining: Duration,
323    },
324}
325
326/// Stage at which one model attempt failed.
327///
328/// The stage is observability evidence, not retry advice and not proof of
329/// provider billing or side-effect outcome. Recovery uses the enclosed
330/// [`crate::RetryAdvice`] and the runtime's independent budget, attempt,
331/// deadline, idempotency, and policy checks.
332#[derive(
333    Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
334)]
335#[non_exhaustive]
336#[serde(rename_all = "snake_case")]
337pub enum ModelErrorPhase {
338    /// Local preparation failed before starting a provider exchange.
339    Preparation,
340    /// A provider exchange was attempted without accepting a complete response or stream.
341    Dispatch,
342    /// A complete-response exchange failed during provider response handling.
343    Response,
344    /// An accepted provider stream failed, possibly after semantic events were emitted.
345    Stream,
346}
347
348/// Correlation evidence attached to a failed model attempt.
349///
350/// Provider identifiers are opaque diagnostic values. They do not grant
351/// authority and are never replay, deduplication, or idempotency keys.
352#[derive(Clone, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
353#[serde(deny_unknown_fields)]
354pub struct ModelErrorProvenance {
355    attempt_id: AttemptId,
356    model: CapabilityIdentity,
357    #[serde(skip_serializing_if = "Option::is_none")]
358    provider_model_id: Option<ModelProviderModelId>,
359    #[serde(skip_serializing_if = "Option::is_none")]
360    provider_request_id: Option<ModelProviderRequestId>,
361    #[serde(skip_serializing_if = "Option::is_none")]
362    provider_response_id: Option<ModelProviderResponseId>,
363}
364
365impl ModelErrorProvenance {
366    /// Constructs failure provenance from validated identity and correlation values.
367    #[must_use]
368    pub fn new(
369        attempt_id: AttemptId,
370        model: CapabilityIdentity,
371        provider_model_id: Option<ModelProviderModelId>,
372        provider_request_id: Option<ModelProviderRequestId>,
373        provider_response_id: Option<ModelProviderResponseId>,
374    ) -> Self {
375        Self {
376            attempt_id,
377            model,
378            provider_model_id,
379            provider_request_id,
380            provider_response_id,
381        }
382    }
383
384    /// Returns the exact execution-attempt identifier.
385    #[must_use]
386    pub const fn attempt_id(&self) -> AttemptId {
387        self.attempt_id
388    }
389
390    /// Returns the stable owner-qualified model binding identity.
391    #[must_use]
392    pub const fn model(&self) -> &CapabilityIdentity {
393        &self.model
394    }
395
396    /// Returns the optional opaque provider model identifier.
397    #[must_use]
398    pub const fn provider_model_id(&self) -> Option<&ModelProviderModelId> {
399        self.provider_model_id.as_ref()
400    }
401
402    /// Returns the optional opaque provider request identifier.
403    #[must_use]
404    pub const fn provider_request_id(&self) -> Option<&ModelProviderRequestId> {
405        self.provider_request_id.as_ref()
406    }
407
408    /// Returns the optional opaque provider response identifier.
409    #[must_use]
410    pub const fn provider_response_id(&self) -> Option<&ModelProviderResponseId> {
411        self.provider_response_id.as_ref()
412    }
413}
414
415impl fmt::Debug for ModelErrorProvenance {
416    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
417        formatter
418            .debug_struct("ModelErrorProvenance")
419            .field("attempt_id", &self.attempt_id)
420            .field("model", &self.model)
421            .field("provider_model_id", &self.provider_model_id)
422            .field("provider_request_id", &self.provider_request_id)
423            .field("provider_response_id", &self.provider_response_id)
424            .finish_non_exhaustive()
425    }
426}
427
428/// Public-safe typed failure returned by a model adapter.
429///
430/// Optional usage is the last complete normalized cumulative snapshot known
431/// for the failed attempt. Missing usage means unknown and must never be
432/// interpreted as zero. Stream consumers discard partial output as a completed
433/// response and separately account for any reported usage.
434#[derive(Clone, Deserialize, JsonSchema, Serialize)]
435#[serde(deny_unknown_fields)]
436pub struct ModelError {
437    failure: Box<Failure>,
438    phase: ModelErrorPhase,
439    provenance: Box<ModelErrorProvenance>,
440    #[serde(skip_serializing_if = "Option::is_none")]
441    usage: Option<ModelUsage>,
442}
443
444impl ModelError {
445    /// Constructs a model failure from validated public-safe components.
446    #[must_use]
447    pub fn new(
448        failure: Failure,
449        phase: ModelErrorPhase,
450        provenance: ModelErrorProvenance,
451        usage: Option<ModelUsage>,
452    ) -> Self {
453        Self {
454            failure: Box::new(failure),
455            phase,
456            provenance: Box::new(provenance),
457            usage,
458        }
459    }
460
461    /// Revalidates attempt, model, response-mode, and usage bindings.
462    ///
463    /// # Errors
464    ///
465    /// Returns [`ModelErrorValidationError`] when this failure does not belong
466    /// to the exact context/descriptor/request snapshot or its reported usage
467    /// exceeds the request ceilings.
468    pub fn validate_for(
469        &self,
470        context: &ModelContext,
471        descriptor: &ModelDescriptor,
472        request: &ModelRequest,
473    ) -> Result<(), ModelErrorValidationError> {
474        self.validate_for_attempt(context.attempt_id, descriptor, request)
475    }
476
477    /// Revalidates this failure against a durable attempt identity and exact
478    /// descriptor/request snapshot.
479    ///
480    /// This is the persistence-safe counterpart to [`Self::validate_for`]: a
481    /// recovered ledger has no process-local monotonic clock or cancellation
482    /// handle, but it must still reject attempt, model, delivery-mode, and usage
483    /// substitution before using the failure as retry evidence.
484    ///
485    /// # Errors
486    ///
487    /// Returns [`ModelErrorValidationError`] for any binding mismatch.
488    pub fn validate_for_attempt(
489        &self,
490        attempt_id: AttemptId,
491        descriptor: &ModelDescriptor,
492        request: &ModelRequest,
493    ) -> Result<(), ModelErrorValidationError> {
494        if self.provenance.attempt_id != attempt_id {
495            return Err(ModelErrorValidationError::AttemptMismatch {
496                expected: attempt_id,
497                actual: self.provenance.attempt_id,
498            });
499        }
500
501        let expected_model = descriptor.metadata().identity();
502        if &self.provenance.model != expected_model {
503            return Err(ModelErrorValidationError::ModelIdentityMismatch {
504                expected: Box::new(expected_model.clone()),
505                actual: Box::new(self.provenance.model.clone()),
506            });
507        }
508
509        let phase_matches_mode = match self.phase {
510            ModelErrorPhase::Preparation | ModelErrorPhase::Dispatch => true,
511            ModelErrorPhase::Response => request.response_mode() == ModelResponseMode::Complete,
512            ModelErrorPhase::Stream => request.response_mode() == ModelResponseMode::Streaming,
513        };
514        if !phase_matches_mode {
515            return Err(ModelErrorValidationError::PhaseResponseModeMismatch {
516                phase: self.phase,
517                response_mode: request.response_mode(),
518            });
519        }
520
521        if let Some(usage) = &self.usage {
522            if usage.input_tokens() > request.limits().max_input_tokens() {
523                return Err(ModelErrorValidationError::InputUsageExceedsRequest {
524                    maximum: request.limits().max_input_tokens(),
525                    actual: usage.input_tokens(),
526                });
527            }
528            if usage.output_tokens() > request.limits().max_output_tokens() {
529                return Err(ModelErrorValidationError::OutputUsageExceedsRequest {
530                    maximum: request.limits().max_output_tokens(),
531                    actual: usage.output_tokens(),
532                });
533            }
534        }
535        Ok(())
536    }
537
538    /// Returns the common public-safe failure occurrence.
539    #[must_use]
540    pub const fn failure(&self) -> &Failure {
541        &self.failure
542    }
543
544    /// Consumes this value and returns the common failure occurrence.
545    #[must_use]
546    pub fn into_failure(self) -> Failure {
547        *self.failure
548    }
549
550    /// Returns the stage at which the attempt failed.
551    #[must_use]
552    pub const fn phase(&self) -> ModelErrorPhase {
553        self.phase
554    }
555
556    /// Returns attempt and provider correlation evidence.
557    #[must_use]
558    pub const fn provenance(&self) -> &ModelErrorProvenance {
559        &self.provenance
560    }
561
562    /// Returns the last complete normalized usage snapshot, when known.
563    #[must_use]
564    pub const fn usage(&self) -> Option<&ModelUsage> {
565        self.usage.as_ref()
566    }
567}
568
569impl fmt::Debug for ModelError {
570    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
571        formatter
572            .debug_struct("ModelError")
573            .field("failure", &self.failure)
574            .field("phase", &self.phase)
575            .field("provenance", &self.provenance)
576            .field("usage", &self.usage)
577            .finish_non_exhaustive()
578    }
579}
580
581impl fmt::Display for ModelError {
582    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
583        fmt::Display::fmt(&self.failure, formatter)
584    }
585}
586
587impl StdError for ModelError {
588    fn source(&self) -> Option<&(dyn StdError + 'static)> {
589        Some(&self.failure)
590    }
591}
592
593/// Invalid relationship between a model failure and its invocation snapshot.
594#[derive(Clone, Debug, Eq, Error, PartialEq)]
595#[non_exhaustive]
596pub enum ModelErrorValidationError {
597    /// Failure provenance named a different attempt.
598    #[error("model failure attempt {actual} does not match context attempt {expected}")]
599    AttemptMismatch {
600        /// Expected context attempt.
601        expected: AttemptId,
602        /// Rejected failure attempt.
603        actual: AttemptId,
604    },
605    /// Failure provenance named a different registered model binding.
606    #[error("model failure identity {actual:?} does not match descriptor {expected:?}")]
607    ModelIdentityMismatch {
608        /// Exact immutable descriptor identity.
609        expected: Box<CapabilityIdentity>,
610        /// Rejected failure claim.
611        actual: Box<CapabilityIdentity>,
612    },
613    /// Failure stage was impossible for the request's delivery mode.
614    #[error("model failure phase {phase:?} is invalid for {response_mode:?} delivery")]
615    PhaseResponseModeMismatch {
616        /// Reported failure stage.
617        phase: ModelErrorPhase,
618        /// Immutable request delivery mode.
619        response_mode: ModelResponseMode,
620    },
621    /// Provider input accounting exceeded the request ceiling.
622    #[error("failed model attempt input usage {actual} exceeds request maximum {maximum}")]
623    InputUsageExceedsRequest {
624        /// Request input-token ceiling.
625        maximum: TokenCount,
626        /// Provider-reported normalized input.
627        actual: TokenCount,
628    },
629    /// Provider output accounting exceeded the request ceiling.
630    #[error("failed model attempt output usage {actual} exceeds request maximum {maximum}")]
631    OutputUsageExceedsRequest {
632        /// Request output-token ceiling.
633        maximum: TokenCount,
634        /// Provider-reported normalized output.
635        actual: TokenCount,
636    },
637}
638
639/// Object-safe, provider-neutral model execution boundary.
640///
641/// Implementations must validate the immutable descriptor capabilities,
642/// registered extensions, and referenced schemas before provider I/O. Unary
643/// invocation accepts only [`ModelResponseMode::Complete`]; streaming accepts
644/// only [`ModelResponseMode::Streaming`]. Every response/event/error must use
645/// the context attempt and descriptor identity.
646///
647/// An adapter must not hide provider SDK retries beneath one [`AttemptId`]. It
648/// disables such retries or arranges for the runtime to create and account for
649/// a distinct attempt before every provider exchange. It enforces the monotonic
650/// deadline and cooperative signal while preserving outcome uncertainty.
651/// A stream emits at most one terminal `Err`, emits nothing afterward, and
652/// never converts transport EOF, provider failure, cancellation, or malformed
653/// output into a successful terminal event.
654pub trait Model: Send + Sync + 'static {
655    /// Returns the immutable descriptor for this exact registered binding.
656    fn descriptor(&self) -> &ModelDescriptor;
657
658    /// Returns the capabilities frozen into the descriptor snapshot.
659    fn capabilities(&self) -> &ModelCapabilities {
660        self.descriptor().capabilities()
661    }
662
663    /// Executes one complete-response model attempt.
664    fn invoke(
665        &self,
666        context: ModelContext,
667        request: ModelRequest,
668    ) -> BoxFuture<'_, Result<ModelResponse, ModelError>>;
669
670    /// Executes one streaming model attempt.
671    fn stream(
672        &self,
673        context: ModelContext,
674        request: ModelRequest,
675    ) -> BoxStream<'_, Result<ModelEvent, ModelError>>;
676}
677
678/// Offline schema resources required by a concrete model adapter.
679///
680/// Implementations expose only canonical, digest-pinned documents installed at
681/// process startup. Adapters use the bytes to construct provider tool and
682/// structured-output declarations, then use [`crate::GraphSchemaValidator`] to
683/// validate provider output locally. Implementations must never retrieve a
684/// schema from its URI while an attempt is executing.
685pub trait ModelSchemaRegistry: crate::GraphSchemaValidator + Send + Sync + 'static {
686    /// Returns exact RFC 8785 canonical JSON Schema bytes for a pinned resource.
687    fn canonical_schema_bytes(&self, schema: &SchemaReference) -> Option<&[u8]>;
688}
689
690#[cfg(test)]
691mod tests {
692    use std::{
693        pin::Pin,
694        task::{Context, Poll},
695    };
696
697    use serde_json::{Value, json, to_value};
698
699    use super::*;
700    use crate::{
701        BudgetUsage, DurationMillis, FailureCategory, FailureCode, FailureId, FailureMessage,
702        FailureOrigin, ResolvedBudget, RetryAdvice,
703    };
704
705    const ATTEMPT_ID: &str = "01912345-6789-7abc-8def-0123456789ab";
706    const RUN_ID: &str = "01912345-6789-7abc-8def-0123456789ac";
707    const THREAD_ID: &str = "01912345-6789-7abc-8def-0123456789ad";
708    const FAILURE_ID: &str = "01912345-6789-7abc-8def-0123456789ae";
709    const OBSERVED_AT: &str = "2029-12-31T23:59:59.000000Z";
710
711    struct AlwaysCancelled;
712
713    impl CancellationObserver for AlwaysCancelled {
714        fn is_cancelled(&self) -> bool {
715            true
716        }
717
718        fn cancelled(&self) -> BoxFuture<'_, ()> {
719            Box::pin(async {})
720        }
721    }
722
723    fn descriptor() -> ModelDescriptor {
724        let fixture: Value = serde_json::from_str(include_str!(
725            "../tests/fixtures/core-model-descriptor-v1.json"
726        ))
727        .unwrap();
728        serde_json::from_value(fixture["descriptors"]["valid"][0].clone()).unwrap()
729    }
730
731    fn request(response_mode: ModelResponseMode) -> ModelRequest {
732        let fixture: Value =
733            serde_json::from_str(include_str!("../tests/fixtures/core-model-request-v1.json"))
734                .unwrap();
735        let mut value = fixture["requests"]["valid"][0].clone();
736        if response_mode == ModelResponseMode::Streaming {
737            value["response_mode"] = Value::from("streaming");
738            value["requirements"]["streaming"] = Value::Bool(true);
739        }
740        serde_json::from_value(value).unwrap()
741    }
742
743    fn remaining_budget(observed_at: Timestamp) -> BudgetRemaining {
744        let fixture: Value =
745            serde_json::from_str(include_str!("../tests/fixtures/core-budget-v1.json")).unwrap();
746        let resolved =
747            serde_json::from_value::<ResolvedBudget>(fixture["resolved"]["valid"][0].clone())
748                .unwrap();
749        resolved
750            .remaining(&BudgetUsage::zero(), observed_at)
751            .unwrap()
752    }
753
754    fn context_with(cancellation: CancellationSignal) -> ModelContext {
755        let observed_at = OBSERVED_AT.parse::<Timestamp>().unwrap();
756        ModelContext::new(
757            TenantId::new("tenant-production").unwrap(),
758            RUN_ID.parse().unwrap(),
759            THREAD_ID.parse().unwrap(),
760            ATTEMPT_ID.parse().unwrap(),
761            remaining_budget(observed_at),
762            observed_at,
763            Instant::now(),
764            cancellation,
765        )
766        .unwrap()
767    }
768
769    fn failure() -> Failure {
770        Failure::new(
771            FAILURE_ID.parse::<FailureId>().unwrap(),
772            FailureCategory::RateLimited,
773            FailureCode::new("provider.rate_limited").unwrap(),
774            FailureOrigin::new("provider.example").unwrap(),
775            FailureMessage::new("The model provider is temporarily unavailable.").unwrap(),
776            RetryAdvice::SafeAfter {
777                delay: DurationMillis::new(250).unwrap(),
778            },
779        )
780        .unwrap()
781    }
782
783    fn provenance(descriptor: &ModelDescriptor, attempt_id: AttemptId) -> ModelErrorProvenance {
784        ModelErrorProvenance::new(
785            attempt_id,
786            descriptor.metadata().identity().clone(),
787            Some(ModelProviderModelId::new("provider-model-v1").unwrap()),
788            Some(ModelProviderRequestId::new("req_01JABCDEF").unwrap()),
789            Some(ModelProviderResponseId::new("resp_01JABCDEF").unwrap()),
790        )
791    }
792
793    #[test]
794    fn cancellation_signal_is_runtime_neutral_cloneable_and_redacted() {
795        let never = CancellationSignal::never();
796        assert!(!never.is_cancelled());
797        assert_eq!(
798            format!("{never:?}"),
799            "CancellationSignal { cancelled: false, .. }"
800        );
801
802        let cancelled = CancellationSignal::new(AlwaysCancelled);
803        assert!(cancelled.is_cancelled());
804        assert!(cancelled.clone().is_cancelled());
805        assert_eq!(
806            format!("{cancelled:?}"),
807            "CancellationSignal { cancelled: true, .. }"
808        );
809    }
810
811    #[test]
812    fn model_context_derives_a_finite_monotonic_deadline() {
813        let observed_at = OBSERVED_AT.parse::<Timestamp>().unwrap();
814        let observed_instant = Instant::now();
815        let context = ModelContext::new(
816            TenantId::new("tenant-production").unwrap(),
817            RUN_ID.parse().unwrap(),
818            THREAD_ID.parse().unwrap(),
819            ATTEMPT_ID.parse().unwrap(),
820            remaining_budget(observed_at),
821            observed_at,
822            observed_instant,
823            CancellationSignal::never(),
824        )
825        .unwrap();
826
827        let expected_remaining = Duration::from_secs(1);
828        assert_eq!(context.observed_at(), observed_at);
829        assert_eq!(
830            context.remaining_time_at(observed_instant),
831            Some(expected_remaining)
832        );
833        assert_eq!(
834            context.deadline_instant(),
835            observed_instant + expected_remaining
836        );
837        assert_eq!(context.stop_reason_at(observed_instant), None);
838        assert_eq!(
839            context.stop_reason_at(context.deadline_instant()),
840            Some(ModelStopReason::DeadlineExceeded)
841        );
842        assert_eq!(context.remaining_time_at(context.deadline_instant()), None);
843    }
844
845    #[test]
846    fn model_context_rejects_reached_deadlines_and_cancellation_wins() {
847        let observed_at = "2030-01-01T00:00:00.000000Z".parse::<Timestamp>().unwrap();
848        let error = ModelContext::new(
849            TenantId::new("tenant-production").unwrap(),
850            RUN_ID.parse().unwrap(),
851            THREAD_ID.parse().unwrap(),
852            ATTEMPT_ID.parse().unwrap(),
853            remaining_budget(OBSERVED_AT.parse().unwrap()),
854            observed_at,
855            Instant::now(),
856            CancellationSignal::never(),
857        )
858        .unwrap_err();
859        assert!(matches!(error, ModelContextError::DeadlineReached { .. }));
860
861        let context = context_with(CancellationSignal::new(AlwaysCancelled));
862        assert_eq!(
863            context.stop_reason_at(context.deadline_instant()),
864            Some(ModelStopReason::Cancelled)
865        );
866    }
867
868    #[test]
869    fn model_context_debug_omits_budget_values_and_monotonic_clock() {
870        let context = context_with(CancellationSignal::never());
871        let debug = format!("{context:?}");
872        assert!(debug.contains("tenant-production"));
873        assert!(debug.contains(ATTEMPT_ID));
874        assert!(!debug.contains("1000000"));
875        assert!(!debug.contains("Instant"));
876    }
877
878    #[test]
879    fn model_error_round_trips_public_evidence_without_leaking_identifiers() {
880        let descriptor = descriptor();
881        let error = ModelError::new(
882            failure(),
883            ModelErrorPhase::Stream,
884            provenance(&descriptor, ATTEMPT_ID.parse().unwrap()),
885            Some(ModelUsage::new(TokenCount::new(120), None, TokenCount::new(7), None).unwrap()),
886        );
887        let value = to_value(&error).unwrap();
888        assert_eq!(value["phase"], "stream");
889        assert_eq!(value["provenance"]["provider_request_id"], "req_01JABCDEF");
890        let decoded = serde_json::from_value::<ModelError>(value.clone()).unwrap();
891        assert_eq!(to_value(decoded).unwrap(), value);
892        assert_eq!(
893            error.to_string(),
894            "The model provider is temporarily unavailable."
895        );
896
897        let debug = format!("{error:?}");
898        assert!(!debug.contains("req_01JABCDEF"));
899        assert!(!debug.contains("resp_01JABCDEF"));
900        assert!(!debug.contains("provider-model-v1"));
901        assert!(!debug.contains("temporarily unavailable"));
902    }
903
904    #[test]
905    fn model_error_validation_binds_attempt_mode_model_and_usage() {
906        let descriptor = descriptor();
907        let context = context_with(CancellationSignal::never());
908        let complete = request(ModelResponseMode::Complete);
909        let valid = ModelError::new(
910            failure(),
911            ModelErrorPhase::Response,
912            provenance(&descriptor, context.attempt_id()),
913            Some(ModelUsage::new(TokenCount::new(120), None, TokenCount::new(7), None).unwrap()),
914        );
915        valid
916            .validate_for(&context, &descriptor, &complete)
917            .unwrap();
918
919        let wrong_attempt = ModelError::new(
920            failure(),
921            ModelErrorPhase::Response,
922            provenance(&descriptor, RUN_ID.parse::<AttemptId>().unwrap()),
923            None,
924        );
925        assert!(matches!(
926            wrong_attempt.validate_for(&context, &descriptor, &complete),
927            Err(ModelErrorValidationError::AttemptMismatch { .. })
928        ));
929
930        let wrong_phase = ModelError::new(
931            failure(),
932            ModelErrorPhase::Stream,
933            provenance(&descriptor, context.attempt_id()),
934            None,
935        );
936        assert_eq!(
937            wrong_phase.validate_for(&context, &descriptor, &complete),
938            Err(ModelErrorValidationError::PhaseResponseModeMismatch {
939                phase: ModelErrorPhase::Stream,
940                response_mode: ModelResponseMode::Complete,
941            })
942        );
943
944        let excessive = ModelError::new(
945            failure(),
946            ModelErrorPhase::Response,
947            provenance(&descriptor, context.attempt_id()),
948            Some(
949                ModelUsage::new(
950                    TokenCount::new(complete.limits().max_input_tokens().get() + 1),
951                    None,
952                    TokenCount::ZERO,
953                    None,
954                )
955                .unwrap(),
956            ),
957        );
958        assert!(matches!(
959            excessive.validate_for(&context, &descriptor, &complete),
960            Err(ModelErrorValidationError::InputUsageExceedsRequest { .. })
961        ));
962    }
963
964    #[test]
965    fn response_provenance_preserves_provider_request_correlation() {
966        let descriptor = descriptor();
967        let provenance = crate::ModelResponseProvenance::new(
968            ATTEMPT_ID.parse().unwrap(),
969            descriptor.metadata().identity().clone(),
970            None,
971            None,
972        )
973        .with_provider_request_id(ModelProviderRequestId::new("req_01JABCDEF").unwrap());
974        assert_eq!(
975            provenance.provider_request_id().unwrap().as_str(),
976            "req_01JABCDEF"
977        );
978        assert_eq!(
979            to_value(&provenance).unwrap()["provider_request_id"],
980            "req_01JABCDEF"
981        );
982        assert!(!format!("{provenance:?}").contains("req_01JABCDEF"));
983    }
984
985    struct EmptyStream;
986
987    impl Stream for EmptyStream {
988        type Item = Result<ModelEvent, ModelError>;
989
990        fn poll_next(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
991            Poll::Ready(None)
992        }
993    }
994
995    struct FakeModel {
996        descriptor: ModelDescriptor,
997    }
998
999    impl Model for FakeModel {
1000        fn descriptor(&self) -> &ModelDescriptor {
1001            &self.descriptor
1002        }
1003
1004        fn invoke(
1005            &self,
1006            _: ModelContext,
1007            _: ModelRequest,
1008        ) -> BoxFuture<'_, Result<ModelResponse, ModelError>> {
1009            Box::pin(pending())
1010        }
1011
1012        fn stream(
1013            &self,
1014            _: ModelContext,
1015            _: ModelRequest,
1016        ) -> BoxStream<'_, Result<ModelEvent, ModelError>> {
1017            Box::pin(EmptyStream)
1018        }
1019    }
1020
1021    #[test]
1022    fn model_trait_is_object_safe_and_boundary_values_are_send_sync() {
1023        fn assert_send_sync<T: Send + Sync>() {}
1024        fn accept_object(_: &dyn Model) {}
1025
1026        assert_send_sync::<ModelContext>();
1027        assert_send_sync::<ModelError>();
1028        assert_send_sync::<CancellationSignal>();
1029
1030        let model = FakeModel {
1031            descriptor: descriptor(),
1032        };
1033        accept_object(&model);
1034        assert_eq!(model.capabilities(), model.descriptor().capabilities());
1035    }
1036
1037    #[test]
1038    fn model_error_schemas_are_closed_and_wire_rejects_unknown_fields() {
1039        for schema in [
1040            to_value(schemars::schema_for!(ModelErrorProvenance)).unwrap(),
1041            to_value(schemars::schema_for!(ModelError)).unwrap(),
1042        ] {
1043            assert_eq!(schema["type"], "object");
1044            assert_eq!(schema["additionalProperties"], false);
1045        }
1046
1047        let descriptor = descriptor();
1048        let error = ModelError::new(
1049            failure(),
1050            ModelErrorPhase::Dispatch,
1051            provenance(&descriptor, ATTEMPT_ID.parse().unwrap()),
1052            None,
1053        );
1054        let mut value = to_value(error).unwrap();
1055        value["provider_payload"] = json!({ "secret": true });
1056        assert!(serde_json::from_value::<ModelError>(value).is_err());
1057    }
1058}