rusty-agent-runtime 0.10.0

The durable agent runtime built in Rust — core graph engine: typed channels with reducers, Pregel/BSP super-step execution, checkpoints, interrupts, and streaming.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
//! Effect kernel v2 (R0.7): retry-safety moves from runtime convention into
//! the type system.
//!
//! R0.5 froze the [`Effect`] taxonomy as a wire contract and R0.6 made it a
//! runtime convention — [`crate::durable::classify_retry`] refuses to silently
//! retry anything that is not [`Effect::is_freely_repeatable`]. That gate is a
//! function call away from being ignored: nothing in the type of a node,
//! tool, or durable task says what its failure modes are. This module adds
//! the compile-time half. An effect type declares its safety class by
//! implementing one of the marker traits below; generic infrastructure (a
//! retry loop, a speculator, the R0.7 race pattern) can then *require* a
//! class at the type level instead of re-checking a convention at runtime.
//!
//! The marker traits **compose with** the wire enum, they do not replace it:
//! [`Effect`] stays the serde/golden-pinned contract journals and envelopes
//! are written in; the typed kernel is the in-process API that enforcement
//! points are built from. The mapping is one-to-one, with one deliberate
//! naming reconciliation:
//!
//! | Marker trait            | Wire [`Effect`]   | What the class unlocks |
//! |-------------------------|-------------------|------------------------|
//! | [`PureEffect`]          | `Pure`            | caching, speculation, unrestricted retry |
//! | [`ReadOnlyEffect`]      | `ReadOnly`        | unrestricted retry; replay serves the journaled value |
//! | [`IdempotentEffect`]    | `Idempotent`      | automatic retry under a stable idempotency key |
//! | [`CompensatableEffect`] | `Compensatable`   | execution only with a registered rollback handler |
//! | [`IrreversibleEffect`]  | `NonIdempotent`   | execution only behind an explicit [`ApprovalToken`] |
//!
//! The 2026-08-08 review names the last rung *Irreversible*; the wire enum
//! calls it `NonIdempotent`. We keep the wire name for two reasons: the
//! enum's serde shape is golden-pinned evidence (an additive rename would
//! churn every journal for zero semantic gain), and `NonIdempotent` states
//! what the runtime can actually *verify* — the absence of a declared
//! idempotency story — whereas irreversibility is a claim about the world it
//! cannot check. The typed API adopts the review's vocabulary
//! ([`IrreversibleEffect`]) because that is the word that makes the approval
//! boundary legible at a call site; the two names denote one class.
//!
//! Two further mechanisms close the loop with the R0.6 receipt ledger:
//!
//! - **Deterministic effect ids** ([`derive_effect_id`], [`EffectId`]) — a
//!   content-addressed identity derived from the run scope, the effect kind,
//!   the input hash, and the idempotency key. On recovery the runtime asks
//!   "did this exact effect already commit?" and the journal answers through
//!   [`crate::journal::JournalSnapshot::find_effect_receipt_by_effect_id`].
//! - **The approval boundary** ([`ApprovalToken`], [`admit_irreversible`]) —
//!   an irreversible effect executes only when presented with a token scoped
//!   to its derived effect id. The token is a proof-of-explicit-decision
//!   *within the process*: it makes approval a value that must be
//!   constructed, not a boolean that can be silently defaulted. Cross-process
//!   attestation of approvals is R0.9's signed-receipt work.
//!
//! Runtime enforcement is opt-in: enabling effect admission on an executor
//! propagates a scoped [`EffectAdmissionContext`] through
//! [`crate::node::NodeContext`]. The prebuilt ReAct tools node carries it into
//! [`crate::tool::ToolExecutor`] automatically; custom nodes must do the same
//! when they construct a tool executor. Calls on that guarded path are
//! admitted after middleware has finalized their name and arguments but
//! before the tool body runs. Direct calls to [`crate::tool::Tool::call`] are
//! outside this cooperative boundary. Executors that do not enable it keep
//! the pre-R0.7 behavior, so existing graphs remain source-compatible.

use std::collections::BTreeMap;
use std::sync::{Arc, Mutex};

use serde::{Deserialize, Serialize};
use serde_json::Value;
use thiserror::Error;

use crate::record::{sha256_hex, Effect};

