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
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
//! The capability host (R0.9 Rusty Capsules, wave 1): governed execution
//! of untrusted WASM Component Model guests behind the declared manifest.
//!
//! Where [`crate::wasm_node`] runs pure-compute core-WASM guests with no
//! imports at all, the capability host runs *components* whose imports
//! exist only when granted. ABI v0 stays untouched beside this — trusted
//! pure compute keeps the fast path; capsules are the untrusted-with-
//! capabilities case. There is no migration.
//!
//! # Structural denial, and what it does and does not prove
//!
//! A capsule instantiates against its manifest's declared WIT world
//! ([`crate::capsule::WORLD_V1`]), and the host links exactly the imports
//! the granted capabilities name. Before instantiation the host walks the
//! component's import list: an import whose capability class carries no
//! grant is never linked, and the invocation is refused with a journaled
//! [`CapsuleDenial`]. This is the object-capability property enforced by
//! the linker: a component built without the `net` import cannot reach
//! the network even in-process — there is no symbol to call, no handle to
//! forge. What it proves: a guest *without* the import cannot attempt the
//! capability at all. What it does not prove: anything about a guest
//! *with* the import — a linked import is a door, and the grant says how
//! far it opens.
//!
//! That second half is scoped denial. A `network` grant naming one
//! hostname links the `fetch` import, but the host's import implementation
//! matches host + protocol + method against the grant set before anything
//! executes, and a mismatch is refused in-band and journaled as a
//! [`CapsuleDenial`] naming the absent grant (granted host A, attempted
//! host B — the absent grant is `network` scoped to host B). A scoped
//! denial is a runtime check, honestly: it can be evaluated only when the
//! attempt arrives. Both denials journal through the same event kind,
//! distinguished by their payloads — structural denials carry an
//! empty-scope absent grant (no grant at any scope existed), scoped
//! denials name the scope that was missing.
//!
//! # Resource governance
//!
//! Three wasmtime mechanisms, one per budget axis: **fuel** is the CPU
//! budget (deterministic, replay-stable — the `wasm_node` inheritance);
//! **epoch interruption** is the wall-time budget's enforcement arm — a
//! per-host ticker advances the engine epoch every `EPOCH_TICK_MS`
//! milliseconds, and each store's deadline is set in ticks, so a guest
//! that stops yielding is preempted (the fuel-only model cannot express
//! this, which is why capsules need their own host); the
//! [`ResourceLimiter`] carries the memory cap. Budget breaches abort the
//! invocation and are journaled on the invocation event with the budget
//! that bit, when it is confidently attributable (fuel reads the store's
//! remaining fuel; wall time reads the clock; memory and other traps are
//! reported unattributed rather than guessed).
//!
//! # Output gate
//!
//! The guest's result crosses the trust boundary as a string. Before the
//! host accepts it: `max_output_bytes` is enforced, and the payload must
//! parse as JSON. Full draft-2020-12 validation against the manifest's
//! declared `output_schema` is pinned in the contract and lands with the
//! wave that adopts a validator — the same staging
//! [`crate::durable::ArtifactContract::schema`] documented in R0.7. The
//! canonical ABI itself has already typed the export (`result<string,
//! string>`): an untrusted component's output is a claim to validate,
//! never a structure to trust.
//!
//! # Journaling
//!
//! Given a [`Journal`], every invocation records: the invocation itself
//! (a [`RunEventKind::WasmCall`] event — a capsule invocation *is* a WASM
//! guest call; the payload names the capsule id), every granted
//! capability use ([`RunEventKind::CapsuleCall`], the capsule rule's
//! "every use is journaled" half), and every denial
//! ([`RunEventKind::CapsuleDenied`]). Capability events chain causally
//! from the run event the caller passes as `parent`.
//!
//! # Revocation at the next use (R0.9 wave 2)
//!
//! Admission-time authorization (the server's Cedar plane) evaluates
//! static policy; it cannot retroactively un-admit a capsule already
//! running under yesterday's grants. The wave-2 answer is the
//! [`GrantRecheck`] seam: each granted import implementation — `fetch`,
//! `now-millis`, the wave-1 world — re-authorizes the exact scope it is
//! about to exercise *after* the wave-1 scope match and *before*
//! anything executes. A grant revoked since admission refuses in-band
//! and journals a [`CapsuleDenial`] pinned to the **live** policy
//! version — the new verdict, not the version the capsule was admitted
//! under. In-flight invocations keep their fuel and wall-time budgets
//! regardless: a revocation that cannot interrupt a running capsule
//! still bounds how long it can run. Core owns the trait and the
//! enforcement; the server owns the implementation (the
//! [`NetworkConnector`] boundary, drawn for the same reason — the core
//! crate stays engine-free).

