lib/machine/src/world/root.zig

daab053ee43316e1809a84551d573ddd1e5bf3d2

  1 //! Machines that talk to each other advance separately, so stopping them all at
  2 //! one instant, storing that instant, and bringing it back later takes a definition
  3 //! of what one instant is, and this namespace supplies it. The namespace folds the
  4 //! state of every running machine, every machine's saved state, and the order of
  5 //! everything that passed between the machines into one identity, and a caller seals,
  6 //! restores, and replays that identity. The execution cycle runs seal, then restore,
  7 //! then activate, then advance, and seal again.
  8 //!
  9 //! A step of the machines can fail its checks before it changes anything, or after
 10 //! its changes have begun. Running machines together adds places where two runs
 11 //! of the same program could differ, beyond the places each machine has alone.
 12 //!
 13 //! The order of everything that passed between the machines lives in one record
 14 //! of every admitted input, packet, settlement, and fault decision across them,
 15 //! the *ledger*. The namespace runs one deterministic execution across up to four
 16 //! machines, together with the ledger (a *world*). The instant is a complete restorable
 17 //! boundary holding one digest of the whole world state together with the checkpoint
 18 //! root of each machine, and carrying no live state (a *cut*).
 19 //!
 20 //! A step is an input delivered to a machine together with the guest work that settles
 21 //! it (a *turn*). Each turn runs under the world, generation, and token authorized
 22 //! for it (its *activation fence*). Every mutation works on a copy of the ledger
 23 //! (a *candidate ledger*), verifies the result on that copy, then commits the record
 24 //! and the world's new position in its history together, once every verification
 25 //! passes. A turn that fails before changing anything leaves the world usable (*rejected*).
 26 //! A turn that fails after mutation began tears down every running machine and ends
 27 //! the world (*invalidated*).
 28 //!
 29 //! The namespace answers for exactly three named places where two runs of the same
 30 //! program could differ (each a *divergence source*): the activation fence, turn
 31 //! selection, and the replay source.
 32 //!
 33 //! - *node*: one participant in a world, named by a 16-byte identity.
 34 //! - *world root*: one world state folded into a single digest, covering the contract
 35 //!   that binds every node, the ledger root, and the node count.
 36 //! - *moment*: a position in one world's history, pairing the world root the world
 37 //!   grew from with the ledger root it has reached since.
 38 //! - *instance*: one live K0 execution that borrows caller-owned storage and guest-memory
 39 //!   backing until `deinit`.
 40 //! - *checkpoint*: captured machine execution state carrying an identity that any
 41 //!   holder of the bytes can recompute.
 42 
 43 const fault_owner = @import("fault.zig");
 44 const live_owner = @import("live.zig");
 45 const moment_owner = @import("moment.zig");
 46 const owner = @import("owner.zig");
 47 const prefix_owner = @import("prefix.zig");
 48 const profile = @import("../profile/root.zig");
 49 const replay_owner = @import("replay.zig");
 50 const restore_owner = @import("restore.zig");
 51 const types = @import("types.zig");
 52 
 53 pub const manifest = @import("manifest/root.zig");
 54 
 55 pub const Binding = types.Binding;
 56 pub const Cut = types.Cut;
 57 pub const Dialect = types.Dialect;
 58 pub const Error = owner.Error;
 59 pub const FaultApplied = fault_owner.Applied;
 60 pub const FaultError = fault_owner.Error;
 61 pub const FaultRejection = fault_owner.Rejection;
 62 pub const FaultResult = fault_owner.Result;
 63 pub const LiveActivated = live_owner.Activated;
 64 pub const LiveActivateResult = live_owner.ActivateResult;
 65 pub const LiveAdvanced = live_owner.Advanced;
 66 pub const LiveError = live_owner.Error;
 67 pub const LiveRejection = live_owner.Rejection;
 68 pub const LiveTurnResult = live_owner.TurnResult;
 69 pub const Moment = moment_owner.Moment;
 70 pub const MomentDialect = moment_owner.Dialect;
 71 pub const MomentError = moment_owner.Error;
 72 pub const Node = types.Node;
 73 pub const PrefixError = prefix_owner.Error;
 74 pub const PrefixFault = prefix_owner.Fault;
 75 pub const PrefixInput = prefix_owner.Input;
 76 pub const PrefixProgress = prefix_owner.Progress;
 77 pub const PrefixResult = prefix_owner.Result;
 78 pub const PrefixStep = prefix_owner.Step;
 79 pub const PrefixStopped = prefix_owner.Stopped;
 80 pub const PrefixTurn = prefix_owner.Turn;
 81 pub const Root = types.Root;
 82 pub const RestoreBinding = restore_owner.Binding;
 83 pub const RestoreError = restore_owner.Error;
 84 pub const RestoreMode = restore_owner.Mode;
 85 pub const RestoreRejection = restore_owner.Rejection;
 86 pub const RestoreResult = restore_owner.Result;
 87 pub const RestoreTarget = restore_owner.Target;
 88 pub const RestoreUnavailable = restore_owner.Unavailable;
 89 pub const Restored = restore_owner.Restored;
 90 pub const RestoredNode = restore_owner.Node;
 91 pub const ReplayAdvanced = replay_owner.Advanced;
 92 pub const ReplayError = replay_owner.Error;
 93 pub const ReplayFrame = replay_owner.Frame;
 94 pub const ReplayInput = replay_owner.Input;
 95 pub const ReplayRejection = replay_owner.Rejection;
 96 pub const ReplayResult = replay_owner.Result;
 97 pub const Source = types.Source;
 98 pub const node_limit = types.node_limit;
 99 pub const prefix_step_limit = prefix_owner.step_limit;
100 pub const applyFault = fault_owner.applyFault;
101 pub const activate = live_owner.activate;
102 pub const prepareMoment = moment_owner.prepare;
103 pub const replayFault = fault_owner.replayFault;
104 pub const replayPrefix = prefix_owner.replayPrefix;
105 pub const seal = owner.seal;
106 pub const restore = restore_owner.restore;
107 pub const replayTurn = replay_owner.replayTurn;
108 pub const terminal = live_owner.terminal;
109 pub const verify = owner.verify;
110 pub const verifyMoment = moment_owner.verify;
111 
112 pub const determinism_sources = [_]profile.DeterminismSource{
113     .activation_fence,
114     .turn_selection,
115     .replay_source,
116 };