/// Domain-separation and versioning prefix for [`derive_effect_id`].
///
/// Effect ids are content addresses; the prefix keeps them collision-free
/// against every other SHA-256 digest in the system (artifact references,
/// journal heads, topology hashes) and gives the derivation formula an
/// explicit version handle if it ever needs to change.
pub const EFFECT_ID_DOMAIN: &str = "rusty/effect-id/v1";

/// A deterministic, content-addressed identity for one logical effect
/// within a run scope.
///
/// Derived — never minted — by [`derive_effect_id`]: the same `(scope, kind,
/// input hash, idempotency key)` tuple always yields the same id, so a
/// recovered run re-derives the id of the effect it was about to perform and
/// asks the journal whether a receipt already exists for it. That lookup is
/// what turns "retry carefully" into "do not re-execute what already
/// committed" — exactly-once *business outcomes* where the effect protocol
/// supports it, never a pretend exactly-once execution.
///
/// Transparent newtype over the lowercase hex digest: serializes as a bare
/// string, consistent with [`crate::record::ArtifactRef`].
#[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(transparent)]
pub struct EffectId(String);

impl EffectId {
    /// The hex digest.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

impl std::fmt::Display for EffectId {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.0)
    }
}

/// Derive the deterministic id of an effect occurrence.
///
/// The formula is `SHA-256` over the newline-joined, domain-prefixed tuple:
///
/// ```text
/// EFFECT_ID_DOMAIN "\n" scope "\n" kind "\n" input_hash "\n" (idempotency_key | "-")
/// ```
///
/// - `scope` is the run (or sub-run) identity the effect belongs to — two
///   runs performing the same call get different ids, so a receipt from one
///   run can never masquerade as another's.
/// - `kind` is the effect type's stable identifier ([`TypedEffect::kind`]).
/// - `input_hash` is the lowercase hex SHA-256 of the canonical input (the
///   same canonical `serde_json` serialization [`crate::record::PayloadRef::content_hash`]
///   uses), precomputed by the caller so this function stays IO-free.
/// - `idempotency_key` distinguishes intentional replays under one key from
///   distinct effects that happen to share an input; `-` fills the slot when
///   the effect has no key, so keyed and unkeyed derivations can never
///   collide.
///
/// Newline-joining (rather than concatenation) keeps the tuple unambiguous
/// without a length prefix — the same framing [`crate::graph::Graph::topology_hash`]
/// uses for topology lines.
pub fn derive_effect_id(
    scope: &str,
    kind: &str,
    input_hash: &str,
    idempotency_key: Option<&str>,
) -> EffectId {
    let material = [
        EFFECT_ID_DOMAIN,
        scope,
        kind,
        input_hash,
        idempotency_key.unwrap_or("-"),
    ]
    .join("\n");
    EffectId(sha256_hex(material.as_bytes()))
}

/// The runtime description of one effect occurrence awaiting admission.
///
/// [`TypedEffect`] is the compile-time declaration surface; this value is its
/// object-safe dispatch counterpart. A [`crate::tool::Tool`] produces one for
/// each call after middleware has finalized the call. Its input hash is
/// computed with the same canonical JSON convention as journal payloads, so
/// approval tokens derived before execution match the id the dispatcher
/// re-derives at the boundary.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EffectRequest {
    kind: String,
    effect: Effect,
    input_hash: String,
    idempotency_key: Option<String>,
}

impl EffectRequest {
    /// Describe an effect over canonical JSON `input`.
    pub fn new(
        kind: impl Into<String>,
        effect: Effect,
        input: &Value,
        idempotency_key: Option<String>,
    ) -> Self {
        let input_hash = crate::record::PayloadRef::inline(input.clone())
            .content_hash()
            .expect("a serde_json::Value always serializes");
        Self {
            kind: kind.into(),
            effect,
            input_hash,
            idempotency_key,
        }
    }

    /// Bridge a typed declaration into the runtime admission surface.
    pub fn from_typed<E: TypedEffect>(effect: &E) -> Self {
        Self {
            kind: effect.kind().to_owned(),
            effect: E::EFFECT,
            input_hash: effect.input_hash().to_owned(),
            idempotency_key: effect.idempotency_key().map(str::to_owned),
        }
    }

    /// Stable application-defined effect kind.
    pub fn kind(&self) -> &str {
        &self.kind
    }

    /// Wire-level safety class recorded for this occurrence.
    pub fn effect(&self) -> Effect {
        self.effect
    }