use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use std::time::{Duration, Instant};

use serde::Serialize;
use serde_json::{json, Value};
use wasmtime::component::{Component, Linker};
use wasmtime::{Config, Engine, ResourceLimiter, Store};

use crate::capsule::{
    any_grant_of_kind, is_read_only_method, network_grant_covers, CapabilityGrant, CapabilityKind,
    CapsuleDenial, CapsuleId, CapsuleManifest, CapsuleUse, ResourceBudget,
};
use crate::error::{Result, RustyError};
use crate::journal::{EventDraft, Journal};
use crate::record::{sha256_hex, Effect, EventStatus, RunEventKind};

/// The wave-1 world's network import instance. Hand-written components
/// import this exact name; the linker provides it when — and only when —
/// the manifest grants `network`.
const NET_INSTANCE: &str = "rusty:capsule/net@0.1.0";

/// The wave-1 world's clock import instance, linked when the manifest
/// grants `clock`.
const CLOCK_INSTANCE: &str = "rusty:capsule/clock@0.1.0";

/// The epoch ticker's cadence. Wall-time deadlines are set in ticks, so
/// enforcement granularity is one tick — coarse on purpose (a budget is a
/// bound, not a schedule), cheap enough to run per capsule host.
const EPOCH_TICK_MS: u64 = 5;

/// Map a component import name onto the capability class it belongs to.
/// The mapping is total over the wave-1 world: an import naming nothing
/// here is outside every supported world and fails closed.
fn capability_for_import(name: &str) -> Option<CapabilityKind> {
    match name {
        NET_INSTANCE => Some(CapabilityKind::Network),
        CLOCK_INSTANCE => Some(CapabilityKind::Clock),
        _ => None,
    }
}

/// One outbound network call, as the host's `fetch` import receives it.
/// The connector never sees the guest — it sees this validated request.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FetchRequest {
    /// The protocol (`https`, `http`, …) — matched against the grant.
    pub protocol: String,
    /// The hostname — matched against the grant.
    pub host: String,
    /// The HTTP method — matched against the grant.
    pub method: String,
    /// The request path (not grant-matched; the grant scopes the origin).
    pub path: String,
    /// The request body, when the guest sent one.
    pub body: Option<String>,
}

/// The connector's answer to a [`FetchRequest`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FetchResponse {
    /// The HTTP status code.
    pub status: u16,
    /// The response body.
    pub body: String,
}

/// The egress seam: where a deployment plugs its outbound path for
/// granted capsule network calls.
///
/// Core owns the trait, applications own the implementation — the
/// `CandidateEvaluator` boundary, drawn for the same reason: the runtime
/// owns the journaled *shape* of the call (scope match, use record,
/// denial) and the deployment owns performing it (its proxy, its auth,
/// its TLS posture). No default ships in wave 1: a manifest granting
/// `network` against a host built without a connector is a configuration
/// error, not an implicit egress path.
pub trait NetworkConnector: std::fmt::Debug + Send + Sync {
    /// Perform one already-grant-matched call. Errors are the connector's
    /// own (DNS, TLS, status handling) — they are journaled as failed
    /// uses, never retried by the host.
    fn fetch(&self, request: &FetchRequest) -> std::result::Result<FetchResponse, String>;
}

/// A revoked grant's refusal (R0.9 wave 2): the live policy verdict that
/// now forbids a use the capsule was admitted with.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RecheckDenial {
    /// The policy version the refusal is journaled against — the *new*
    /// version whose verdict revoked the grant, so the journaled denial
    /// attributes the refusal to the verdict that made it.
    pub policy_version: String,

    /// Human-facing context: which grant stopped holding, and why.
    pub detail: String,
}

