Skip to main content

stateknot_core/
outbox.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Integrity-bound transactional outbox deliveries and delivery attempts.
5//!
6//! An [`OutboxDeliveryIntent`] is supplied beside one journal append and is
7//! materialized as [`OutboxDelivery`] only after that exact origin event has a
8//! durable [`JournalHead`]. A store must insert both records in one database
9//! transaction. This closes the crash window between committing a run fact and
10//! scheduling its notification.
11//!
12//! Delivery is deliberately at-least-once. Every network attempt first commits
13//! a fixed, non-renewable [`DeliveryFence`]. A response may complete the attempt
14//! only before its exclusive expiry. If the process loses an acknowledgement,
15//! a later attempt may repeat the same stable [`DeliveryId`]; destination
16//! adapters therefore accept only duplicate-tolerant notification protocols.
17//! Non-idempotent model and tool side effects belong in their invocation
18//! ledgers, not this outbox.
19
20use std::{collections::BTreeSet, fmt};
21
22use schemars::JsonSchema;
23use serde::{Deserialize, Deserializer, Serialize, de};
24use thiserror::Error;
25
26use crate::{
27    AttemptId, DeliveryId, DestinationId, Digest, EventId, Failure, FencingEpoch, JournalHead,
28    JournalPayload, RetryAdvice, RunId, TenantId, Timestamp,
29};
30
31const INTENT_DIGEST_DOMAIN: &[u8] = b"stateknot-outbox-intent-v1\0";
32const DELIVERY_DIGEST_DOMAIN: &[u8] = b"stateknot-outbox-delivery-v1\0";
33const ATTEMPT_START_DIGEST_DOMAIN: &[u8] = b"stateknot-outbox-attempt-start-v1\0";
34const ATTEMPT_COMPLETION_DIGEST_DOMAIN: &[u8] = b"stateknot-outbox-attempt-completion-v1\0";
35
36/// Hard bound on physical attempts retained for one delivery.
37pub const MAX_OUTBOX_ATTEMPTS: usize = 64;
38
39/// Longest permitted fixed attempt lease, in milliseconds.
40///
41/// Protocol adapters must configure their complete request timeout below this
42/// bound and below the lease they request. Attempts are intentionally not
43/// renewable, keeping takeover and lost-ack behavior deterministic.
44pub const MAX_OUTBOX_ATTEMPT_LEASE_MILLIS: i64 = 300_000;
45
46/// Immutable reference to one tenant-owned destination configuration snapshot.
47///
48/// The referenced snapshot contains protocol routing and credential *handles*;
49/// raw credentials must never be embedded in an outbox record. Keeping the
50/// digest here prevents a destination update from changing an in-flight
51/// delivery's authority or routing semantics.
52#[derive(Clone, Debug, Deserialize, Eq, Hash, JsonSchema, PartialEq, Serialize)]
53#[serde(deny_unknown_fields)]
54pub struct OutboxDestinationRef {
55    tenant_id: TenantId,
56    destination_id: DestinationId,
57    snapshot_digest: Digest,
58}
59
60impl OutboxDestinationRef {
61    /// Constructs an immutable tenant-scoped destination reference.
62    #[must_use]
63    pub const fn new(
64        tenant_id: TenantId,
65        destination_id: DestinationId,
66        snapshot_digest: Digest,
67    ) -> Self {
68        Self {
69            tenant_id,
70            destination_id,
71            snapshot_digest,
72        }
73    }
74
75    /// Returns the tenant boundary.
76    #[must_use]
77    pub const fn tenant_id(&self) -> &TenantId {
78        &self.tenant_id
79    }
80
81    /// Returns the stable destination identity.
82    #[must_use]
83    pub const fn destination_id(&self) -> DestinationId {
84        self.destination_id
85    }
86
87    /// Returns the immutable destination snapshot checksum.
88    #[must_use]
89    pub const fn snapshot_digest(&self) -> Digest {
90        self.snapshot_digest
91    }
92}
93
94/// Idempotent pre-commit request to enqueue one notification.
95///
96/// `origin_event_id` lets a retry prove which journal append must be paired
97/// with this intent. Reusing `delivery_id` is valid only when every field and
98/// `intent_digest` match the existing record.
99#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
100#[serde(deny_unknown_fields)]
101pub struct OutboxDeliveryIntent {
102    tenant_id: TenantId,
103    run_id: RunId,
104    delivery_id: DeliveryId,
105    origin_event_id: EventId,
106    destination: OutboxDestinationRef,
107    payload: JournalPayload,
108    expires_at: Timestamp,
109    intent_digest: Digest,
110}
111
112impl OutboxDeliveryIntent {
113    /// Constructs an integrity-bound enqueue request.
114    ///
115    /// The payload is a schema-pinned canonical envelope consumed by the
116    /// protocol adapter. It is not an arbitrary external side-effect command.
117    ///
118    /// # Errors
119    ///
120    /// Returns [`OutboxDeliveryError`] for a crossed tenant boundary or an
121    /// integrity calculation failure.
122    #[allow(clippy::too_many_arguments)]
123    pub fn new(
124        tenant_id: TenantId,
125        run_id: RunId,
126        delivery_id: DeliveryId,
127        origin_event_id: EventId,
128        destination: OutboxDestinationRef,
129        payload: JournalPayload,
130        expires_at: Timestamp,
131    ) -> Result<Self, OutboxDeliveryError> {
132        if destination.tenant_id() != &tenant_id {
133            return Err(OutboxDeliveryError::DestinationTenantMismatch);
134        }
135        let intent_digest = compute_intent_digest(&OutboxIntentDigestWire {
136            tenant_id: &tenant_id,
137            run_id,
138            delivery_id,
139            origin_event_id,
140            destination: &destination,
141            payload_digest: payload.digest(),
142            expires_at,
143        })?;
144        Ok(Self {
145            tenant_id,
146            run_id,
147            delivery_id,
148            origin_event_id,
149            destination,
150            payload,
151            expires_at,
152            intent_digest,
153        })
154    }
155
156    /// Restores and verifies a persisted enqueue request.
157    ///
158    /// # Errors
159    ///
160    /// Returns [`OutboxDeliveryError`] when scope or the checksum differs.
161    #[allow(clippy::too_many_arguments)]
162    pub fn restore(
163        tenant_id: TenantId,
164        run_id: RunId,
165        delivery_id: DeliveryId,
166        origin_event_id: EventId,
167        destination: OutboxDestinationRef,
168        payload: JournalPayload,
169        expires_at: Timestamp,
170        intent_digest: Digest,
171    ) -> Result<Self, OutboxDeliveryError> {
172        let restored = Self::new(
173            tenant_id,
174            run_id,
175            delivery_id,
176            origin_event_id,
177            destination,
178            payload,
179            expires_at,
180        )?;
181        if restored.intent_digest != intent_digest {
182            return Err(OutboxDeliveryError::IntentDigestMismatch);
183        }
184        Ok(restored)
185    }
186
187    /// Returns the tenant boundary.
188    #[must_use]
189    pub const fn tenant_id(&self) -> &TenantId {
190        &self.tenant_id
191    }
192
193    /// Returns the owning run.
194    #[must_use]
195    pub const fn run_id(&self) -> RunId {
196        self.run_id
197    }
198
199    /// Returns the stable delivery identity used across retries.
200    #[must_use]
201    pub const fn delivery_id(&self) -> DeliveryId {
202        self.delivery_id
203    }
204
205    /// Returns the exact origin event requested by the caller.
206    #[must_use]
207    pub const fn origin_event_id(&self) -> EventId {
208        self.origin_event_id
209    }
210
211    /// Returns the immutable destination snapshot reference.
212    #[must_use]
213    pub const fn destination(&self) -> &OutboxDestinationRef {
214        &self.destination
215    }
216
217    /// Returns the immutable schema-pinned delivery payload.
218    #[must_use]
219    pub const fn payload(&self) -> &JournalPayload {
220        &self.payload
221    }
222
223    /// Returns the exclusive delivery deadline.
224    #[must_use]
225    pub const fn expires_at(&self) -> Timestamp {
226        self.expires_at
227    }
228
229    /// Returns the complete idempotency checksum.
230    #[must_use]
231    pub const fn intent_digest(&self) -> Digest {
232        self.intent_digest
233    }
234}
235
236impl fmt::Debug for OutboxDeliveryIntent {
237    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
238        formatter
239            .debug_struct("OutboxDeliveryIntent")
240            .field("tenant_id", &self.tenant_id)
241            .field("run_id", &self.run_id)
242            .field("delivery_id", &self.delivery_id)
243            .field("origin_event_id", &self.origin_event_id)
244            .field("destination", &self.destination)
245            .field("payload", &self.payload)
246            .field("expires_at", &self.expires_at)
247            .field("intent_digest", &self.intent_digest)
248            .finish_non_exhaustive()
249    }
250}
251
252impl<'de> Deserialize<'de> for OutboxDeliveryIntent {
253    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
254    where
255        D: Deserializer<'de>,
256    {
257        #[derive(Deserialize)]
258        #[serde(deny_unknown_fields)]
259        struct Wire {
260            tenant_id: TenantId,
261            run_id: RunId,
262            delivery_id: DeliveryId,
263            origin_event_id: EventId,
264            destination: OutboxDestinationRef,
265            payload: JournalPayload,
266            expires_at: Timestamp,
267            intent_digest: Digest,
268        }
269
270        let wire = Wire::deserialize(deserializer)?;
271        Self::restore(
272            wire.tenant_id,
273            wire.run_id,
274            wire.delivery_id,
275            wire.origin_event_id,
276            wire.destination,
277            wire.payload,
278            wire.expires_at,
279            wire.intent_digest,
280        )
281        .map_err(de::Error::custom)
282    }
283}
284
285/// Immutable outbox record atomically committed with its origin journal fact.
286#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
287#[serde(deny_unknown_fields)]
288pub struct OutboxDelivery {
289    intent: OutboxDeliveryIntent,
290    origin: JournalHead,
291    digest: Digest,
292}
293
294impl OutboxDelivery {
295    /// Materializes an enqueue intent against the exact committed origin.
296    ///
297    /// # Errors
298    ///
299    /// Returns [`OutboxDeliveryError`] for substituted scope/event identity, a
300    /// deadline that is not after the origin, or integrity failure.
301    pub fn commit(
302        intent: OutboxDeliveryIntent,
303        origin: JournalHead,
304    ) -> Result<Self, OutboxDeliveryError> {
305        validate_delivery_shape(&intent, &origin)?;
306        let digest = compute_delivery_digest(&OutboxDeliveryDigestWire {
307            tenant_id: &intent.tenant_id,
308            run_id: intent.run_id,
309            delivery_id: intent.delivery_id,
310            intent_digest: intent.intent_digest,
311            origin: &origin,
312            expires_at: intent.expires_at,
313        })?;
314        Ok(Self {
315            intent,
316            origin,
317            digest,
318        })
319    }
320
321    /// Restores and verifies a durable delivery record.
322    ///
323    /// # Errors
324    ///
325    /// Returns [`OutboxDeliveryError`] when any invariant or checksum differs.
326    pub fn restore(
327        intent: OutboxDeliveryIntent,
328        origin: JournalHead,
329        digest: Digest,
330    ) -> Result<Self, OutboxDeliveryError> {
331        let restored = Self::commit(intent, origin)?;
332        if restored.digest != digest {
333            return Err(OutboxDeliveryError::DeliveryDigestMismatch);
334        }
335        Ok(restored)
336    }
337
338    /// Returns the immutable enqueue intent.
339    #[must_use]
340    pub const fn intent(&self) -> &OutboxDeliveryIntent {
341        &self.intent
342    }
343
344    /// Returns the exact atomically paired journal origin.
345    #[must_use]
346    pub const fn origin(&self) -> &JournalHead {
347        &self.origin
348    }
349
350    /// Returns the complete delivery checksum.
351    #[must_use]
352    pub const fn digest(&self) -> Digest {
353        self.digest
354    }
355
356    /// Returns a compact exact reference used by attempt records.
357    #[must_use]
358    pub fn head(&self) -> OutboxDeliveryHead {
359        OutboxDeliveryHead {
360            tenant_id: self.intent.tenant_id.clone(),
361            run_id: self.intent.run_id,
362            delivery_id: self.intent.delivery_id,
363            origin: self.origin.clone(),
364            intent_digest: self.intent.intent_digest,
365            expires_at: self.intent.expires_at,
366            digest: self.digest,
367        }
368    }
369}
370
371impl fmt::Debug for OutboxDelivery {
372    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
373        formatter
374            .debug_struct("OutboxDelivery")
375            .field("intent", &self.intent)
376            .field("origin", &self.origin)
377            .field("digest", &self.digest)
378            .finish_non_exhaustive()
379    }
380}
381
382impl<'de> Deserialize<'de> for OutboxDelivery {
383    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
384    where
385        D: Deserializer<'de>,
386    {
387        #[derive(Deserialize)]
388        #[serde(deny_unknown_fields)]
389        struct Wire {
390            intent: OutboxDeliveryIntent,
391            origin: JournalHead,
392            digest: Digest,
393        }
394
395        let wire = Wire::deserialize(deserializer)?;
396        Self::restore(wire.intent, wire.origin, wire.digest).map_err(de::Error::custom)
397    }
398}
399
400/// Compact, integrity-verifiable identity of one committed delivery.
401#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
402#[serde(deny_unknown_fields)]
403pub struct OutboxDeliveryHead {
404    tenant_id: TenantId,
405    run_id: RunId,
406    delivery_id: DeliveryId,
407    origin: JournalHead,
408    intent_digest: Digest,
409    expires_at: Timestamp,
410    digest: Digest,
411}
412
413impl OutboxDeliveryHead {
414    /// Restores and verifies a compact delivery identity.
415    ///
416    /// # Errors
417    ///
418    /// Returns [`OutboxDeliveryError`] for crossed scope, an invalid deadline,
419    /// or a checksum mismatch.
420    #[allow(clippy::too_many_arguments)]
421    pub fn restore(
422        tenant_id: TenantId,
423        run_id: RunId,
424        delivery_id: DeliveryId,
425        origin: JournalHead,
426        intent_digest: Digest,
427        expires_at: Timestamp,
428        digest: Digest,
429    ) -> Result<Self, OutboxDeliveryError> {
430        validate_delivery_head_scope(&tenant_id, run_id, &origin, expires_at)?;
431        let expected = compute_delivery_digest(&OutboxDeliveryDigestWire {
432            tenant_id: &tenant_id,
433            run_id,
434            delivery_id,
435            intent_digest,
436            origin: &origin,
437            expires_at,
438        })?;
439        if expected != digest {
440            return Err(OutboxDeliveryError::DeliveryDigestMismatch);
441        }
442        Ok(Self {
443            tenant_id,
444            run_id,
445            delivery_id,
446            origin,
447            intent_digest,
448            expires_at,
449            digest,
450        })
451    }
452
453    /// Returns the tenant boundary.
454    #[must_use]
455    pub const fn tenant_id(&self) -> &TenantId {
456        &self.tenant_id
457    }
458
459    /// Returns the owning run.
460    #[must_use]
461    pub const fn run_id(&self) -> RunId {
462        self.run_id
463    }
464
465    /// Returns the stable delivery identity.
466    #[must_use]
467    pub const fn delivery_id(&self) -> DeliveryId {
468        self.delivery_id
469    }
470
471    /// Returns the exact origin journal head.
472    #[must_use]
473    pub const fn origin(&self) -> &JournalHead {
474        &self.origin
475    }
476
477    /// Returns the enqueue intent checksum.
478    #[must_use]
479    pub const fn intent_digest(&self) -> Digest {
480        self.intent_digest
481    }
482
483    /// Returns the exclusive delivery deadline.
484    #[must_use]
485    pub const fn expires_at(&self) -> Timestamp {
486        self.expires_at
487    }
488
489    /// Returns the full delivery checksum.
490    #[must_use]
491    pub const fn digest(&self) -> Digest {
492        self.digest
493    }
494}
495
496impl<'de> Deserialize<'de> for OutboxDeliveryHead {
497    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
498    where
499        D: Deserializer<'de>,
500    {
501        #[derive(Deserialize)]
502        #[serde(deny_unknown_fields)]
503        struct Wire {
504            tenant_id: TenantId,
505            run_id: RunId,
506            delivery_id: DeliveryId,
507            origin: JournalHead,
508            intent_digest: Digest,
509            expires_at: Timestamp,
510            digest: Digest,
511        }
512
513        let wire = Wire::deserialize(deserializer)?;
514        Self::restore(
515            wire.tenant_id,
516            wire.run_id,
517            wire.delivery_id,
518            wire.origin,
519            wire.intent_digest,
520            wire.expires_at,
521            wire.digest,
522        )
523        .map_err(de::Error::custom)
524    }
525}
526
527/// Fencing token authorizing one fixed physical delivery attempt.
528///
529/// The token is not authority by itself. Completion stores must compare every
530/// field and the database clock against the locked current delivery row in the
531/// same transaction.
532#[derive(Clone, Debug, Deserialize, Eq, Hash, JsonSchema, PartialEq, Serialize)]
533#[serde(deny_unknown_fields)]
534pub struct DeliveryFence {
535    tenant_id: TenantId,
536    run_id: RunId,
537    delivery_id: DeliveryId,
538    attempt_id: AttemptId,
539    epoch: FencingEpoch,
540}
541
542impl DeliveryFence {
543    /// Constructs a delivery-scoped fence from trusted allocation results.
544    #[must_use]
545    pub const fn new(
546        tenant_id: TenantId,
547        run_id: RunId,
548        delivery_id: DeliveryId,
549        attempt_id: AttemptId,
550        epoch: FencingEpoch,
551    ) -> Self {
552        Self {
553            tenant_id,
554            run_id,
555            delivery_id,
556            attempt_id,
557            epoch,
558        }
559    }
560
561    /// Returns the tenant boundary.
562    #[must_use]
563    pub const fn tenant_id(&self) -> &TenantId {
564        &self.tenant_id
565    }
566
567    /// Returns the owning run.
568    #[must_use]
569    pub const fn run_id(&self) -> RunId {
570        self.run_id
571    }
572
573    /// Returns the fenced delivery.
574    #[must_use]
575    pub const fn delivery_id(&self) -> DeliveryId {
576        self.delivery_id
577    }
578
579    /// Returns the unique physical attempt identity.
580    #[must_use]
581    pub const fn attempt_id(&self) -> AttemptId {
582        self.attempt_id
583    }
584
585    /// Returns the monotonic delivery ownership epoch.
586    #[must_use]
587    pub const fn epoch(&self) -> FencingEpoch {
588        self.epoch
589    }
590}
591
592/// Lifecycle state of one physical outbox attempt.
593#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, PartialEq, Serialize)]
594#[serde(rename_all = "snake_case")]
595#[non_exhaustive]
596pub enum OutboxAttemptStatus {
597    /// The attempt is durably started and has no completion.
598    Delivering,
599    /// The destination acknowledged the notification.
600    Acknowledged,
601    /// Public-safe failure evidence was committed.
602    Failed,
603}
604
605/// Terminal outcome of one physical delivery attempt.
606#[allow(clippy::large_enum_variant)]
607#[derive(Clone, JsonSchema, Serialize)]
608#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
609#[non_exhaustive]
610pub enum OutboxAttemptOutcome {
611    /// The destination returned a protocol-defined acknowledgement.
612    Acknowledged {
613        /// Optional digest of bounded, non-secret acknowledgement evidence.
614        #[serde(skip_serializing_if = "Option::is_none")]
615        evidence_digest: Option<Digest>,
616    },
617    /// The attempt failed with explicit retry advice.
618    Failed {
619        /// Public-safe failure evidence; secrets and raw response bodies are forbidden.
620        failure: Failure,
621    },
622}
623
624impl OutboxAttemptOutcome {
625    /// Returns the terminal physical-attempt status.
626    #[must_use]
627    pub const fn status(&self) -> OutboxAttemptStatus {
628        match self {
629            Self::Acknowledged { .. } => OutboxAttemptStatus::Acknowledged,
630            Self::Failed { .. } => OutboxAttemptStatus::Failed,
631        }
632    }
633
634    /// Returns acknowledgement evidence, if the attempt succeeded.
635    #[must_use]
636    pub const fn evidence_digest(&self) -> Option<Digest> {
637        match self {
638            Self::Acknowledged { evidence_digest } => *evidence_digest,
639            Self::Failed { .. } => None,
640        }
641    }
642
643    /// Returns public-safe failure evidence, if the attempt failed.
644    #[must_use]
645    pub const fn failure(&self) -> Option<&Failure> {
646        match self {
647            Self::Acknowledged { .. } => None,
648            Self::Failed { failure } => Some(failure),
649        }
650    }
651}
652
653impl fmt::Debug for OutboxAttemptOutcome {
654    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
655        match self {
656            Self::Acknowledged { evidence_digest } => formatter
657                .debug_struct("Acknowledged")
658                .field("evidence_digest", evidence_digest)
659                .finish(),
660            Self::Failed { failure } => formatter
661                .debug_struct("Failed")
662                .field("failure_id", &failure.id())
663                .field("category", &failure.category())
664                .field("code", failure.code())
665                .field("origin", failure.origin())
666                .field("retry_advice", &failure.retry_advice())
667                .finish_non_exhaustive(),
668        }
669    }
670}
671
672impl<'de> Deserialize<'de> for OutboxAttemptOutcome {
673    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
674    where
675        D: Deserializer<'de>,
676    {
677        #[allow(clippy::large_enum_variant)]
678        #[derive(Deserialize)]
679        #[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
680        enum Wire {
681            Acknowledged {
682                #[serde(default)]
683                evidence_digest: Option<Digest>,
684            },
685            Failed {
686                failure: Failure,
687            },
688        }
689
690        Ok(match Wire::deserialize(deserializer)? {
691            Wire::Acknowledged { evidence_digest } => Self::Acknowledged { evidence_digest },
692            Wire::Failed { failure } => Self::Failed { failure },
693        })
694    }
695}
696
697/// Durable admission record committed before one network request begins.
698#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
699#[serde(deny_unknown_fields)]
700pub struct OutboxAttemptStart {
701    delivery: OutboxDeliveryHead,
702    fence: DeliveryFence,
703    started_at: Timestamp,
704    expires_at: Timestamp,
705    digest: Digest,
706}
707
708impl OutboxAttemptStart {
709    /// Constructs a fixed, non-renewable attempt lease.
710    ///
711    /// # Errors
712    ///
713    /// Returns [`OutboxAttemptError`] for crossed scope, timing outside the
714    /// delivery window, a lease over five minutes, or integrity failure.
715    pub fn new(
716        delivery: &OutboxDelivery,
717        fence: DeliveryFence,
718        started_at: Timestamp,
719        expires_at: Timestamp,
720    ) -> Result<Self, OutboxAttemptError> {
721        Self::materialize(delivery.head(), fence, started_at, expires_at)
722    }
723
724    /// Restores and verifies a durable attempt start.
725    ///
726    /// # Errors
727    ///
728    /// Returns [`OutboxAttemptError`] when any invariant or checksum differs.
729    pub fn restore(
730        delivery: OutboxDeliveryHead,
731        fence: DeliveryFence,
732        started_at: Timestamp,
733        expires_at: Timestamp,
734        digest: Digest,
735    ) -> Result<Self, OutboxAttemptError> {
736        let restored = Self::materialize(delivery, fence, started_at, expires_at)?;
737        if restored.digest != digest {
738            return Err(OutboxAttemptError::StartDigestMismatch);
739        }
740        Ok(restored)
741    }
742
743    fn materialize(
744        delivery: OutboxDeliveryHead,
745        fence: DeliveryFence,
746        started_at: Timestamp,
747        expires_at: Timestamp,
748    ) -> Result<Self, OutboxAttemptError> {
749        validate_attempt_start(&delivery, &fence, started_at, expires_at)?;
750        let digest = compute_attempt_start_digest(&OutboxAttemptStartDigestWire {
751            delivery: &delivery,
752            fence: &fence,
753            started_at,
754            expires_at,
755        })?;
756        Ok(Self {
757            delivery,
758            fence,
759            started_at,
760            expires_at,
761            digest,
762        })
763    }
764
765    /// Returns the exact delivery being attempted.
766    #[must_use]
767    pub const fn delivery(&self) -> &OutboxDeliveryHead {
768        &self.delivery
769    }
770
771    /// Returns the attempt fence.
772    #[must_use]
773    pub const fn fence(&self) -> &DeliveryFence {
774        &self.fence
775    }
776
777    /// Returns the database start observation.
778    #[must_use]
779    pub const fn started_at(&self) -> Timestamp {
780        self.started_at
781    }
782
783    /// Returns the exclusive fixed attempt expiry.
784    #[must_use]
785    pub const fn expires_at(&self) -> Timestamp {
786        self.expires_at
787    }
788
789    /// Returns the full start checksum.
790    #[must_use]
791    pub const fn digest(&self) -> Digest {
792        self.digest
793    }
794
795    /// Returns a compact exact reference used by completion records.
796    #[must_use]
797    pub fn head(&self) -> OutboxAttemptStartHead {
798        OutboxAttemptStartHead {
799            delivery: self.delivery.clone(),
800            fence: self.fence.clone(),
801            started_at: self.started_at,
802            expires_at: self.expires_at,
803            digest: self.digest,
804        }
805    }
806}
807
808impl fmt::Debug for OutboxAttemptStart {
809    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
810        formatter
811            .debug_struct("OutboxAttemptStart")
812            .field("delivery", &self.delivery)
813            .field("fence", &self.fence)
814            .field("started_at", &self.started_at)
815            .field("expires_at", &self.expires_at)
816            .field("digest", &self.digest)
817            .finish_non_exhaustive()
818    }
819}
820
821impl<'de> Deserialize<'de> for OutboxAttemptStart {
822    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
823    where
824        D: Deserializer<'de>,
825    {
826        #[derive(Deserialize)]
827        #[serde(deny_unknown_fields)]
828        struct Wire {
829            delivery: OutboxDeliveryHead,
830            fence: DeliveryFence,
831            started_at: Timestamp,
832            expires_at: Timestamp,
833            digest: Digest,
834        }
835
836        let wire = Wire::deserialize(deserializer)?;
837        Self::restore(
838            wire.delivery,
839            wire.fence,
840            wire.started_at,
841            wire.expires_at,
842            wire.digest,
843        )
844        .map_err(de::Error::custom)
845    }
846}
847
848/// Compact exact identity of one durable delivery-attempt start.
849#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
850#[serde(deny_unknown_fields)]
851pub struct OutboxAttemptStartHead {
852    delivery: OutboxDeliveryHead,
853    fence: DeliveryFence,
854    started_at: Timestamp,
855    expires_at: Timestamp,
856    digest: Digest,
857}
858
859impl OutboxAttemptStartHead {
860    /// Restores and verifies a compact start identity.
861    ///
862    /// # Errors
863    ///
864    /// Returns [`OutboxAttemptError`] for invalid scope, timing, or checksum.
865    pub fn restore(
866        delivery: OutboxDeliveryHead,
867        fence: DeliveryFence,
868        started_at: Timestamp,
869        expires_at: Timestamp,
870        digest: Digest,
871    ) -> Result<Self, OutboxAttemptError> {
872        Ok(OutboxAttemptStart::restore(delivery, fence, started_at, expires_at, digest)?.head())
873    }
874
875    /// Returns the exact delivery identity.
876    #[must_use]
877    pub const fn delivery(&self) -> &OutboxDeliveryHead {
878        &self.delivery
879    }
880
881    /// Returns the exact attempt fence.
882    #[must_use]
883    pub const fn fence(&self) -> &DeliveryFence {
884        &self.fence
885    }
886
887    /// Returns the database start observation.
888    #[must_use]
889    pub const fn started_at(&self) -> Timestamp {
890        self.started_at
891    }
892
893    /// Returns the exclusive fixed attempt expiry.
894    #[must_use]
895    pub const fn expires_at(&self) -> Timestamp {
896        self.expires_at
897    }
898
899    /// Returns the complete start checksum.
900    #[must_use]
901    pub const fn digest(&self) -> Digest {
902        self.digest
903    }
904}
905
906impl<'de> Deserialize<'de> for OutboxAttemptStartHead {
907    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
908    where
909        D: Deserializer<'de>,
910    {
911        #[derive(Deserialize)]
912        #[serde(deny_unknown_fields)]
913        struct Wire {
914            delivery: OutboxDeliveryHead,
915            fence: DeliveryFence,
916            started_at: Timestamp,
917            expires_at: Timestamp,
918            digest: Digest,
919        }
920
921        let wire = Wire::deserialize(deserializer)?;
922        OutboxAttemptStart::restore(
923            wire.delivery,
924            wire.fence,
925            wire.started_at,
926            wire.expires_at,
927            wire.digest,
928        )
929        .map(|start| start.head())
930        .map_err(de::Error::custom)
931    }
932}
933
934/// Immutable terminal record for one already-started delivery attempt.
935#[derive(Clone, JsonSchema, Serialize)]
936#[serde(deny_unknown_fields)]
937pub struct OutboxAttemptCompletion {
938    start: OutboxAttemptStartHead,
939    outcome: OutboxAttemptOutcome,
940    completed_at: Timestamp,
941    digest: Digest,
942}
943
944impl OutboxAttemptCompletion {
945    /// Commits a protocol acknowledgement before the attempt fence expires.
946    ///
947    /// # Errors
948    ///
949    /// Returns [`OutboxAttemptError`] for invalid timing or integrity material.
950    pub fn acknowledge(
951        start: &OutboxAttemptStart,
952        evidence_digest: Option<Digest>,
953        completed_at: Timestamp,
954    ) -> Result<Self, OutboxAttemptError> {
955        Self::materialize(
956            start.head(),
957            OutboxAttemptOutcome::Acknowledged { evidence_digest },
958            completed_at,
959        )
960    }
961
962    /// Commits public-safe failure evidence before the attempt fence expires.
963    ///
964    /// Reconcile-first failures are rejected: outbox destinations must tolerate
965    /// duplicate delivery and may therefore use only safe-after or never.
966    ///
967    /// # Errors
968    ///
969    /// Returns [`OutboxAttemptError`] for unsafe retry advice, invalid timing,
970    /// or integrity material.
971    pub fn fail(
972        start: &OutboxAttemptStart,
973        failure: Failure,
974        completed_at: Timestamp,
975    ) -> Result<Self, OutboxAttemptError> {
976        Self::materialize(
977            start.head(),
978            OutboxAttemptOutcome::Failed { failure },
979            completed_at,
980        )
981    }
982
983    /// Restores and verifies a persisted terminal record.
984    ///
985    /// # Errors
986    ///
987    /// Returns [`OutboxAttemptError`] when any invariant or checksum differs.
988    pub fn restore(
989        start: OutboxAttemptStartHead,
990        outcome: OutboxAttemptOutcome,
991        completed_at: Timestamp,
992        digest: Digest,
993    ) -> Result<Self, OutboxAttemptError> {
994        let restored = Self::materialize(start, outcome, completed_at)?;
995        if restored.digest != digest {
996            return Err(OutboxAttemptError::CompletionDigestMismatch);
997        }
998        Ok(restored)
999    }
1000
1001    fn materialize(
1002        start: OutboxAttemptStartHead,
1003        outcome: OutboxAttemptOutcome,
1004        completed_at: Timestamp,
1005    ) -> Result<Self, OutboxAttemptError> {
1006        validate_attempt_completion(&start, &outcome, completed_at)?;
1007        let digest = compute_attempt_completion_digest(&OutboxAttemptCompletionDigestWire {
1008            start: &start,
1009            outcome: &outcome,
1010            completed_at,
1011        })?;
1012        Ok(Self {
1013            start,
1014            outcome,
1015            completed_at,
1016            digest,
1017        })
1018    }
1019
1020    /// Returns the exact attempt start completed by this record.
1021    #[must_use]
1022    pub const fn start(&self) -> &OutboxAttemptStartHead {
1023        &self.start
1024    }
1025
1026    /// Returns the terminal outcome.
1027    #[must_use]
1028    pub const fn outcome(&self) -> &OutboxAttemptOutcome {
1029        &self.outcome
1030    }
1031
1032    /// Returns the terminal physical-attempt status.
1033    #[must_use]
1034    pub const fn status(&self) -> OutboxAttemptStatus {
1035        self.outcome.status()
1036    }
1037
1038    /// Returns the database completion observation.
1039    #[must_use]
1040    pub const fn completed_at(&self) -> Timestamp {
1041        self.completed_at
1042    }
1043
1044    /// Returns the complete terminal-record checksum.
1045    #[must_use]
1046    pub const fn digest(&self) -> Digest {
1047        self.digest
1048    }
1049}
1050
1051impl fmt::Debug for OutboxAttemptCompletion {
1052    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1053        formatter
1054            .debug_struct("OutboxAttemptCompletion")
1055            .field("start", &self.start)
1056            .field("outcome", &self.outcome)
1057            .field("completed_at", &self.completed_at)
1058            .field("digest", &self.digest)
1059            .finish_non_exhaustive()
1060    }
1061}
1062
1063impl<'de> Deserialize<'de> for OutboxAttemptCompletion {
1064    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1065    where
1066        D: Deserializer<'de>,
1067    {
1068        #[derive(Deserialize)]
1069        #[serde(deny_unknown_fields)]
1070        struct Wire {
1071            start: OutboxAttemptStartHead,
1072            outcome: OutboxAttemptOutcome,
1073            completed_at: Timestamp,
1074            digest: Digest,
1075        }
1076
1077        let wire = Wire::deserialize(deserializer)?;
1078        Self::restore(wire.start, wire.outcome, wire.completed_at, wire.digest)
1079            .map_err(de::Error::custom)
1080    }
1081}
1082
1083/// Fully restored physical delivery attempt, active or terminal.
1084#[derive(Clone, JsonSchema, Serialize)]
1085#[serde(deny_unknown_fields)]
1086pub struct OutboxAttempt {
1087    start: OutboxAttemptStart,
1088    #[serde(skip_serializing_if = "Option::is_none")]
1089    completion: Option<OutboxAttemptCompletion>,
1090}
1091
1092impl OutboxAttempt {
1093    /// Constructs an active attempt from its durable start.
1094    #[must_use]
1095    pub const fn delivering(start: OutboxAttemptStart) -> Self {
1096        Self {
1097            start,
1098            completion: None,
1099        }
1100    }
1101
1102    /// Restores an attempt and verifies the exact start/completion join.
1103    ///
1104    /// # Errors
1105    ///
1106    /// Returns [`OutboxAttemptError::CompletionStartMismatch`] for a crossed
1107    /// physical attempt.
1108    pub fn restore(
1109        start: OutboxAttemptStart,
1110        completion: Option<OutboxAttemptCompletion>,
1111    ) -> Result<Self, OutboxAttemptError> {
1112        if completion
1113            .as_ref()
1114            .is_some_and(|completion| completion.start() != &start.head())
1115        {
1116            return Err(OutboxAttemptError::CompletionStartMismatch);
1117        }
1118        Ok(Self { start, completion })
1119    }
1120
1121    /// Returns the immutable durable start.
1122    #[must_use]
1123    pub const fn start(&self) -> &OutboxAttemptStart {
1124        &self.start
1125    }
1126
1127    /// Returns the optional terminal completion.
1128    #[must_use]
1129    pub const fn completion(&self) -> Option<&OutboxAttemptCompletion> {
1130        self.completion.as_ref()
1131    }
1132
1133    /// Returns the current physical-attempt status.
1134    #[must_use]
1135    pub const fn status(&self) -> OutboxAttemptStatus {
1136        match &self.completion {
1137            Some(completion) => completion.status(),
1138            None => OutboxAttemptStatus::Delivering,
1139        }
1140    }
1141}
1142
1143impl fmt::Debug for OutboxAttempt {
1144    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1145        formatter
1146            .debug_struct("OutboxAttempt")
1147            .field("start", &self.start)
1148            .field("completion", &self.completion)
1149            .finish_non_exhaustive()
1150    }
1151}
1152
1153impl<'de> Deserialize<'de> for OutboxAttempt {
1154    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
1155    where
1156        D: Deserializer<'de>,
1157    {
1158        #[derive(Deserialize)]
1159        #[serde(deny_unknown_fields)]
1160        struct Wire {
1161            start: OutboxAttemptStart,
1162            #[serde(default)]
1163            completion: Option<OutboxAttemptCompletion>,
1164        }
1165
1166        let wire = Wire::deserialize(deserializer)?;
1167        Self::restore(wire.start, wire.completion).map_err(de::Error::custom)
1168    }
1169}
1170
1171/// Projected lifecycle of a complete delivery at one database observation.
1172#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, JsonSchema, PartialEq, Serialize)]
1173#[serde(rename_all = "snake_case")]
1174#[non_exhaustive]
1175pub enum OutboxDeliveryStatus {
1176    /// Eligible for a new physical attempt.
1177    Pending,
1178    /// A fixed attempt lease is still live.
1179    Delivering,
1180    /// A safe retry exists but its delay has not elapsed.
1181    RetryScheduled,
1182    /// A destination acknowledgement terminated delivery.
1183    Acknowledged,
1184    /// Retry advice or the hard attempt bound terminated delivery.
1185    DeadLetter,
1186    /// The delivery deadline elapsed before acknowledgement.
1187    Expired,
1188}
1189
1190/// Streaming validator and state projector for one delivery's attempt history.
1191///
1192/// Attempts use epoch one followed by exact successors. An uncompleted attempt
1193/// can be replaced only after its fixed exclusive expiry. This verifier is
1194/// bounded and rejects rather than mutates its state on every invalid record.
1195#[derive(Clone, Debug)]
1196pub struct OutboxAttemptHistoryVerifier {
1197    delivery: OutboxDeliveryHead,
1198    last: Option<OutboxAttempt>,
1199    attempt_ids: BTreeSet<AttemptId>,
1200    count: usize,
1201}
1202
1203impl OutboxAttemptHistoryVerifier {
1204    /// Constructs an empty verifier for one committed delivery.
1205    #[must_use]
1206    pub fn new(delivery: &OutboxDelivery) -> Self {
1207        Self {
1208            delivery: delivery.head(),
1209            last: None,
1210            attempt_ids: BTreeSet::new(),
1211            count: 0,
1212        }
1213    }
1214
1215    /// Returns the delivery identity being verified.
1216    #[must_use]
1217    pub const fn delivery(&self) -> &OutboxDeliveryHead {
1218        &self.delivery
1219    }
1220
1221    /// Returns the number of verified physical attempts.
1222    #[must_use]
1223    pub const fn count(&self) -> usize {
1224        self.count
1225    }
1226
1227    /// Returns the last verified full attempt, if present.
1228    #[must_use]
1229    pub const fn last(&self) -> Option<&OutboxAttempt> {
1230        self.last.as_ref()
1231    }
1232
1233    /// Verifies and advances to the next physical attempt.
1234    ///
1235    /// # Errors
1236    ///
1237    /// Returns [`OutboxAttemptHistoryError`] for substitution, non-contiguous
1238    /// fencing, premature takeover/retry, terminal successors, or overflow.
1239    pub fn verify_next(
1240        &mut self,
1241        attempt: &OutboxAttempt,
1242    ) -> Result<(), OutboxAttemptHistoryError> {
1243        if self.count == MAX_OUTBOX_ATTEMPTS {
1244            return Err(OutboxAttemptHistoryError::AttemptLimitExceeded);
1245        }
1246        if attempt.start.delivery != self.delivery {
1247            return Err(OutboxAttemptHistoryError::DeliveryMismatch);
1248        }
1249        let attempt_id = attempt.start.fence.attempt_id;
1250        if self.attempt_ids.contains(&attempt_id) {
1251            return Err(OutboxAttemptHistoryError::AttemptIdReused { attempt_id });
1252        }
1253
1254        if let Some(previous) = self.last.as_ref() {
1255            validate_attempt_successor(previous, attempt)?;
1256        } else if attempt.start.fence.epoch != FencingEpoch::FIRST {
1257            return Err(OutboxAttemptHistoryError::FirstEpochInvalid {
1258                actual: attempt.start.fence.epoch,
1259            });
1260        }
1261
1262        self.attempt_ids.insert(attempt_id);
1263        self.last = Some(attempt.clone());
1264        self.count += 1;
1265        Ok(())
1266    }
1267
1268    /// Projects durable delivery state at one database-clock observation.
1269    ///
1270    /// # Errors
1271    ///
1272    /// Returns [`OutboxAttemptHistoryError::ObservationClockRegression`] when
1273    /// the observation precedes already-verified durable evidence.
1274    pub fn status_at(
1275        &self,
1276        observed_at: Timestamp,
1277    ) -> Result<OutboxDeliveryStatus, OutboxAttemptHistoryError> {
1278        let latest_at = self.last.as_ref().map_or_else(
1279            || self.delivery.origin.recorded_at(),
1280            |attempt| {
1281                attempt.completion.as_ref().map_or_else(
1282                    || attempt.start.started_at,
1283                    |completion| completion.completed_at,
1284                )
1285            },
1286        );
1287        if observed_at < latest_at {
1288            return Err(OutboxAttemptHistoryError::ObservationClockRegression {
1289                latest_at,
1290                observed_at,
1291            });
1292        }
1293
1294        if let Some(completion) = self
1295            .last
1296            .as_ref()
1297            .and_then(|value| value.completion.as_ref())
1298        {
1299            match completion.outcome() {
1300                OutboxAttemptOutcome::Acknowledged { .. } => {
1301                    return Ok(OutboxDeliveryStatus::Acknowledged);
1302                }
1303                OutboxAttemptOutcome::Failed { failure }
1304                    if matches!(failure.retry_advice(), RetryAdvice::Never) =>
1305                {
1306                    return Ok(OutboxDeliveryStatus::DeadLetter);
1307                }
1308                OutboxAttemptOutcome::Failed { .. } if self.count == MAX_OUTBOX_ATTEMPTS => {
1309                    return Ok(OutboxDeliveryStatus::DeadLetter);
1310                }
1311                OutboxAttemptOutcome::Failed { .. } => {}
1312            }
1313        }
1314
1315        if let Some(last) = self.last.as_ref() {
1316            if last.completion.is_none()
1317                && self.count == MAX_OUTBOX_ATTEMPTS
1318                && observed_at >= last.start.expires_at
1319            {
1320                return Ok(if last.start.expires_at < self.delivery.expires_at {
1321                    OutboxDeliveryStatus::DeadLetter
1322                } else {
1323                    OutboxDeliveryStatus::Expired
1324                });
1325            }
1326        }
1327
1328        if observed_at >= self.delivery.expires_at {
1329            return Ok(OutboxDeliveryStatus::Expired);
1330        }
1331
1332        let Some(last) = self.last.as_ref() else {
1333            return Ok(OutboxDeliveryStatus::Pending);
1334        };
1335        let Some(completion) = last.completion.as_ref() else {
1336            if observed_at < last.start.expires_at {
1337                return Ok(OutboxDeliveryStatus::Delivering);
1338            }
1339            return Ok(OutboxDeliveryStatus::Pending);
1340        };
1341
1342        let OutboxAttemptOutcome::Failed { failure } = completion.outcome() else {
1343            return Ok(OutboxDeliveryStatus::Acknowledged);
1344        };
1345        let RetryAdvice::SafeAfter { delay } = failure.retry_advice() else {
1346            return Ok(OutboxDeliveryStatus::DeadLetter);
1347        };
1348        let eligible_at = retry_eligible_at(completion.completed_at, delay.as_i64())
1349            .map_err(|_| OutboxAttemptHistoryError::RetryDelayOutOfRange)?;
1350        Ok(if observed_at < eligible_at {
1351            OutboxDeliveryStatus::RetryScheduled
1352        } else {
1353            OutboxDeliveryStatus::Pending
1354        })
1355    }
1356}
1357
1358/// Invalid delivery scope, atomic origin binding, deadline, or checksum.
1359#[derive(Clone, Debug, Eq, Error, PartialEq)]
1360#[non_exhaustive]
1361pub enum OutboxDeliveryError {
1362    /// Destination reference crossed the enqueue tenant boundary.
1363    #[error("outbox destination crosses the delivery tenant boundary")]
1364    DestinationTenantMismatch,
1365    /// Origin journal crossed the enqueue tenant boundary.
1366    #[error("outbox origin crosses the delivery tenant boundary")]
1367    OriginTenantMismatch,
1368    /// Origin journal named another run.
1369    #[error("outbox origin does not belong to the delivery run")]
1370    OriginRunMismatch,
1371    /// The committed journal event differed from the requested origin event.
1372    #[error("outbox origin event does not match the enqueue intent")]
1373    OriginEventMismatch,
1374    /// The delivery deadline was not strictly after the origin commit time.
1375    #[error("outbox delivery deadline must be after its origin")]
1376    DeadlineNotAfterOrigin,
1377    /// Persisted enqueue checksum did not match its fields.
1378    #[error("outbox intent digest does not match its fields")]
1379    IntentDigestMismatch,
1380    /// Persisted committed-delivery checksum did not match its fields.
1381    #[error("outbox delivery digest does not match its fields")]
1382    DeliveryDigestMismatch,
1383    /// Canonical integrity material could not be serialized.
1384    #[error("outbox delivery integrity calculation failed: {source}")]
1385    Integrity {
1386        /// Exact integrity failure.
1387        #[source]
1388        source: OutboxDeliveryIntegrityError,
1389    },
1390}
1391
1392impl From<OutboxDeliveryIntegrityError> for OutboxDeliveryError {
1393    fn from(source: OutboxDeliveryIntegrityError) -> Self {
1394        Self::Integrity { source }
1395    }
1396}
1397
1398/// Failure to canonicalize delivery integrity material.
1399#[derive(Clone, Debug, Eq, Error, PartialEq)]
1400#[non_exhaustive]
1401pub enum OutboxDeliveryIntegrityError {
1402    /// A closed typed checksum preimage could not be canonicalized.
1403    #[error("outbox delivery checksum preimage serialization failed")]
1404    CanonicalSerialization,
1405}
1406
1407/// Invalid attempt fence, timing, completion, or checksum.
1408#[derive(Clone, Debug, Eq, Error, PartialEq)]
1409#[non_exhaustive]
1410pub enum OutboxAttemptError {
1411    /// Attempt fence crossed the delivery tenant boundary.
1412    #[error("outbox attempt fence crosses the delivery tenant boundary")]
1413    FenceTenantMismatch,
1414    /// Attempt fence named another run.
1415    #[error("outbox attempt fence does not belong to the delivery run")]
1416    FenceRunMismatch,
1417    /// Attempt fence named another delivery.
1418    #[error("outbox attempt fence does not belong to the delivery")]
1419    FenceDeliveryMismatch,
1420    /// Attempt start preceded the atomic origin commit.
1421    #[error("outbox attempt starts before its delivery origin")]
1422    StartBeforeOrigin,
1423    /// Attempt start was at or after the delivery deadline.
1424    #[error("outbox attempt starts at or after the delivery deadline")]
1425    StartOutsideDeliveryWindow,
1426    /// Attempt expiry was not strictly after start.
1427    #[error("outbox attempt expiry must be after its start")]
1428    ExpiryNotAfterStart,
1429    /// Attempt expiry exceeded the delivery deadline.
1430    #[error("outbox attempt expiry exceeds the delivery deadline")]
1431    ExpiryAfterDeliveryDeadline,
1432    /// Attempt lease exceeded the hard duration bound.
1433    #[error("outbox attempt lease is {actual_millis}ms; maximum is {maximum_millis}ms")]
1434    LeaseTooLong {
1435        /// Maximum accepted duration.
1436        maximum_millis: i64,
1437        /// Observed ceiling duration in milliseconds.
1438        actual_millis: i64,
1439    },
1440    /// Completion preceded its start.
1441    #[error("outbox attempt completion precedes its start")]
1442    CompletionBeforeStart,
1443    /// Completion occurred at or after the exclusive attempt expiry.
1444    #[error("outbox attempt completion is outside its live fence")]
1445    CompletionOutsideFence,
1446    /// Duplicate-tolerant delivery cannot require ambiguity reconciliation.
1447    #[error("outbox failure cannot require external reconciliation")]
1448    ReconciliationUnsupported,
1449    /// Safe retry delay could not be represented as a canonical timestamp.
1450    #[error("outbox retry delay exceeds the supported timestamp range")]
1451    RetryDelayOutOfRange,
1452    /// Completion joined to another physical start.
1453    #[error("outbox attempt completion does not belong to its start")]
1454    CompletionStartMismatch,
1455    /// Persisted attempt-start checksum did not match its fields.
1456    #[error("outbox attempt start digest does not match its fields")]
1457    StartDigestMismatch,
1458    /// Persisted attempt-completion checksum did not match its fields.
1459    #[error("outbox attempt completion digest does not match its fields")]
1460    CompletionDigestMismatch,
1461    /// Canonical integrity material could not be serialized.
1462    #[error("outbox attempt integrity calculation failed: {source}")]
1463    Integrity {
1464        /// Exact integrity failure.
1465        #[source]
1466        source: OutboxAttemptIntegrityError,
1467    },
1468}
1469
1470impl From<OutboxAttemptIntegrityError> for OutboxAttemptError {
1471    fn from(source: OutboxAttemptIntegrityError) -> Self {
1472        Self::Integrity { source }
1473    }
1474}
1475
1476/// Failure to canonicalize attempt integrity material.
1477#[derive(Clone, Debug, Eq, Error, PartialEq)]
1478#[non_exhaustive]
1479pub enum OutboxAttemptIntegrityError {
1480    /// A closed typed checksum preimage could not be canonicalized.
1481    #[error("outbox attempt checksum preimage serialization failed")]
1482    CanonicalSerialization,
1483}
1484
1485/// Invalid physical-attempt history for one logical delivery.
1486#[derive(Clone, Debug, Eq, Error, PartialEq)]
1487#[non_exhaustive]
1488pub enum OutboxAttemptHistoryError {
1489    /// More than the bounded number of attempts was supplied.
1490    #[error("outbox delivery exceeded its physical attempt limit")]
1491    AttemptLimitExceeded,
1492    /// An attempt belonged to another logical delivery.
1493    #[error("outbox attempt history changed its logical delivery")]
1494    DeliveryMismatch,
1495    /// A physical attempt identity was used twice.
1496    #[error("outbox attempt history reused physical attempt {attempt_id}")]
1497    AttemptIdReused {
1498        /// Reused physical identity.
1499        attempt_id: AttemptId,
1500    },
1501    /// First attempt did not use fencing epoch one.
1502    #[error("first outbox attempt used epoch {actual}; expected one")]
1503    FirstEpochInvalid {
1504        /// Rejected first epoch.
1505        actual: FencingEpoch,
1506    },
1507    /// A successor did not use the exact next fencing epoch.
1508    #[error("outbox attempt fencing epoch is not the exact successor")]
1509    EpochNotSuccessor,
1510    /// A successor start clock regressed behind prior durable evidence.
1511    #[error("outbox attempt history durable clock regressed")]
1512    ClockRegression,
1513    /// An unfinished attempt was replaced before its fixed lease expired.
1514    #[error("unfinished outbox attempt cannot be replaced before lease expiry")]
1515    LiveAttemptSuperseded,
1516    /// An acknowledged delivery was attempted again.
1517    #[error("acknowledged outbox delivery cannot start another attempt")]
1518    PreviousAttemptAcknowledged,
1519    /// Failure evidence did not authorize another automatic attempt.
1520    #[error("outbox failure recovery advice does not authorize automatic retry")]
1521    RetryNotAuthorized,
1522    /// A successor preceded the explicit safe-after delay.
1523    #[error("outbox retry started before its explicit safe-after delay elapsed")]
1524    RetryDelayNotElapsed {
1525        /// Earliest allowed successor start.
1526        eligible_at: Timestamp,
1527        /// Rejected successor start.
1528        started_at: Timestamp,
1529    },
1530    /// Safe-after timestamp could not be represented.
1531    #[error("outbox retry delay exceeds the supported timestamp range")]
1532    RetryDelayOutOfRange,
1533    /// A status observation preceded already verified durable evidence.
1534    #[error("outbox status observation clock regressed")]
1535    ObservationClockRegression {
1536        /// Latest durable timestamp in the verified history.
1537        latest_at: Timestamp,
1538        /// Rejected observation.
1539        observed_at: Timestamp,
1540    },
1541}
1542
1543#[derive(Serialize)]
1544struct OutboxIntentDigestWire<'a> {
1545    tenant_id: &'a TenantId,
1546    run_id: RunId,
1547    delivery_id: DeliveryId,
1548    origin_event_id: EventId,
1549    destination: &'a OutboxDestinationRef,
1550    payload_digest: Digest,
1551    expires_at: Timestamp,
1552}
1553
1554#[derive(Serialize)]
1555struct OutboxDeliveryDigestWire<'a> {
1556    tenant_id: &'a TenantId,
1557    run_id: RunId,
1558    delivery_id: DeliveryId,
1559    intent_digest: Digest,
1560    origin: &'a JournalHead,
1561    expires_at: Timestamp,
1562}
1563
1564#[derive(Serialize)]
1565struct OutboxAttemptStartDigestWire<'a> {
1566    delivery: &'a OutboxDeliveryHead,
1567    fence: &'a DeliveryFence,
1568    started_at: Timestamp,
1569    expires_at: Timestamp,
1570}
1571
1572#[derive(Serialize)]
1573struct OutboxAttemptCompletionDigestWire<'a> {
1574    start: &'a OutboxAttemptStartHead,
1575    outcome: &'a OutboxAttemptOutcome,
1576    completed_at: Timestamp,
1577}
1578
1579fn compute_intent_digest(
1580    value: &OutboxIntentDigestWire<'_>,
1581) -> Result<Digest, OutboxDeliveryIntegrityError> {
1582    delivery_digest(INTENT_DIGEST_DOMAIN, value)
1583}
1584
1585fn compute_delivery_digest(
1586    value: &OutboxDeliveryDigestWire<'_>,
1587) -> Result<Digest, OutboxDeliveryIntegrityError> {
1588    delivery_digest(DELIVERY_DIGEST_DOMAIN, value)
1589}
1590
1591fn delivery_digest<T: Serialize>(
1592    domain: &[u8],
1593    value: &T,
1594) -> Result<Digest, OutboxDeliveryIntegrityError> {
1595    let canonical = serde_json_canonicalizer::to_vec(value)
1596        .map_err(|_| OutboxDeliveryIntegrityError::CanonicalSerialization)?;
1597    let mut preimage = Vec::with_capacity(domain.len() + canonical.len());
1598    preimage.extend_from_slice(domain);
1599    preimage.extend_from_slice(&canonical);
1600    Ok(Digest::sha256(preimage))
1601}
1602
1603fn compute_attempt_start_digest(
1604    value: &OutboxAttemptStartDigestWire<'_>,
1605) -> Result<Digest, OutboxAttemptIntegrityError> {
1606    attempt_digest(ATTEMPT_START_DIGEST_DOMAIN, value)
1607}
1608
1609fn compute_attempt_completion_digest(
1610    value: &OutboxAttemptCompletionDigestWire<'_>,
1611) -> Result<Digest, OutboxAttemptIntegrityError> {
1612    attempt_digest(ATTEMPT_COMPLETION_DIGEST_DOMAIN, value)
1613}
1614
1615fn attempt_digest<T: Serialize>(
1616    domain: &[u8],
1617    value: &T,
1618) -> Result<Digest, OutboxAttemptIntegrityError> {
1619    let canonical = serde_json_canonicalizer::to_vec(value)
1620        .map_err(|_| OutboxAttemptIntegrityError::CanonicalSerialization)?;
1621    let mut preimage = Vec::with_capacity(domain.len() + canonical.len());
1622    preimage.extend_from_slice(domain);
1623    preimage.extend_from_slice(&canonical);
1624    Ok(Digest::sha256(preimage))
1625}
1626
1627fn validate_delivery_shape(
1628    intent: &OutboxDeliveryIntent,
1629    origin: &JournalHead,
1630) -> Result<(), OutboxDeliveryError> {
1631    validate_delivery_head_scope(&intent.tenant_id, intent.run_id, origin, intent.expires_at)?;
1632    if origin.event_id() != intent.origin_event_id {
1633        return Err(OutboxDeliveryError::OriginEventMismatch);
1634    }
1635    Ok(())
1636}
1637
1638fn validate_delivery_head_scope(
1639    tenant_id: &TenantId,
1640    run_id: RunId,
1641    origin: &JournalHead,
1642    expires_at: Timestamp,
1643) -> Result<(), OutboxDeliveryError> {
1644    if origin.tenant_id() != tenant_id {
1645        return Err(OutboxDeliveryError::OriginTenantMismatch);
1646    }
1647    if origin.run_id() != run_id {
1648        return Err(OutboxDeliveryError::OriginRunMismatch);
1649    }
1650    if expires_at <= origin.recorded_at() {
1651        return Err(OutboxDeliveryError::DeadlineNotAfterOrigin);
1652    }
1653    Ok(())
1654}
1655
1656fn validate_attempt_start(
1657    delivery: &OutboxDeliveryHead,
1658    fence: &DeliveryFence,
1659    started_at: Timestamp,
1660    expires_at: Timestamp,
1661) -> Result<(), OutboxAttemptError> {
1662    if fence.tenant_id != delivery.tenant_id {
1663        return Err(OutboxAttemptError::FenceTenantMismatch);
1664    }
1665    if fence.run_id != delivery.run_id {
1666        return Err(OutboxAttemptError::FenceRunMismatch);
1667    }
1668    if fence.delivery_id != delivery.delivery_id {
1669        return Err(OutboxAttemptError::FenceDeliveryMismatch);
1670    }
1671    if started_at < delivery.origin.recorded_at() {
1672        return Err(OutboxAttemptError::StartBeforeOrigin);
1673    }
1674    if started_at >= delivery.expires_at {
1675        return Err(OutboxAttemptError::StartOutsideDeliveryWindow);
1676    }
1677    if expires_at <= started_at {
1678        return Err(OutboxAttemptError::ExpiryNotAfterStart);
1679    }
1680    if expires_at > delivery.expires_at {
1681        return Err(OutboxAttemptError::ExpiryAfterDeliveryDeadline);
1682    }
1683    let duration_micros =
1684        i128::from(expires_at.unix_micros()) - i128::from(started_at.unix_micros());
1685    let maximum_micros = i128::from(MAX_OUTBOX_ATTEMPT_LEASE_MILLIS) * 1_000;
1686    if duration_micros > maximum_micros {
1687        let actual_millis = i64::try_from((duration_micros + 999) / 1_000).unwrap_or(i64::MAX);
1688        return Err(OutboxAttemptError::LeaseTooLong {
1689            maximum_millis: MAX_OUTBOX_ATTEMPT_LEASE_MILLIS,
1690            actual_millis,
1691        });
1692    }
1693    Ok(())
1694}
1695
1696fn validate_attempt_completion(
1697    start: &OutboxAttemptStartHead,
1698    outcome: &OutboxAttemptOutcome,
1699    completed_at: Timestamp,
1700) -> Result<(), OutboxAttemptError> {
1701    if completed_at < start.started_at {
1702        return Err(OutboxAttemptError::CompletionBeforeStart);
1703    }
1704    if completed_at >= start.expires_at {
1705        return Err(OutboxAttemptError::CompletionOutsideFence);
1706    }
1707    if let OutboxAttemptOutcome::Failed { failure } = outcome {
1708        match failure.retry_advice() {
1709            RetryAdvice::ReconcileFirst => {
1710                return Err(OutboxAttemptError::ReconciliationUnsupported);
1711            }
1712            RetryAdvice::SafeAfter { delay } => {
1713                retry_eligible_at(completed_at, delay.as_i64())?;
1714            }
1715            RetryAdvice::Never => {}
1716        }
1717    }
1718    Ok(())
1719}
1720
1721fn validate_attempt_successor(
1722    previous: &OutboxAttempt,
1723    next: &OutboxAttempt,
1724) -> Result<(), OutboxAttemptHistoryError> {
1725    if next.start.fence.epoch
1726        != previous
1727            .start
1728            .fence
1729            .epoch
1730            .checked_next()
1731            .ok_or(OutboxAttemptHistoryError::AttemptLimitExceeded)?
1732    {
1733        return Err(OutboxAttemptHistoryError::EpochNotSuccessor);
1734    }
1735
1736    let anchor = previous
1737        .completion
1738        .as_ref()
1739        .map_or(previous.start.expires_at, |completion| {
1740            completion.completed_at
1741        });
1742    if next.start.started_at < anchor {
1743        return Err(if previous.completion.is_none() {
1744            OutboxAttemptHistoryError::LiveAttemptSuperseded
1745        } else {
1746            OutboxAttemptHistoryError::ClockRegression
1747        });
1748    }
1749
1750    let Some(completion) = previous.completion.as_ref() else {
1751        return Ok(());
1752    };
1753    match completion.outcome() {
1754        OutboxAttemptOutcome::Acknowledged { .. } => {
1755            Err(OutboxAttemptHistoryError::PreviousAttemptAcknowledged)
1756        }
1757        OutboxAttemptOutcome::Failed { failure } => match failure.retry_advice() {
1758            RetryAdvice::SafeAfter { delay } => {
1759                let eligible_at = retry_eligible_at(completion.completed_at, delay.as_i64())
1760                    .map_err(|_| OutboxAttemptHistoryError::RetryDelayOutOfRange)?;
1761                if next.start.started_at < eligible_at {
1762                    Err(OutboxAttemptHistoryError::RetryDelayNotElapsed {
1763                        eligible_at,
1764                        started_at: next.start.started_at,
1765                    })
1766                } else {
1767                    Ok(())
1768                }
1769            }
1770            RetryAdvice::Never | RetryAdvice::ReconcileFirst => {
1771                Err(OutboxAttemptHistoryError::RetryNotAuthorized)
1772            }
1773        },
1774    }
1775}
1776
1777fn retry_eligible_at(
1778    completed_at: Timestamp,
1779    delay_millis: i64,
1780) -> Result<Timestamp, OutboxAttemptError> {
1781    let eligible_micros = i128::from(completed_at.unix_micros()) + i128::from(delay_millis) * 1_000;
1782    if eligible_micros > i128::from(Timestamp::MAX.unix_micros()) {
1783        return Err(OutboxAttemptError::RetryDelayOutOfRange);
1784    }
1785    Timestamp::from_unix_micros(
1786        i64::try_from(eligible_micros).map_err(|_| OutboxAttemptError::RetryDelayOutOfRange)?,
1787    )
1788    .map_err(|_| OutboxAttemptError::RetryDelayOutOfRange)
1789}
1790
1791#[cfg(test)]
1792mod tests {
1793    use super::*;
1794    use crate::{
1795        BoundedJson, DurationMillis, FailureCategory, FailureCode, FailureId, FailureMessage,
1796        FailureOrigin, JournalEventKind, JournalSequence, SchemaId, SchemaReference, Version,
1797    };
1798    use proptest::prelude::*;
1799    use serde_json::{Value, from_value, json, to_value};
1800
1801    const BASE_MICROS: i64 = 1_893_456_000_000_000;
1802
1803    fn id<T: std::str::FromStr>(suffix: u8) -> T
1804    where
1805        T::Err: fmt::Debug,
1806    {
1807        format!("01912345-6789-7abc-8def-0123456789{suffix:02x}")
1808            .parse()
1809            .unwrap()
1810    }
1811
1812    fn timestamp(offset_micros: i64) -> Timestamp {
1813        Timestamp::from_unix_micros(BASE_MICROS + offset_micros).unwrap()
1814    }
1815
1816    fn payload() -> JournalPayload {
1817        JournalPayload::new(
1818            SchemaReference::new(
1819                "https://stateknot.github.io/schema/outbox-test/1.0.0"
1820                    .parse::<SchemaId>()
1821                    .unwrap(),
1822                Version::new(1, 0, 0),
1823                Digest::sha256(b"outbox-test-schema"),
1824            ),
1825            JournalEventKind::new("a2a-task-update").unwrap(),
1826            BoundedJson::try_from_value(json!({
1827                "task_id": "task-42",
1828                "state": "completed"
1829            }))
1830            .unwrap(),
1831        )
1832        .unwrap()
1833    }
1834
1835    fn delivery_with_deadline(deadline_offset_micros: i64) -> OutboxDelivery {
1836        let tenant_id = TenantId::new("tenant-a").unwrap();
1837        let run_id = id::<RunId>(0x10);
1838        let origin_event_id = id::<EventId>(0x11);
1839        let destination = OutboxDestinationRef::new(
1840            tenant_id.clone(),
1841            id::<DestinationId>(0x12),
1842            Digest::sha256(b"destination-snapshot"),
1843        );
1844        let intent = OutboxDeliveryIntent::new(
1845            tenant_id.clone(),
1846            run_id,
1847            id::<DeliveryId>(0x13),
1848            origin_event_id,
1849            destination,
1850            payload(),
1851            timestamp(deadline_offset_micros),
1852        )
1853        .unwrap();
1854        let origin = JournalHead::new(
1855            tenant_id,
1856            run_id,
1857            JournalSequence::FIRST,
1858            origin_event_id,
1859            timestamp(0),
1860            Digest::sha256(b"origin-event"),
1861        );
1862        OutboxDelivery::commit(intent, origin).unwrap()
1863    }
1864
1865    fn delivery() -> OutboxDelivery {
1866        delivery_with_deadline(86_400_000_000)
1867    }
1868
1869    fn start(
1870        delivery: &OutboxDelivery,
1871        suffix: u8,
1872        epoch: u64,
1873        started_offset_micros: i64,
1874        lease_micros: i64,
1875    ) -> OutboxAttemptStart {
1876        OutboxAttemptStart::new(
1877            delivery,
1878            DeliveryFence::new(
1879                delivery.intent().tenant_id().clone(),
1880                delivery.intent().run_id(),
1881                delivery.intent().delivery_id(),
1882                id::<AttemptId>(suffix),
1883                FencingEpoch::new(epoch).unwrap(),
1884            ),
1885            timestamp(started_offset_micros),
1886            timestamp(started_offset_micros + lease_micros),
1887        )
1888        .unwrap()
1889    }
1890
1891    fn failure(suffix: u8, retry_advice: RetryAdvice) -> Failure {
1892        let category = if matches!(retry_advice, RetryAdvice::ReconcileFirst) {
1893            FailureCategory::AmbiguousExternalOutcome
1894        } else {
1895            FailureCategory::Internal
1896        };
1897        Failure::new(
1898            id::<FailureId>(suffix),
1899            category,
1900            FailureCode::new("outbox.delivery_failed").unwrap(),
1901            FailureOrigin::new("stateknot.outbox.test").unwrap(),
1902            FailureMessage::new("Delivery failed safely").unwrap(),
1903            retry_advice,
1904        )
1905        .unwrap()
1906    }
1907
1908    #[test]
1909    fn delivery_binds_origin_destination_payload_deadline_and_every_digest() {
1910        let delivery = delivery();
1911        let encoded = to_value(&delivery).unwrap();
1912        assert_eq!(
1913            from_value::<OutboxDelivery>(encoded.clone()).unwrap(),
1914            delivery
1915        );
1916        assert_eq!(
1917            from_value::<OutboxDeliveryHead>(to_value(delivery.head()).unwrap()).unwrap(),
1918            delivery.head()
1919        );
1920
1921        for path in ["delivery_id", "expires_at"] {
1922            let mut changed = to_value(delivery.head()).unwrap();
1923            changed[path] = if path == "delivery_id" {
1924                json!(id::<DeliveryId>(0x14))
1925            } else {
1926                json!(timestamp(86_399_000_000))
1927            };
1928            assert!(from_value::<OutboxDeliveryHead>(changed).is_err());
1929        }
1930
1931        let mut changed_payload = encoded;
1932        changed_payload["intent"]["payload"]["data"]["state"] = json!("failed");
1933        assert!(from_value::<OutboxDelivery>(changed_payload).is_err());
1934    }
1935
1936    #[test]
1937    fn delivery_rejects_crossed_scope_substituted_origin_and_closed_deadline() {
1938        let delivery = delivery();
1939        let intent = delivery.intent().clone();
1940        let origin = delivery.origin().clone();
1941
1942        let crossed = JournalHead::new(
1943            TenantId::new("tenant-b").unwrap(),
1944            origin.run_id(),
1945            origin.sequence(),
1946            origin.event_id(),
1947            origin.recorded_at(),
1948            origin.digest(),
1949        );
1950        assert_eq!(
1951            OutboxDelivery::commit(intent.clone(), crossed),
1952            Err(OutboxDeliveryError::OriginTenantMismatch)
1953        );
1954
1955        let substituted = JournalHead::new(
1956            origin.tenant_id().clone(),
1957            origin.run_id(),
1958            origin.sequence(),
1959            id::<EventId>(0x15),
1960            origin.recorded_at(),
1961            origin.digest(),
1962        );
1963        assert_eq!(
1964            OutboxDelivery::commit(intent, substituted),
1965            Err(OutboxDeliveryError::OriginEventMismatch)
1966        );
1967
1968        let deadline = delivery_with_deadline(1);
1969        let mut changed = to_value(deadline).unwrap();
1970        changed["intent"]["expires_at"] = json!(timestamp(0));
1971        assert!(from_value::<OutboxDelivery>(changed).is_err());
1972    }
1973
1974    #[test]
1975    fn attempt_lease_and_completion_enforce_exclusive_time_boundaries() {
1976        let delivery = delivery_with_deadline(600_000_000);
1977        let live = start(&delivery, 0x20, 1, 1_000_000, 10_000_000);
1978        assert!(
1979            OutboxAttemptCompletion::acknowledge(
1980                &live,
1981                Some(Digest::sha256(b"ack")),
1982                timestamp(10_999_999),
1983            )
1984            .is_ok()
1985        );
1986        assert!(matches!(
1987            OutboxAttemptCompletion::acknowledge(&live, None, timestamp(11_000_000)),
1988            Err(OutboxAttemptError::CompletionOutsideFence)
1989        ));
1990
1991        let too_long = OutboxAttemptStart::new(
1992            &delivery,
1993            DeliveryFence::new(
1994                delivery.intent().tenant_id().clone(),
1995                delivery.intent().run_id(),
1996                delivery.intent().delivery_id(),
1997                id::<AttemptId>(0x21),
1998                FencingEpoch::new(2).unwrap(),
1999            ),
2000            timestamp(1_000_000),
2001            timestamp(1_000_000 + (MAX_OUTBOX_ATTEMPT_LEASE_MILLIS + 1) * 1_000),
2002        );
2003        assert!(matches!(
2004            too_long,
2005            Err(OutboxAttemptError::LeaseTooLong { .. })
2006        ));
2007    }
2008
2009    #[test]
2010    fn outbox_rejects_reconcile_first_because_duplicates_are_the_contract() {
2011        let delivery = delivery();
2012        let start = start(&delivery, 0x22, 1, 1_000_000, 10_000_000);
2013        assert!(matches!(
2014            OutboxAttemptCompletion::fail(
2015                &start,
2016                failure(0x23, RetryAdvice::ReconcileFirst),
2017                timestamp(2_000_000),
2018            ),
2019            Err(OutboxAttemptError::ReconciliationUnsupported)
2020        ));
2021    }
2022
2023    #[test]
2024    fn lost_ack_recovery_waits_for_fixed_expiry_and_advances_exact_epoch() {
2025        let delivery = delivery();
2026        let first = OutboxAttempt::delivering(start(&delivery, 0x30, 1, 1_000_000, 5_000_000));
2027        let early = OutboxAttempt::delivering(start(&delivery, 0x31, 2, 5_999_999, 5_000_000));
2028        let recovered = OutboxAttempt::delivering(start(&delivery, 0x31, 2, 6_000_000, 5_000_000));
2029
2030        let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2031        verifier.verify_next(&first).unwrap();
2032        assert_eq!(
2033            verifier.verify_next(&early),
2034            Err(OutboxAttemptHistoryError::LiveAttemptSuperseded)
2035        );
2036        assert_eq!(verifier.count(), 1);
2037        verifier.verify_next(&recovered).unwrap();
2038        assert_eq!(verifier.count(), 2);
2039    }
2040
2041    #[test]
2042    fn safe_after_retry_and_status_projection_use_durable_database_time() {
2043        let delivery = delivery();
2044        let first_start = start(&delivery, 0x40, 1, 1_000_000, 10_000_000);
2045        let completion = OutboxAttemptCompletion::fail(
2046            &first_start,
2047            failure(
2048                0x41,
2049                RetryAdvice::SafeAfter {
2050                    delay: DurationMillis::new(2_500).unwrap(),
2051                },
2052            ),
2053            timestamp(2_000_000),
2054        )
2055        .unwrap();
2056        let first = OutboxAttempt::restore(first_start, Some(completion)).unwrap();
2057
2058        let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2059        verifier.verify_next(&first).unwrap();
2060        assert_eq!(
2061            verifier.status_at(timestamp(4_499_999)).unwrap(),
2062            OutboxDeliveryStatus::RetryScheduled
2063        );
2064        assert_eq!(
2065            verifier.status_at(timestamp(4_500_000)).unwrap(),
2066            OutboxDeliveryStatus::Pending
2067        );
2068
2069        let early = OutboxAttempt::delivering(start(&delivery, 0x42, 2, 4_499_999, 1_000_000));
2070        assert!(matches!(
2071            verifier.verify_next(&early),
2072            Err(OutboxAttemptHistoryError::RetryDelayNotElapsed { .. })
2073        ));
2074        let retry = OutboxAttempt::delivering(start(&delivery, 0x42, 2, 4_500_000, 1_000_000));
2075        verifier.verify_next(&retry).unwrap();
2076    }
2077
2078    #[test]
2079    fn acknowledgement_and_never_failures_are_absorbing_terminal_states() {
2080        let delivery = delivery();
2081        let acknowledged_start = start(&delivery, 0x50, 1, 1_000_000, 10_000_000);
2082        let acknowledged = OutboxAttempt::restore(
2083            acknowledged_start.clone(),
2084            Some(
2085                OutboxAttemptCompletion::acknowledge(
2086                    &acknowledged_start,
2087                    None,
2088                    timestamp(2_000_000),
2089                )
2090                .unwrap(),
2091            ),
2092        )
2093        .unwrap();
2094        let successor = OutboxAttempt::delivering(start(&delivery, 0x51, 2, 3_000_000, 1_000_000));
2095        let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2096        verifier.verify_next(&acknowledged).unwrap();
2097        assert_eq!(
2098            verifier.status_at(timestamp(3_000_000)).unwrap(),
2099            OutboxDeliveryStatus::Acknowledged
2100        );
2101        assert_eq!(
2102            verifier.verify_next(&successor),
2103            Err(OutboxAttemptHistoryError::PreviousAttemptAcknowledged)
2104        );
2105
2106        let failed_start = start(&delivery, 0x52, 1, 1_000_000, 10_000_000);
2107        let failed = OutboxAttempt::restore(
2108            failed_start.clone(),
2109            Some(
2110                OutboxAttemptCompletion::fail(
2111                    &failed_start,
2112                    failure(0x53, RetryAdvice::Never),
2113                    timestamp(2_000_000),
2114                )
2115                .unwrap(),
2116            ),
2117        )
2118        .unwrap();
2119        let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2120        verifier.verify_next(&failed).unwrap();
2121        assert_eq!(
2122            verifier.status_at(timestamp(3_000_000)).unwrap(),
2123            OutboxDeliveryStatus::DeadLetter
2124        );
2125        assert_eq!(
2126            verifier.verify_next(&successor),
2127            Err(OutboxAttemptHistoryError::RetryNotAuthorized)
2128        );
2129    }
2130
2131    #[test]
2132    fn attempt_history_is_hard_bounded_and_rejections_do_not_advance_state() {
2133        let delivery = delivery();
2134        let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2135        for index in 0..MAX_OUTBOX_ATTEMPTS {
2136            let started_offset = 1_000_000 + i64::try_from(index).unwrap() * 2_000;
2137            let attempt_start = start(
2138                &delivery,
2139                u8::try_from(0x80 + index).unwrap(),
2140                u64::try_from(index + 1).unwrap(),
2141                started_offset,
2142                1_000,
2143            );
2144            let completion = OutboxAttemptCompletion::fail(
2145                &attempt_start,
2146                failure(
2147                    u8::try_from(0x40 + index).unwrap(),
2148                    RetryAdvice::SafeAfter {
2149                        delay: DurationMillis::ZERO,
2150                    },
2151                ),
2152                timestamp(started_offset + 500),
2153            )
2154            .unwrap();
2155            verifier
2156                .verify_next(&OutboxAttempt::restore(attempt_start, Some(completion)).unwrap())
2157                .unwrap();
2158        }
2159        assert_eq!(verifier.count(), MAX_OUTBOX_ATTEMPTS);
2160        assert_eq!(
2161            verifier.status_at(timestamp(2_000_000)).unwrap(),
2162            OutboxDeliveryStatus::DeadLetter
2163        );
2164        assert_eq!(
2165            verifier.status_at(timestamp(90_000_000_000)).unwrap(),
2166            OutboxDeliveryStatus::DeadLetter,
2167            "attempt exhaustion is an absorbing terminal state"
2168        );
2169        let extra = OutboxAttempt::delivering(start(
2170            &delivery,
2171            0x7f,
2172            u64::try_from(MAX_OUTBOX_ATTEMPTS + 1).unwrap(),
2173            2_000_000,
2174            1_000,
2175        ));
2176        assert_eq!(
2177            verifier.verify_next(&extra),
2178            Err(OutboxAttemptHistoryError::AttemptLimitExceeded)
2179        );
2180        assert_eq!(verifier.count(), MAX_OUTBOX_ATTEMPTS);
2181    }
2182
2183    #[test]
2184    fn all_integrity_bearing_wires_are_closed_and_revalidated() {
2185        let delivery = delivery();
2186        let start = start(&delivery, 0x60, 1, 1_000_000, 10_000_000);
2187        let completion = OutboxAttemptCompletion::acknowledge(
2188            &start,
2189            Some(Digest::sha256(b"ack")),
2190            timestamp(2_000_000),
2191        )
2192        .unwrap();
2193        let attempt = OutboxAttempt::restore(start.clone(), Some(completion.clone())).unwrap();
2194
2195        macro_rules! rejects_extra {
2196            ($value:expr, $type:ty) => {{
2197                let mut extra = to_value($value).unwrap();
2198                extra["unsafe_extension"] = Value::Bool(true);
2199                assert!(from_value::<$type>(extra).is_err());
2200            }};
2201        }
2202        rejects_extra!(delivery.intent(), OutboxDeliveryIntent);
2203        rejects_extra!(&delivery, OutboxDelivery);
2204        rejects_extra!(delivery.head(), OutboxDeliveryHead);
2205        rejects_extra!(&start, OutboxAttemptStart);
2206        rejects_extra!(start.head(), OutboxAttemptStartHead);
2207        rejects_extra!(&completion, OutboxAttemptCompletion);
2208        rejects_extra!(&attempt, OutboxAttempt);
2209
2210        let mut changed = to_value(completion).unwrap();
2211        changed["outcome"]["evidence_digest"] = json!(Digest::sha256(b"changed"));
2212        assert!(from_value::<OutboxAttemptCompletion>(changed).is_err());
2213    }
2214
2215    proptest! {
2216        #[test]
2217        fn safe_after_projection_changes_only_at_the_exact_boundary(
2218            delay_millis in 1_i64..=86_000_000_i64,
2219        ) {
2220            let delivery = delivery_with_deadline(86_400_000_000);
2221            let attempt_start = start(&delivery, 0x70, 1, 1_000_000, 10_000_000);
2222            let completed_at = timestamp(2_000_000);
2223            let completion = OutboxAttemptCompletion::fail(
2224                &attempt_start,
2225                failure(
2226                    0x71,
2227                    RetryAdvice::SafeAfter {
2228                        delay: DurationMillis::new(delay_millis).unwrap(),
2229                    },
2230                ),
2231                completed_at,
2232            )
2233            .unwrap();
2234            let mut verifier = OutboxAttemptHistoryVerifier::new(&delivery);
2235            verifier
2236                .verify_next(&OutboxAttempt::restore(attempt_start, Some(completion)).unwrap())
2237                .unwrap();
2238            let eligible_at = timestamp(2_000_000 + delay_millis * 1_000);
2239            let before = Timestamp::from_unix_micros(eligible_at.unix_micros() - 1).unwrap();
2240
2241            prop_assert_eq!(
2242                verifier.status_at(before).unwrap(),
2243                OutboxDeliveryStatus::RetryScheduled
2244            );
2245            prop_assert_eq!(
2246                verifier.status_at(eligible_at).unwrap(),
2247                OutboxDeliveryStatus::Pending
2248            );
2249        }
2250
2251        #[test]
2252        fn fixed_attempt_lease_acceptance_matches_the_published_bound(
2253            lease_millis in 1_i64..=MAX_OUTBOX_ATTEMPT_LEASE_MILLIS + 1,
2254        ) {
2255            let delivery = delivery_with_deadline(600_000_000);
2256            let result = OutboxAttemptStart::new(
2257                &delivery,
2258                DeliveryFence::new(
2259                    delivery.intent().tenant_id().clone(),
2260                    delivery.intent().run_id(),
2261                    delivery.intent().delivery_id(),
2262                    id::<AttemptId>(0x72),
2263                    FencingEpoch::FIRST,
2264                ),
2265                timestamp(1_000_000),
2266                timestamp(1_000_000 + lease_millis * 1_000),
2267            );
2268            prop_assert_eq!(result.is_ok(), lease_millis <= MAX_OUTBOX_ATTEMPT_LEASE_MILLIS);
2269        }
2270    }
2271}