    /// Canonical input digest used in the deterministic effect id.
    pub fn input_hash(&self) -> &str {
        &self.input_hash
    }

    /// Stable idempotency key, when the declaration requires one.
    pub fn idempotency_key(&self) -> Option<&str> {
        self.idempotency_key.as_deref()
    }

    /// This occurrence's deterministic id in `scope`.
    pub fn effect_id(&self, scope: &str) -> EffectId {
        derive_effect_id(
            scope,
            self.kind(),
            self.input_hash(),
            self.idempotency_key(),
        )
    }
}

/// The typed half of the effect taxonomy: an effect type's contract with the
/// kernel.
///
/// Implement this trait plus exactly one marker trait ([`PureEffect`],
/// [`ReadOnlyEffect`], [`IdempotentEffect`], [`CompensatableEffect`],
/// [`IrreversibleEffect`]) to declare an effect's safety class. The marker is
/// the compile-time claim; [`TypedEffect::EFFECT`] is the wire-level class it
/// must agree with — every admission helper checks the two against each
/// other, so a type whose marker and declared class disagree is rejected at
/// the enforcement point, not silently misclassified.
pub trait TypedEffect {
    /// The wire-level [`Effect`] class this type records in journals and
    /// envelopes. Must agree with the marker trait the type implements (see
    /// the module-level mapping table); the admission helpers enforce the
    /// agreement.
    const EFFECT: Effect;

    /// The effect kind: a stable, application-chosen identifier
    /// (`"charge_card"`, `"index_document"`). Part of the effect id and the
    /// key under which rollback handlers are registered, so it must not
    /// change between deployments that share a journal.
    fn kind(&self) -> &str;

    /// Lowercase hex SHA-256 of the effect's canonical input. Two calls with
    /// equal inputs must hash equal — use the canonical `serde_json`
    /// serialization, as [`crate::record::PayloadRef::content_hash`] does.
    fn input_hash(&self) -> &str;

    /// The idempotency key the effect commits under, when it has one. The
    /// key participates in the effect id, so retried derivation under the
    /// same key converges on the id a recovery pass looks up. `None` is
    /// honest only for effects that are freely repeatable without a key.
    fn idempotency_key(&self) -> Option<&str> {
        None
    }

    /// This effect's deterministic id within `scope` (usually the run id) —
    /// [`derive_effect_id`] over the type's own contract fields.
    fn effect_id(&self, scope: &str) -> EffectId {
        derive_effect_id(
            scope,
            self.kind(),
            self.input_hash(),
            self.idempotency_key(),
        )
    }
}

/// Marker: a pure function of its inputs with no observable effect beyond
/// its return value (wire class [`Effect::Pure`]).
///
/// Pure work may be cached, memoized, and speculated freely: re-execution is
/// always safe and always equivalent, so a speculative result and an
/// on-demand result are indistinguishable. Declare it by implementing this
/// trait; [`admit_speculation`] is the enforcement point speculators call.
pub trait PureEffect: TypedEffect {}

/// Marker: reads external state but writes nothing (wire class
/// [`Effect::ReadOnly`]).
///
/// Re-execution is safe but not necessarily equivalent — the world may have
/// changed — so exact replay serves the journaled value while live replay
/// re-reads. Retries are unconstrained, which is why there is no admission
/// helper for this class: nothing needs gating.
pub trait ReadOnlyEffect: TypedEffect {}

/// Marker: repeating the call under the same idempotency key has the same
/// effect as calling once (wire class [`Effect::Idempotent`]).
///
/// This is the class that unlocks automatic retry — the typed form of the
/// gate [`crate::durable::classify_retry`] applies to the untyped enum.
/// [`admit_retry`] additionally requires the key itself: retrying an
/// "idempotent" effect with no key is the exact unsoundness the taxonomy
/// exists to prevent, and the helper refuses it.
pub trait IdempotentEffect: TypedEffect {}

/// Marker: repeating the call duplicates the effect, but a declared
/// compensating action can logically undo it — charge/refund (wire class
/// [`Effect::Compensatable`]).
///
/// The compensation is not optional coloring: [`admit_compensatable`]
/// requires a rollback handler registered for the effect's kind before the
/// effect may execute, and returns that handler so the caller holds the undo
/// path from the start. Automatic compensation remains out of scope
/// (unchanged from R0.6: `Compensatable` fails closed in the untyped retry
/// path) — the handler is invoked by policy, not by the kernel.
pub trait CompensatableEffect: TypedEffect {}