/// The revocation seam (R0.9 wave 2): a per-call re-authorization of a
/// granted capability against the *live* policy, plugged into the host
/// like [`NetworkConnector`] and owned by the server.
///
/// Why this exists: admission-time policy evaluation is static — a
/// capsule admitted an hour ago still holds the grants it was admitted
/// with, and a policy change since then is invisible to the wave-1 scope
/// match. Revocation takes effect at the *next capability use*: the
/// granted import implementations consult this seam after the scope
/// match and before anything executes, and a refusal is journaled as a
/// [`CapsuleDenial`] pinned to the live policy version. Without a
/// recheck plugged in the host behaves exactly as wave 1 — the seam is
/// the server's to provide, and a host built for a deployment without
/// the policy plane has nothing to consult.
pub trait GrantRecheck: std::fmt::Debug + Send + Sync {
    /// Re-authorize one capability use. `grant` is the exact scope the
    /// guest is about to exercise (the wave-1 scope match has already
    /// passed). `None` permits the call; `Some(denial)` refuses it,
    /// journaled against `denial.policy_version`.
    fn recheck(&self, capsule_id: &CapsuleId, grant: &CapabilityGrant) -> Option<RecheckDenial>;
}

/// The memory-growth cap, store-local (the `wasm_node` pattern).
struct StoreLimits {
    max_memory_bytes: Option<usize>,
}

impl ResourceLimiter for StoreLimits {
    fn memory_growing(
        &mut self,
        _current: usize,
        desired: usize,
        _maximum: Option<usize>,
    ) -> std::result::Result<bool, wasmtime::Error> {
        Ok(match self.max_memory_bytes {
            Some(cap) => desired <= cap,
            None => true,
        })
    }

    fn table_growing(
        &mut self,
        _current: usize,
        desired: usize,
        _maximum: Option<usize>,
    ) -> std::result::Result<bool, wasmtime::Error> {
        // Guests get tables for function pointers; cap generously but finite.
        Ok(desired <= 100_000)
    }
}

/// What one invocation needs in the store: the effective grants, the
/// connectors, and the journaling cursor. Every invocation builds a fresh
/// store — guests keep no state across calls (the engine's idempotency
/// contract, inherited from `wasm_node`).
struct StoreData {
    limiter: StoreLimits,
    grants: Vec<CapabilityGrant>,
    capsule_id: CapsuleId,
    connector: Option<Arc<dyn NetworkConnector>>,
    clock: Arc<dyn Fn() -> u64 + Send + Sync>,
    recheck: Option<Arc<dyn GrantRecheck>>,
    journal: Option<Journal>,
    parent: Option<String>,
    uses: Vec<CapsuleUse>,
    denials: Vec<CapsuleDenial>,
}

impl StoreData {
    /// Record one capability event, chaining causally from the previous
    /// one (the first chains from the run event the caller named). No
    /// journal means the payloads are still collected on the store data —
    /// evidence survives a journal-less invocation in the outcome.
    fn journal_event(
        &mut self,
        kind: RunEventKind,
        effect: Effect,
        output: Value,
        status: EventStatus,
    ) {
        if let Some(journal) = &self.journal {
            let mut draft = EventDraft::new(kind, effect).output(output).status(status);
            if let Some(parent) = &self.parent {
                draft = draft.parent(parent.clone());
            }
            self.parent = Some(journal.record(draft));
        }
    }

    /// The wave-2 revocation seam: re-authorize the exact scope `grant`
    /// the guest is about to exercise against the live policy. A refusal
    /// is journaled as a [`CapsuleDenial`] pinned to the live policy
    /// version and surfaces in-band, exactly like a wave-1 scope denial.
    fn policy_recheck(&mut self, grant: CapabilityGrant) -> std::result::Result<(), String> {
        let Some(recheck) = &self.recheck else {
            return Ok(());
        };
        let Some(revocation) = recheck.recheck(&self.capsule_id, &grant) else {
            return Ok(());
        };
        let denial = CapsuleDenial::scoped(
            self.capsule_id.clone(),
            grant,
            format!(
                "the grant was admitted but policy version `{}` no longer permits it — \
                 revocation takes effect at the next capability use: {}",
                revocation.policy_version, revocation.detail
            ),
        )
        .with_policy_version(revocation.policy_version);
        self.denials.push(denial.clone());
        let detail = denial.detail.clone();
        if let Ok(output) = serde_json::to_value(&denial) {
            self.journal_event(
                RunEventKind::CapsuleDenied,
                Effect::Pure,
                output,
                EventStatus::Ok,
            );
        }
        Err(format!("denied: {detail}"))
    }
}

/// The inputs to one capsule invocation. Built via
/// [`CapsuleInvocation::new`] plus the builder methods; the budget
/// declared here is the *enclosing run's* bound, clamped field-wise
/// against the manifest's own declaration at invocation
/// ([`ResourceBudget::clamp`]) — the effective budget is never wider than
/// either layer.
#[derive(Debug, Clone)]
pub struct CapsuleInvocation {
    /// The guest's input (serialized to a JSON string at the boundary).
    pub input: Value,

