sim_lib_machine/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(missing_docs)]
3//! Policy contracts for neutral, bounded decoded-instruction machines.
4//!
5//! Consumers supply every semantic choice through the traits below; the execution
6//! engine only owns bounded, iterative control transfer.
7
8mod admission;
9mod code;
10mod driver;
11mod frame;
12mod managed;
13mod shuffle;
14mod slots;
15mod stack;
16
17pub use admission::{
18    AdmissionError, AdmissionLimits, AdmissionPolicy, MachineDescription, MachinePermit,
19};
20pub use driver::{
21    ContinuationEvidence, DriveError, DriveOutcome, DriveResult, Driver, InstructionDriverPolicy,
22    LocatedFault, MachineAbrupt, MachineCheckpoint, MachineFrame, MachineUnwind, PolicyStep,
23    SafepointDriveError, StepKind, StepOutcome, WorkReceipt,
24};
25pub use frame::{
26    CallTransfer, Frame, FrameStack, FrameStackError, ReturnTransfer, Transfer, TransferError,
27};
28pub use managed::{ManagedRootSource, RootScanError, RootSnapshot};
29pub use shuffle::{ShuffleError, ShufflePlan};
30pub use slots::{SlotError, SlotFile};
31pub use stack::{StackError, UnitStack};
32
33/// Supplies stable instruction identity and the consumer's decoded form.
34///
35/// For example, a WebAssembly decoder or a BEAM loader can supply this policy.
36pub trait InstructionPolicy {
37    /// One decoded instruction.
38    type Instruction;
39    /// Stable identity used by branches, coverage, and receipts.
40    type InstructionId: Copy + Eq + Ord;
41
42    /// Returns the stable identity of `instruction`.
43    fn instruction_id(instruction: &Self::Instruction) -> Self::InstructionId;
44}
45
46/// Accounts values in consumer-defined logical storage units.
47///
48/// For example, a WebAssembly value policy or a Forth cell policy can supply it.
49pub trait ValueWidthPolicy {
50    /// A machine value whose representation remains consumer-owned.
51    type Value;
52
53    /// Returns the nonzero logical width charged for `value`.
54    fn width(value: &Self::Value) -> usize;
55}
56
57/// Classifies the effects an instruction may request from its driver.
58///
59/// For example, a WebAssembly embedder or an Erlang emulator can supply it.
60pub trait EffectPolicy<I> {
61    /// Consumer-defined effect description.
62    type Effect;
63
64    /// Describes the effect of `instruction` without performing it.
65    fn classify(instruction: &I) -> Self::Effect;
66}
67
68/// Describes bounded guest-frame metadata without owning frame storage.
69///
70/// For example, a WebAssembly engine or a PostScript interpreter can supply it.
71pub trait FramePolicy {
72    /// Consumer-defined frame metadata.
73    type Frame;
74    /// Stable callable identity.
75    type CallableId: Copy + Eq + Ord;
76
77    /// Returns the callable associated with `frame`.
78    fn callable(frame: &Self::Frame) -> Self::CallableId;
79}
80
81/// Selects protected regions and consumer-defined abrupt outcomes.
82///
83/// For example, a WebAssembly trap policy or a BEAM exit policy can supply it.
84pub trait HandlerPolicy<I> {
85    /// Consumer-defined handler identity.
86    type HandlerId: Copy + Eq + Ord;
87    /// Consumer-defined abrupt outcome.
88    type Abrupt;
89
90    /// Finds the handler, if any, for an instruction and abrupt outcome.
91    fn handler_for(instruction: I, abrupt: &Self::Abrupt) -> Option<Self::HandlerId>;
92}
93
94/// Projects live machine state into the managed-root owner's identity type.
95///
96/// For example, a WebAssembly reference policy or a Scheme heap can supply it.
97pub trait RootPolicy<S> {
98    /// Root identity understood by the consumer's managed arena.
99    type Root;
100
101    /// Visits every live root in deterministic order.
102    fn visit_roots(state: &S, visit: impl FnMut(&Self::Root));
103}
104
105/// Declares semantic polling locations in prepared code.
106///
107/// For example, a WebAssembly loop policy or a Lua interpreter can supply it.
108pub trait SafepointPolicy<I> {
109    /// Returns whether the instruction is a semantic safepoint.
110    fn is_safepoint(instruction: &I) -> bool;
111}
112
113/// Creates deterministic evidence for bounded machine work.
114///
115/// For example, a WebAssembly audit profile or a Forth tracer can supply it.
116pub trait ReceiptPolicy<E> {
117    /// Consumer-defined receipt.
118    type Receipt;
119
120    /// Records exact work from ordered execution evidence.
121    fn receipt(evidence: E) -> Self::Receipt;
122}
123pub use code::{
124    BranchTarget, CodeCursor, CodeError, CoverageMetadata, LocatedCode, LocatedInstruction,
125    ProtectedRegion, RegionSpec, SourceLocation, TargetLocation,
126};
sim_lib_machine/lib.rs

sim_lib_machine/
lib.rs