/// Marker: no safe automatic repetition and no logical undo — send the
/// email, fire the charge without a key (wire class [`Effect::NonIdempotent`];
/// see the module docs for the deliberate naming reconciliation).
///
/// Execution requires an explicit [`ApprovalToken`] scoped to the effect's
/// derived id, presented to [`admit_irreversible`]. Unknown or undeclared
/// effects belong here by default: the wire enum already defaults to
/// `NonIdempotent`, and the typed kernel keeps that convention — what is not
/// declared is never silently retried and never executes without approval.
pub trait IrreversibleEffect: TypedEffect {}

/// Why the kernel refused an admission decision.
///
/// A dedicated error type (not [`crate::error::RustyError`]) because these
/// are contract violations surfaced by the typed API, not runtime execution
/// failures; the executor maps them into its own error path when the
/// enforcement wave lands.
#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum EffectViolation {
    /// The marker trait and [`TypedEffect::EFFECT`] disagree — a type-level
    /// bug, caught at the enforcement point rather than trusted.
    #[error(
        "effect kind `{kind}` is marked with the {marker:?} marker trait but declares \
         {declared:?}: the marker and TypedEffect::EFFECT must agree"
    )]
    DeclarationMismatch {
        /// The effect's kind identifier.
        kind: String,
        /// The wire class the marker trait implies.
        marker: Effect,
        /// The wire class the type actually declared.
        declared: Effect,
    },

    /// An [`IdempotentEffect`] presented for retry admission without the
    /// idempotency key the declaration is meaningless without.
    #[error(
        "idempotent effect kind `{kind}` has no idempotency key: a stable key is what the \
         idempotency declaration means at the wire"
    )]
    MissingIdempotencyKey {
        /// The effect's kind identifier.
        kind: String,
    },

    /// A [`CompensatableEffect`] with no rollback handler registered for its
    /// kind.
    #[error(
        "compensatable effect kind `{kind}` has no registered rollback handler: register one \
         in a CompensationRegistry before executing it"
    )]
    MissingCompensation {
        /// The effect's kind identifier.
        kind: String,
    },

    /// An [`IrreversibleEffect`] presented for execution with no approval
    /// token at all.
    #[error(
        "irreversible effect kind `{kind}` ({effect_id}) requires an explicit approval token \
         scoped to its effect id"
    )]
    MissingApproval {
        /// The effect's kind identifier.
        kind: String,
        /// The effect id the approval must be scoped to.
        effect_id: EffectId,
    },

    /// A token was presented, but it approves a different effect id — an
    /// approval is scoped to exactly one effect occurrence and is not
    /// transferable.
    #[error(
        "approval token for {presented} does not admit irreversible effect kind `{kind}` \
         ({required})"
    )]
    ApprovalScopeMismatch {
        /// The effect's kind identifier.
        kind: String,
        /// The effect id the admission requires.
        required: EffectId,
        /// The effect id the presented token approves.
        presented: EffectId,
    },
}

/// An explicit, scoped approval to execute one irreversible effect
/// occurrence.
///
/// The token is the approval *boundary made into a value*: constructing one
/// is the decision, and [`admit_irreversible`] accepts it only for the exact
/// [`EffectId`] it was minted against, so an approval for one charge cannot
/// launder another. Within a process this is a proof of explicit decision —
/// it cannot stop code that is determined to forge one, and it is not meant
/// to; cross-process attestation is R0.9's signed-receipt work. What it does
/// guarantee is structural: there is no code path through the typed kernel
/// that executes an irreversible effect on a defaulted or forgotten
/// approval.
///
/// Tokens ride the run via [`crate::executor::RunConfig::with_effect_approvals`]
/// so the approval set travels with the run's configuration.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ApprovalToken {
    /// The effect occurrence this token approves.
    effect_id: EffectId,

    /// Who approved — a human operator id, a policy name, a supervision
    /// decision reference. Evidence, not authentication: recorded so the
    /// journal can attribute the boundary when approval journaling lands.
    approved_by: String,
}

impl ApprovalToken {
    /// Mint an approval for exactly one effect id. This constructor is the
    /// approval act: call sites should read as decisions (`let approval =
    /// ApprovalToken::approve(id, "ops:amjad")`), not as plumbing.
    pub fn approve(effect_id: EffectId, approved_by: impl Into<String>) -> Self {
        Self {
            effect_id,
            approved_by: approved_by.into(),
        }
    }