    /// The run's journal, when the invocation should leave evidence.
    pub journal: Option<Journal>,

    /// The causal parent: the run event that caused this invocation.
    pub parent: Option<String>,

    /// The enclosing run's budget bounds. `None` fields mean the run
    /// imposes no bound on that axis — the manifest's declaration (if
    /// any) then governs, and where both are silent the axis is unbounded
    /// (never an invented default).
    pub budget: ResourceBudget,
}

impl CapsuleInvocation {
    /// An invocation with input `input` and no journal, parent, or bounds.
    pub fn new(input: Value) -> Self {
        Self {
            input,
            journal: None,
            parent: None,
            budget: ResourceBudget::default(),
        }
    }

    /// Journal into `journal`, causally under the run event `parent`.
    pub fn with_journal(mut self, journal: Journal, parent: Option<String>) -> Self {
        self.journal = Some(journal);
        self.parent = parent;
        self
    }

    /// The enclosing run's budget bounds.
    pub fn with_budget(mut self, budget: ResourceBudget) -> Self {
        self.budget = budget;
        self
    }
}

/// What a completed invocation produced: the validated output plus the
/// evidence the host collected.
#[derive(Debug)]
pub struct CapsuleOutcome {
    /// The guest's result, parsed as JSON and past the output gate.
    pub output: Value,

    /// Fuel consumed by the guest (the CPU budget's accounting).
    pub fuel_consumed: u64,

    /// Every granted capability use, in call order. Journaled as
    /// `CapsuleCall` events when a journal was attached; carried here
    /// either way.
    pub uses: Vec<CapsuleUse>,

    /// Every scoped denial during the invocation. Structural denials
    /// cannot appear here — they refuse the invocation before it starts.
    pub denials: Vec<CapsuleDenial>,
}

/// The shared interior of a [`CapsuleHost`]: the compiled component plus
/// the manifest it was admitted under.
struct HostInner {
    engine: Engine,
    component: Component,
    manifest: CapsuleManifest,
    capsule_id: CapsuleId,
    connector: Option<Arc<dyn NetworkConnector>>,
    clock: Arc<dyn Fn() -> u64 + Send + Sync>,
    recheck: Option<Arc<dyn GrantRecheck>>,
    /// Set once the epoch ticker starts; the ticker holds this flag and
    /// exits when it clears (host dropped), so hosts do not leak threads.
    ticker_alive: Arc<AtomicBool>,
    ticker_started: AtomicBool,
}

impl Drop for HostInner {
    fn drop(&mut self) {
        self.ticker_alive.store(false, Ordering::Relaxed);
    }
}

/// A WASM Component Model host enforcing one capsule manifest.
///
/// Cheap to clone (the engine and compiled component are `Arc`-backed);
/// the component is compiled once at admission and instantiation is per
/// invocation.
#[derive(Clone)]
pub struct CapsuleHost {
    inner: Arc<HostInner>,
}

impl std::fmt::Debug for CapsuleHost {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("CapsuleHost")
            .field("capsule", &self.inner.manifest.identity.name)
            .field("capsule_id", &self.inner.capsule_id)
            .finish()
    }
}

impl CapsuleHost {
    /// Admit a capsule: validate the manifest, verify the build digest
    /// against the artifact bytes, compile the component.
    ///
    /// Admission is where integrity is decided. A manifest naming bytes it
    /// was not built from does not load (the digest is recomputed, not
    /// trusted); a manifest failing [`CapsuleManifest::validate`] does not
    /// compile. What passes here can be instantiated without further
    /// interpretation.
    pub fn from_bytes(manifest: CapsuleManifest, bytes: impl AsRef<[u8]>) -> Result<Self> {
        let bytes = bytes.as_ref();
        let name = manifest.identity.name.clone();
        let host_err = |msg: String| RustyError::Node(format!("capsule host '{name}': {msg}"));

        manifest.validate()?;
        let actual = sha256_hex(bytes);
        if actual != manifest.build_digest {
            return Err(host_err(format!(
                "build digest mismatch: the manifest names {} but the artifact hashes to \
                 {actual} — a manifest is admitted against the bytes it was built from",
                manifest.build_digest
            )));
        }

        let mut config = Config::new();
        config.consume_fuel(true);
        config.epoch_interruption(true);
        let engine =
            Engine::new(&config).map_err(|e| host_err(format!("failed to create engine: {e}")))?;
        let component = Component::new(&engine, bytes)
            .map_err(|e| host_err(format!("failed to compile component: {e:#}")))?;

        // The wave-1 world exports exactly `run`; refuse components that
        // do not provide it, at admission rather than at invocation (the
        // `wasm_node` ABI check's discipline).
        let exports_run = matches!(
            component
                .component_type()
                .get_export(&engine, "run")
                .map(|export| export.ty),
            Some(wasmtime::component::types::ComponentItem::ComponentFunc(_))
        );
        if !exports_run {
            return Err(host_err(
                "the component does not export `run` — the declared world requires \
                 `run: func(input: string) -> result<string, string>`"
                    .into(),
            ));
        }

        let capsule_id = manifest.capsule_id()?;
        Ok(Self {
            inner: Arc::new(HostInner {
                engine,
                component,
                manifest,
                capsule_id,
                connector: None,
                clock: Arc::new(default_clock),
                recheck: None,
                ticker_alive: Arc::new(AtomicBool::new(true)),
                ticker_started: AtomicBool::new(false),
            }),
        })
    }

