1use 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
27pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
29
30pub type BoxStream<'a, T> = Pin<Box<dyn Stream<Item = T> + Send + 'a>>;
32
33pub trait CancellationObserver: Send + Sync + 'static {
41 fn is_cancelled(&self) -> bool;
43
44 fn cancelled(&self) -> BoxFuture<'_, ()>;
46}
47
48#[derive(Clone)]
54pub struct CancellationSignal {
55 observer: Arc<dyn CancellationObserver>,
56}
57
58impl CancellationSignal {
59 #[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 #[must_use]
72 pub fn from_shared(observer: Arc<dyn CancellationObserver>) -> Self {
73 Self { observer }
74 }
75
76 #[must_use]
82 pub fn never() -> Self {
83 Self::new(NeverCancelled)
84 }
85
86 #[must_use]
88 pub fn is_cancelled(&self) -> bool {
89 self.observer.is_cancelled()
90 }
91
92 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#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
127#[non_exhaustive]
128pub enum ModelStopReason {
129 Cancelled,
131 DeadlineExceeded,
133}
134
135#[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 #[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 #[must_use]
214 pub const fn tenant_id(&self) -> &TenantId {
215 &self.tenant_id
216 }
217
218 #[must_use]
220 pub const fn run_id(&self) -> RunId {
221 self.run_id
222 }
223
224 #[must_use]
226 pub const fn thread_id(&self) -> ThreadId {
227 self.thread_id
228 }
229
230 #[must_use]
232 pub const fn attempt_id(&self) -> AttemptId {
233 self.attempt_id
234 }
235
236 #[must_use]
238 pub const fn budget(&self) -> &BudgetRemaining {
239 &self.budget
240 }
241
242 #[must_use]
244 pub const fn observed_at(&self) -> Timestamp {
245 self.observed_at
246 }
247
248 #[must_use]
250 pub const fn deadline(&self) -> Timestamp {
251 self.budget.deadline()
252 }
253
254 #[must_use]
256 pub const fn deadline_instant(&self) -> Instant {
257 self.deadline_instant
258 }
259
260 #[must_use]
262 pub const fn cancellation(&self) -> &CancellationSignal {
263 &self.cancellation
264 }
265
266 #[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 #[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#[derive(Clone, Debug, Eq, Error, PartialEq)]
308#[non_exhaustive]
309pub enum ModelContextError {
310 #[error("model context deadline {deadline} was reached at {observed_at}")]
312 DeadlineReached {
313 deadline: Timestamp,
315 observed_at: Timestamp,
317 },
318 #[error("model context monotonic deadline is out of range after {remaining:?}")]
320 MonotonicDeadlineOutOfRange {
321 remaining: Duration,
323 },
324}
325
326#[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 Preparation,
340 Dispatch,
342 Response,
344 Stream,
346}
347
348#[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 #[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 #[must_use]
386 pub const fn attempt_id(&self) -> AttemptId {
387 self.attempt_id
388 }
389
390 #[must_use]
392 pub const fn model(&self) -> &CapabilityIdentity {
393 &self.model
394 }
395
396 #[must_use]
398 pub const fn provider_model_id(&self) -> Option<&ModelProviderModelId> {
399 self.provider_model_id.as_ref()
400 }
401
402 #[must_use]
404 pub const fn provider_request_id(&self) -> Option<&ModelProviderRequestId> {
405 self.provider_request_id.as_ref()
406 }
407
408 #[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#[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 #[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 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 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 #[must_use]
540 pub const fn failure(&self) -> &Failure {
541 &self.failure
542 }
543
544 #[must_use]
546 pub fn into_failure(self) -> Failure {
547 *self.failure
548 }
549
550 #[must_use]
552 pub const fn phase(&self) -> ModelErrorPhase {
553 self.phase
554 }
555
556 #[must_use]
558 pub const fn provenance(&self) -> &ModelErrorProvenance {
559 &self.provenance
560 }
561
562 #[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#[derive(Clone, Debug, Eq, Error, PartialEq)]
595#[non_exhaustive]
596pub enum ModelErrorValidationError {
597 #[error("model failure attempt {actual} does not match context attempt {expected}")]
599 AttemptMismatch {
600 expected: AttemptId,
602 actual: AttemptId,
604 },
605 #[error("model failure identity {actual:?} does not match descriptor {expected:?}")]
607 ModelIdentityMismatch {
608 expected: Box<CapabilityIdentity>,
610 actual: Box<CapabilityIdentity>,
612 },
613 #[error("model failure phase {phase:?} is invalid for {response_mode:?} delivery")]
615 PhaseResponseModeMismatch {
616 phase: ModelErrorPhase,
618 response_mode: ModelResponseMode,
620 },
621 #[error("failed model attempt input usage {actual} exceeds request maximum {maximum}")]
623 InputUsageExceedsRequest {
624 maximum: TokenCount,
626 actual: TokenCount,
628 },
629 #[error("failed model attempt output usage {actual} exceeds request maximum {maximum}")]
631 OutputUsageExceedsRequest {
632 maximum: TokenCount,
634 actual: TokenCount,
636 },
637}
638
639pub trait Model: Send + Sync + 'static {
655 fn descriptor(&self) -> &ModelDescriptor;
657
658 fn capabilities(&self) -> &ModelCapabilities {
660 self.descriptor().capabilities()
661 }
662
663 fn invoke(
665 &self,
666 context: ModelContext,
667 request: ModelRequest,
668 ) -> BoxFuture<'_, Result<ModelResponse, ModelError>>;
669
670 fn stream(
672 &self,
673 context: ModelContext,
674 request: ModelRequest,
675 ) -> BoxStream<'_, Result<ModelEvent, ModelError>>;
676}
677
678pub trait ModelSchemaRegistry: crate::GraphSchemaValidator + Send + Sync + 'static {
686 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}