    /// Mint an approval scoped to `effect`'s derived id within `scope` — the
    /// common case, approving the occurrence a run is about to execute.
    pub fn for_effect<E: IrreversibleEffect>(
        effect: &E,
        scope: &str,
        approved_by: impl Into<String>,
    ) -> Self {
        Self::approve(effect.effect_id(scope), approved_by)
    }

    /// The effect id this token approves.
    pub fn effect_id(&self) -> &EffectId {
        &self.effect_id
    }

    /// Who approved.
    pub fn approved_by(&self) -> &str {
        &self.approved_by
    }

    /// Whether this token admits `effect_id`. Scoped, not transferable: only
    /// the exact occurrence it was minted against.
    pub fn admits(&self, effect_id: &EffectId) -> bool {
        &self.effect_id == effect_id
    }
}

/// A registered rollback handler for a [`CompensatableEffect`] kind.
///
/// The handler receives the journaled output of the effect occurrence to
/// undo and returns a compensation record (what was done to undo it) for
/// journaling. Errors are plain strings because compensation failures cross
/// the retry taxonomy's string-classified boundary — a failed compensation
/// is an operator signal, classified and surfaced, never silently retried by
/// the kernel (automatic compensation stays out of scope, as in R0.6).
///
/// `Arc`-wrapped so an admission can hand the caller a cheap clone of the
/// registered undo path.
pub type CompensationHandler = Arc<dyn Fn(&Value) -> Result<Value, String> + Send + Sync>;

/// The registry of rollback handlers backing [`admit_compensatable`].
///
/// Registration is the mechanism that makes a `Compensatable` declaration
/// meaningful: the handler for an effect kind must exist *before* the effect
/// executes, so the undo path is a precondition, not a postmortem. Handlers
/// are keyed by [`TypedEffect::kind`]; re-registering a kind replaces its
/// handler (and returns the old one) so deployments can evolve compensation
/// logic deliberately.
#[derive(Default, Clone)]
pub struct CompensationRegistry {
    handlers: BTreeMap<String, CompensationHandler>,
}

impl std::fmt::Debug for CompensationRegistry {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Handlers are opaque closures; the registered kinds are the useful
        // debug surface.
        f.debug_set().entries(self.handlers.keys()).finish()
    }
}

impl CompensationRegistry {
    /// An empty registry: every `Compensatable` admission fails until a
    /// handler is registered — the fail-closed default.
    pub fn new() -> Self {
        Self::default()
    }

    /// Register `handler` as the rollback path for `kind`, returning the
    /// handler it replaced, if any.
    pub fn register(
        &mut self,
        kind: impl Into<String>,
        handler: CompensationHandler,
    ) -> Option<CompensationHandler> {
        self.handlers.insert(kind.into(), handler)
    }

    /// The handler registered for `kind`, if any.
    pub fn handler_for(&self, kind: &str) -> Option<&CompensationHandler> {
        self.handlers.get(kind)
    }
}

/// A run-scoped, fail-closed admission boundary for runtime effect requests.
///
/// The scope is normally a thread id. Approvals are indexed by their exact
/// deterministic [`EffectId`], and compensations are captured when a request
/// is admitted so the rollback path remains alive for the entire call.
#[derive(Clone)]
pub struct EffectAdmissionContext {
    scope: String,
    approvals: Arc<Mutex<BTreeMap<EffectId, ApprovalToken>>>,
    compensations: CompensationRegistry,
}

impl std::fmt::Debug for EffectAdmissionContext {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let approvals = self.approvals.lock().unwrap_or_else(|e| e.into_inner());
        f.debug_struct("EffectAdmissionContext")
            .field("scope", &self.scope)
            .field("approval_effect_ids", &approvals.keys())
            .field("compensations", &self.compensations)
            .finish()
    }
}

impl EffectAdmissionContext {
    /// Start an admission boundary for `scope` with no approvals or rollback
    /// handlers. This is intentionally fail-closed for compensatable and
    /// irreversible effects.
    pub fn new(scope: impl Into<String>) -> Self {
        Self {
            scope: scope.into(),
            approvals: Arc::new(Mutex::new(BTreeMap::new())),
            compensations: CompensationRegistry::new(),
        }
    }