    /// Plug the egress seam (required before invoking a capsule whose
    /// manifest grants `network`; see [`NetworkConnector`]).
    pub fn with_connector(mut self, connector: Arc<dyn NetworkConnector>) -> Self {
        Arc::get_mut(&mut self.inner)
            .expect("with_connector before the host is shared")
            .connector = Some(connector);
        self
    }

    /// Plug the revocation seam (R0.9 wave 2; see [`GrantRecheck`]):
    /// every granted capability use is re-authorized against the live
    /// policy before it executes, and a revoked grant refuses at its
    /// next use with the denial journaled against the new policy
    /// version. Without one the host behaves exactly as wave 1.
    pub fn with_grant_recheck(mut self, recheck: Arc<dyn GrantRecheck>) -> Self {
        Arc::get_mut(&mut self.inner)
            .expect("with_grant_recheck before the host is shared")
            .recheck = Some(recheck);
        self
    }

    /// Override the clock the `clock` import reads (milliseconds). The
    /// default is the system wall clock; tests and seeded runs pin their
    /// own — the clock is a determinism boundary, which is why it is a
    /// grant and not ambient authority.
    pub fn with_clock(mut self, clock: impl Fn() -> u64 + Send + Sync + 'static) -> Self {
        Arc::get_mut(&mut self.inner)
            .expect("with_clock before the host is shared")
            .clock = Arc::new(clock);
        self
    }

    /// The manifest this host was admitted under.
    pub fn manifest(&self) -> &CapsuleManifest {
        &self.inner.manifest
    }

    /// The admitted manifest's content address.
    pub fn capsule_id(&self) -> &CapsuleId {
        &self.inner.capsule_id
    }

    /// Run one invocation. The guest call is synchronous and CPU-bound; it
    /// runs on a blocking thread, the `wasm_node` discipline.
    pub async fn invoke(&self, invocation: CapsuleInvocation) -> Result<CapsuleOutcome> {
        let inner = Arc::clone(&self.inner);
        let name = inner.manifest.identity.name.clone();
        tokio::task::spawn_blocking(move || run_invocation(&inner, invocation))
            .await
            .map_err(|e| {
                RustyError::Node(format!("capsule host '{name}': task join failed: {e}"))
            })?
    }
}

/// The system wall clock, in milliseconds — the default clock import.
fn default_clock() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|d| d.as_millis() as u64)
        .unwrap_or(0)
}

/// One invocation, start to finish: structural gate, resource setup,
/// guest call, output gate, invocation evidence.
fn run_invocation(inner: &HostInner, invocation: CapsuleInvocation) -> Result<CapsuleOutcome> {
    let manifest = &inner.manifest;
    let name = &manifest.identity.name;
    let host_err = |msg: String| RustyError::Node(format!("capsule host '{name}': {msg}"));
    let budget = manifest.budget.clamp(&invocation.budget);

    let mut journal = invocation.journal;
    let mut parent = invocation.parent;

    // The structural gate. Walk the component's imports before anything is
    // linked: an import whose capability class carries no grant is never
    // linked — the invocation is refused here, and the denial is journaled
    // with an empty-scope absent grant (no grant at any scope existed).
    // An import outside every supported world fails closed the same way.
    for (import, _extern) in inner.component.component_type().imports(&inner.engine) {
        match capability_for_import(import) {
            Some(kind) if any_grant_of_kind(&manifest.capabilities, kind) => {}
            Some(kind) => {
                let denial = CapsuleDenial::unscoped(
                    inner.capsule_id.clone(),
                    kind,
                    format!(
                        "the component imports `{import}` but the manifest grants no \
                         `{kind:?}` capability — the import does not exist for this guest"
                    ),
                );
                journal_capability_event(
                    &mut journal,
                    &mut parent,
                    RunEventKind::CapsuleDenied,
                    Effect::Pure,
                    &denial,
                    EventStatus::Ok,
                );
                return Err(host_err(format!("structural denial: {}", denial.detail)));
            }
            None => {
                return Err(host_err(format!(
                    "the component imports `{import}`, which no supported world declares — \
                     fail closed rather than guess"
                )));
            }
        }
    }

    let grants: Vec<CapabilityGrant> = manifest.capabilities.iter().cloned().collect();
    let wants_network = any_grant_of_kind(&grants, CapabilityKind::Network);
    if wants_network && inner.connector.is_none() {
        return Err(host_err(
            "the manifest grants `network` but the host was built without a connector — \
             a granted egress path is explicit, never ambient"
                .into(),
        ));
    }

    // Resource setup: fuel is the CPU budget, the epoch deadline is the
    // wall-time budget in ticks, the limiter is the memory budget.
    let mut store = Store::new(
        &inner.engine,
        StoreData {
            limiter: StoreLimits {
                max_memory_bytes: budget
                    .max_memory_bytes
                    .map(|bytes| bytes.try_into().unwrap_or(usize::MAX)),
            },
            grants: grants.clone(),
            capsule_id: inner.capsule_id.clone(),
            connector: inner.connector.clone(),
            clock: Arc::clone(&inner.clock),
            recheck: inner.recheck.clone(),
            journal: journal.clone(),
            parent: parent.clone(),
            uses: Vec::new(),
            denials: Vec::new(),
        },
    );
    store.limiter(|s| &mut s.limiter);
    let fuel_set = budget.fuel.unwrap_or(u64::MAX);
    store.set_fuel(fuel_set).map_err(|e| {
        host_err(format!(
            "failed to set fuel (engine needs consume_fuel): {e}"
        ))
    })?;
    let deadline_ticks = match budget.wall_time_ms {
        Some(ms) => {
            ensure_ticker(inner);
            (ms / EPOCH_TICK_MS).max(1)
        }
        None => u64::MAX,
    };
    store.set_epoch_deadline(deadline_ticks);

    // Link exactly the imports the granted capabilities name.
    let mut linker = Linker::new(&inner.engine);
    if wants_network {
        linker
            .instance(NET_INSTANCE)
            .map_err(|e| host_err(format!("failed to define `{NET_INSTANCE}`: {e}")))?
            .func_wrap(
                "fetch",
                |mut ctx: wasmtime::StoreContextMut<'_, StoreData>,
                 (protocol, host, method, path, body): (
                    String,
                    String,
                    String,
                    String,
                    Option<String>,
                )| {
                    Ok((fetch_impl(&mut ctx, protocol, host, method, path, body),))
                },
            )
            .map_err(|e| host_err(format!("failed to link `fetch`: {e}")))?;
    }
    if any_grant_of_kind(&grants, CapabilityKind::Clock) {
        linker
            .instance(CLOCK_INSTANCE)
            .map_err(|e| host_err(format!("failed to define `{CLOCK_INSTANCE}`: {e}")))?
            .func_wrap(
                "now-millis",
                |mut ctx: wasmtime::StoreContextMut<'_, StoreData>,
                 (): ()|
                 -> std::result::Result<(u64,), wasmtime::Error> {
                    Ok((now_millis_impl(&mut ctx).map_err(wasmtime::Error::msg)?,))
                },
            )
            .map_err(|e| host_err(format!("failed to link `now-millis`: {e}")))?;
    }

    let input = serde_json::to_string(&invocation.input)?;
    let started = Instant::now();
    let invocation_effect = manifest
        .effects
        .iter()
        .max()
        .copied()
        .unwrap_or(Effect::Pure);

    let outcome = (|| -> std::result::Result<(Value, u64), String> {
        let instance = linker
            .instantiate(&mut store, &inner.component)
            .map_err(|e| format!("instantiation failed: {e}"))?;
        let run = instance
            .get_typed_func::<(String,), (std::result::Result<String, String>,)>(&mut store, "run")
            .map_err(|e| {
                format!(
                    "bad `run` export (the world declares `run: func(input: string) -> \
                     result<string, string>`): {e}"
                )
            })?;
        let (result,) = run
            .call(&mut store, (input,))
            .map_err(|e| format!("guest run trapped: {e}"))?;
        let fuel_consumed = fuel_set.saturating_sub(store.get_fuel().unwrap_or(0));
        let output =
            result.map_err(|guest_err| format!("the guest returned an error: {guest_err}"))?;

        // The output gate: size first (the payload is untrusted), then
        // well-formed JSON. Schema validation is contract-pinned, not yet
        // enforced (module docs).
        if let Some(cap) = budget.max_output_bytes {
            if output.len() as u64 > cap {
                return Err(format!(
                    "guest output is {} bytes, over the {}-byte max_output_bytes budget",
                    output.len(),
                    cap
                ));
            }
        }
        let parsed: Value = serde_json::from_str(&output)
            .map_err(|e| format!("guest output is not valid JSON: {e}"))?;
        Ok((parsed, fuel_consumed))
    })();

    // Read the fuel accounting before consuming the store — the error
    // path's breach attribution needs it.
    let remaining_fuel = store.get_fuel().ok();
    let data = store.into_data();
    // The invocation event: a capsule invocation is a WASM guest call, so
    // it journals under the shipped `WasmCall` kind with the capsule id in
    // the payload — capability uses and denials chain alongside it from
    // the same parent.
    match outcome {
        Ok((output, fuel_consumed)) => {
            if let Some(journal) = &journal {
                let mut draft = EventDraft::new(RunEventKind::WasmCall, invocation_effect)
                    .input(json!({
                        "capsule_id": inner.capsule_id,
                        "input": invocation.input,
                    }))
                    .output(json!({
                        "capsule_id": inner.capsule_id,
                        "output": output,
                        "fuel_consumed": fuel_consumed,
                    }));
                if let Some(parent) = &parent {
                    draft = draft.parent(parent.clone());
                }
                journal.record(draft);
            }
            Ok(CapsuleOutcome {
                output,
                fuel_consumed,
                uses: data.uses,
                denials: data.denials,
            })
        }
        Err(message) => {
            // Budget attribution, stated only when confident: fuel reads
            // the store's own accounting; wall time reads the clock.
            // Anything else is reported unattributed rather than guessed.
            let breach = if budget.fuel.is_some() && remaining_fuel == Some(0) {
                Some("fuel")
            } else if budget
                .wall_time_ms
                .is_some_and(|ms| started.elapsed() >= Duration::from_millis(ms))
            {
                Some("wall_time")
            } else {
                None
            };
            if let Some(journal) = &journal {
                let mut output = json!({
                    "capsule_id": inner.capsule_id,
                    "error": message,
                });
                if let Some(breach) = breach {
                    output["budget_breach"] = json!(breach);
                }
                let mut draft = EventDraft::new(RunEventKind::WasmCall, invocation_effect)
                    .input(json!({
                        "capsule_id": inner.capsule_id,
                        "input": invocation.input,
                    }))
                    .output(output)
                    .status(EventStatus::Error);
                if let Some(parent) = &parent {
                    draft = draft.parent(parent.clone());
                }
                journal.record(draft);
            }
            Err(host_err(message))
        }
    }
}