    /// Attach the exact approval tokens available to this run.
    pub fn with_approvals(mut self, approvals: impl IntoIterator<Item = ApprovalToken>) -> Self {
        self.approvals = Arc::new(Mutex::new(
            approvals
                .into_iter()
                .map(|token| (token.effect_id().clone(), token))
                .collect(),
        ));
        self
    }

    /// Attach the run's registered rollback handlers.
    pub fn with_compensations(mut self, compensations: CompensationRegistry) -> Self {
        self.compensations = compensations;
        self
    }

    /// The run scope used to derive effect ids.
    pub fn scope(&self) -> &str {
        &self.scope
    }

    /// Admit one effect occurrence, or reject it before its body runs.
    ///
    /// Pure and read-only calls require no additional evidence. Idempotent
    /// calls require a stable key, compensatable calls require a registered
    /// rollback handler, and non-idempotent calls atomically consume an
    /// approval token for this exact content-addressed occurrence. Cloned
    /// contexts share the same approval ledger, so one token admits one call
    /// across parallel nodes and later super-steps.
    pub fn admit(&self, request: &EffectRequest) -> Result<EffectPermit, EffectViolation> {
        let effect_id = request.effect_id(self.scope());
        let (compensation, approval) = match request.effect() {
            Effect::Pure | Effect::ReadOnly => (None, None),
            Effect::Idempotent => {
                if request.idempotency_key().is_none() {
                    return Err(EffectViolation::MissingIdempotencyKey {
                        kind: request.kind().to_owned(),
                    });
                }
                (None, None)
            }
            Effect::Compensatable => (
                Some(
                    self.compensations
                        .handler_for(request.kind())
                        .cloned()
                        .ok_or_else(|| EffectViolation::MissingCompensation {
                            kind: request.kind().to_owned(),
                        })?,
                ),
                None,
            ),
            Effect::NonIdempotent => {
                let approval = self
                    .approvals
                    .lock()
                    .unwrap_or_else(|e| e.into_inner())
                    .remove(&effect_id)
                    .ok_or_else(|| EffectViolation::MissingApproval {
                        kind: request.kind().to_owned(),
                        effect_id: effect_id.clone(),
                    })?;
                (None, Some(approval))
            }
        };
        Ok(EffectPermit {
            effect_id,
            compensation,
            approval,
        })
    }
}

/// Evidence that one runtime effect occurrence passed admission.
///
/// The permit deliberately owns the selected compensation handler. The tool
/// dispatcher keeps it alive until the call completes, preventing a registry
/// update from removing the rollback path after admission but before the
/// effect finishes.
#[derive(Clone)]
pub struct EffectPermit {
    effect_id: EffectId,
    compensation: Option<CompensationHandler>,
    approval: Option<ApprovalToken>,
}

impl std::fmt::Debug for EffectPermit {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("EffectPermit")
            .field("effect_id", &self.effect_id)
            .field("has_compensation", &self.compensation.is_some())
            .field(
                "approved_by",
                &self.approval.as_ref().map(ApprovalToken::approved_by),
            )
            .finish()
    }
}

impl EffectPermit {
    /// The admitted occurrence's deterministic id.
    pub fn effect_id(&self) -> &EffectId {
        &self.effect_id
    }

    /// The rollback handler captured for a compensatable occurrence.
    pub fn compensation(&self) -> Option<&CompensationHandler> {
        self.compensation.as_ref()
    }

    /// The one-shot approval consumed for an irreversible occurrence.
    pub fn approval(&self) -> Option<&ApprovalToken> {
        self.approval.as_ref()
    }
}

/// The marker/class agreement check every admission helper runs first.
///
/// The marker traits carry no methods, so a mismatched pair (`impl
/// IrreversibleEffect` with `EFFECT = Effect::Pure`) compiles; it must not
/// *pass*. Checking at admission keeps the typed API honest without needing
/// compile-fail machinery: a lying declaration is rejected where it would be
/// exploited.
fn check_declaration<E: TypedEffect>(effect: &E, marker: Effect) -> Result<(), EffectViolation> {
    if E::EFFECT != marker {
        return Err(EffectViolation::DeclarationMismatch {
            kind: effect.kind().to_owned(),
            marker,
            declared: E::EFFECT,
        });
    }
    Ok(())
}