/// Start the epoch ticker exactly once per host: a thread advancing the
/// engine's epoch every `EPOCH_TICK_MS` until the host drops. Store
/// deadlines are set in ticks, so every wall-budgeted invocation on this
/// engine preempts within one tick of its own deadline — no cross-talk
/// between concurrent invocations (each store's deadline is an absolute
/// point on the shared counter, not a peer's timer).
fn ensure_ticker(inner: &HostInner) {
    if inner
        .ticker_started
        .compare_exchange(false, true, Ordering::Relaxed, Ordering::Relaxed)
        .is_err()
    {
        return;
    }
    let engine = inner.engine.clone();
    let alive = Arc::downgrade(&inner.ticker_alive);
    std::thread::spawn(move || {
        while let Some(alive) = alive.upgrade() {
            std::thread::sleep(Duration::from_millis(EPOCH_TICK_MS));
            if !alive.load(Ordering::Relaxed) {
                break;
            }
            engine.increment_epoch();
        }
    });
}

/// The `fetch` import: scope match first, connector second, evidence
/// always. Returns the guest-visible `result<string, string>` — denials
/// and connector failures are in-band errors the guest can react to, and
/// both are journaled regardless.
fn fetch_impl(
    ctx: &mut wasmtime::StoreContextMut<'_, StoreData>,
    protocol: String,
    host: String,
    method: String,
    path: String,
    body: Option<String>,
) -> std::result::Result<String, String> {
    let data = ctx.data_mut();
    if !network_grant_covers(&data.grants, &protocol, &host, &method) {
        let denial = CapsuleDenial::scoped(
            data.capsule_id.clone(),
            CapabilityGrant::Network {
                hosts: vec![host.clone()],
                protocols: vec![protocol.clone()],
                methods: vec![method.clone()],
            },
            format!(
                "fetch {method} {protocol}://{host}{path} names no granted network scope — \
                 the absent grant is `network` covering {method} {protocol}://{host}"
            ),
        );
        data.denials.push(denial.clone());
        let detail = denial.detail.clone();
        if let Ok(output) = serde_json::to_value(&denial) {
            data.journal_event(
                RunEventKind::CapsuleDenied,
                Effect::Pure,
                output,
                EventStatus::Ok,
            );
        }
        return Err(format!("denied: {detail}"));
    }

    // The revocation seam (wave 2): the scope match proves the grant was
    // admitted; the recheck proves it still is. A revoked grant refuses
    // here, journaled against the live policy version, before any socket
    // opens.
    data.policy_recheck(CapabilityGrant::Network {
        hosts: vec![host.clone()],
        protocols: vec![protocol.clone()],
        methods: vec![method.clone()],
    })?;

    let request = FetchRequest {
        protocol: protocol.clone(),
        host: host.clone(),
        method: method.clone(),
        path: path.clone(),
        body,
    };
    let connector = data
        .connector
        .clone()
        .expect("the structural gate refuses network grants without a connector");
    let outcome = connector.fetch(&request);
    let effect = if is_read_only_method(&method) {
        Effect::ReadOnly
    } else {
        Effect::NonIdempotent
    };
    let (response, status, guest_result) = match &outcome {
        Ok(resp) => (
            json!({ "status": resp.status, "body": resp.body }),
            EventStatus::Ok,
            Ok(resp.body.clone()),
        ),
        Err(message) => (
            json!({ "error": message }),
            EventStatus::Error,
            Err(format!("connector failed: {message}")),
        ),
    };
    let data = ctx.data_mut();
    let use_record = CapsuleUse {
        capsule_id: data.capsule_id.clone(),
        capability: CapabilityKind::Network,
        operation: "fetch".into(),
        request: json!({
            "protocol": protocol,
            "host": host,
            "method": method,
            "path": path,
        }),
        response,
    };
    data.uses.push(use_record.clone());
    if let Ok(output) = serde_json::to_value(&use_record) {
        data.journal_event(RunEventKind::CapsuleCall, effect, output, status);
    }
    guest_result
}