/// Admit a [`PureEffect`] to caching/speculation.
///
/// Always succeeds for an honestly declared type — the helper exists so the
/// speculator's call site names the precondition it relies on, and so a
/// mismatched declaration (marker trait disagreeing with
/// [`TypedEffect::EFFECT`]) is caught here rather than after a speculated
/// side effect.
pub fn admit_speculation<E: PureEffect>(effect: &E) -> Result<(), EffectViolation> {
    check_declaration::<E>(effect, Effect::Pure)
}

/// Admit an [`IdempotentEffect`] to automatic retry.
///
/// The typed form of the [`crate::durable::classify_retry`] effect gate, with
/// the convention made checkable: the effect must carry the idempotency key
/// its declaration means nothing without. Untyped `Effect` values keep their
/// R0.6 behavior exactly — this helper gates only the typed path.
pub fn admit_retry<E: IdempotentEffect>(effect: &E) -> Result<(), EffectViolation> {
    check_declaration::<E>(effect, Effect::Idempotent)?;
    if effect.idempotency_key().is_none() {
        return Err(EffectViolation::MissingIdempotencyKey {
            kind: effect.kind().to_owned(),
        });
    }
    Ok(())
}

/// Admit a [`CompensatableEffect`] to execute, returning its registered
/// rollback handler.
///
/// The handler is returned — not merely checked — so the caller holds the
/// undo path from the moment the effect is admitted; an effect whose kind
/// has no registered handler is rejected.
pub fn admit_compensatable<E: CompensatableEffect>(
    effect: &E,
    registry: &CompensationRegistry,
) -> Result<CompensationHandler, EffectViolation> {
    check_declaration::<E>(effect, Effect::Compensatable)?;
    registry.handler_for(effect.kind()).cloned().ok_or_else(|| {
        EffectViolation::MissingCompensation {
            kind: effect.kind().to_owned(),
        }
    })
}

/// Admit an [`IrreversibleEffect`] to execute behind an explicit approval.
///
/// `scope` must be the run scope the effect id was (and will be) derived in
/// — the same value recovery uses to re-derive the id. The presented token
/// must be scoped to exactly that id; anything else — no token, or a token
/// for another occurrence — is rejected. The approval boundary this wave
/// lands as a helper becomes an executor enforcement point in a later wave.
pub fn admit_irreversible<E: IrreversibleEffect>(
    effect: &E,
    scope: &str,
    approval: Option<&ApprovalToken>,
) -> Result<(), EffectViolation> {
    check_declaration::<E>(effect, Effect::NonIdempotent)?;
    let required = effect.effect_id(scope);
    let token = approval.ok_or_else(|| EffectViolation::MissingApproval {
        kind: effect.kind().to_owned(),
        effect_id: required.clone(),
    })?;
    if !token.admits(&required) {
        return Err(EffectViolation::ApprovalScopeMismatch {
            kind: effect.kind().to_owned(),
            required,
            presented: token.effect_id().clone(),
        });
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn effect_id_derivation_is_deterministic_and_scoped() {
        let a = derive_effect_id("run-1", "charge_card", "abc123", Some("key-7"));
        let b = derive_effect_id("run-1", "charge_card", "abc123", Some("key-7"));
        assert_eq!(a, b, "same inputs must derive the same id");
        assert_eq!(a.as_str().len(), 64, "ids are hex SHA-256 digests");

        // Every tuple component is load-bearing.
        assert_ne!(
            a,
            derive_effect_id("run-2", "charge_card", "abc123", Some("key-7"))
        );
        assert_ne!(
            a,
            derive_effect_id("run-1", "refund", "abc123", Some("key-7"))
        );
        assert_ne!(
            a,
            derive_effect_id("run-1", "charge_card", "def456", Some("key-7"))
        );
        assert_ne!(
            a,
            derive_effect_id("run-1", "charge_card", "abc123", Some("key-8"))
        );
        assert_ne!(a, derive_effect_id("run-1", "charge_card", "abc123", None));
    }

    #[test]
    fn effect_id_is_serde_transparent() {
        let id = derive_effect_id("run-1", "charge_card", "abc123", None);
        let value = serde_json::to_value(&id).unwrap();
        assert_eq!(value, serde_json::json!(id.as_str()));
        let back: EffectId = serde_json::from_value(value).unwrap();
        assert_eq!(back, id);
    }
}