/// The `now-millis` import: read the host clock, journal the use. The
/// revocation seam runs first (wave 2): a clock grant revoked since
/// admission traps the call — the import's guest-visible signature has
/// no error channel, so a denial arrives as a trap (journaled like
/// every other) rather than a silent wrong answer.
fn now_millis_impl(
    ctx: &mut wasmtime::StoreContextMut<'_, StoreData>,
) -> std::result::Result<u64, String> {
    let data = ctx.data_mut();
    data.policy_recheck(CapabilityGrant::Clock)?;
    let millis = (data.clock)();
    let use_record = CapsuleUse {
        capsule_id: data.capsule_id.clone(),
        capability: CapabilityKind::Clock,
        operation: "now_millis".into(),
        request: json!({}),
        response: json!({ "millis": millis }),
    };
    data.uses.push(use_record.clone());
    if let Ok(output) = serde_json::to_value(&use_record) {
        data.journal_event(
            RunEventKind::CapsuleCall,
            Effect::ReadOnly,
            output,
            EventStatus::Ok,
        );
    }
    Ok(millis)
}

/// Journal one capability event outside a store (the structural gate runs
/// before any store exists). Chains causally from `parent`, then advances
/// it — the same cursor [`StoreData::journal_event`] keeps.
fn journal_capability_event<T: Serialize>(
    journal: &mut Option<Journal>,
    parent: &mut Option<String>,
    kind: RunEventKind,
    effect: Effect,
    payload: &T,
    status: EventStatus,
) {
    let Some(journal) = journal.as_ref() else {
        return;
    };
    let Ok(output) = serde_json::to_value(payload) else {
        return;
    };
    let mut draft = EventDraft::new(kind, effect).output(output).status(status);
    if let Some(parent) = &parent {
        draft = draft.parent(parent.clone());
    }
    *parent = Some(journal.record(draft));
}