A centralized manager of vats and distributed objects. See the Kernel class.
A unit of compute managed by the kernel. See the VatHandle and VatSupervisor classes.
Persistent key-value storage for a vat's durable state. Baggage survives vat
restarts (resuscitation) and is the primary mechanism for vat state persistence. Baggage
is provided as the third argument to buildRootObject.
The initialization method called on the bootstrap vat's root object when a subcluster is first launched. The bootstrap method receives references to other vats and kernel services and is called exactly once — it is not called again after a vat restart.
See subcluster.
A remotable object created with makeDefaultExo() from @metamask/kernel-utils/exo. Exos
are the standard way to create objects that can be passed between vats, stored in
baggage, and invoked via E(). Do not use Far() from @endo/far.
A persistent object residing in a vat and asynchronously accessible to other vats. See the implementation in the kernel's storage methods.
An object registered with the kernel that vats can invoke via E().
Kernel services run in the kernel's own context (not in a vat) and are registered using
kernel.registerKernelServiceObject(). Because service implementations do not participate
in the kernel's reference management, they cannot return exos. Services marked
systemOnly can only be accessed by system subclusters. See the
KernelServiceManager.
A kernel-space component that manages the lifecycle and communication of a vat. The VatSupervisor handles message delivery, syscalls, and vat initialization.
A framework for managing object lifecycles within vats. Liveslots provides the runtime environment for vat code and handles object persistence, distributed promise management, and syscall coordination.
A single execution cycle in the kernel's run queue. Each crank processes one item from the run queue, delivering a single message or notification to a vat. The "message or notification" is whatever item is taken of the run queue. Cranks can be aborted and rolled back if errors occur. See the KernelQueue for the run loop implementation.
A system call made by a vat to request kernel services. Syscalls include operations like sending messages, resolving kernel promises, and accessing persistent storage. See VatSyscall and the syscall service.
The process of sending a message or notification to a vat in a crank. Deliveries can be of type 'message', 'notify', 'dropExports', 'retireExports', 'retireImports', or 'bringOutYourDead'. See the kernel router (KernelRouter) for delivery logic.
The process of serializing and deserializing data for transmission between vats.
The kernel uses marshaling to convert object references and data structures into a format
suitable for cross-vat communication. See the kernel marshal
service for kser and kunser
functions.
A persistent record in the kernel store that tracks the state of a promise across vat
boundaries. A kernel promise has a state (unresolved, fulfilled, or rejected), a
decider, a list of subscribers, and (once settled) a value. Kernel promises
survive vat restarts and crank rollbacks.
Kernel promises are distinct from JavaScript promises. Vat code works with JS promises
and E() calls; liveslots translates between the vat's JS promises and
kernel promise IDs (krefs) via syscalls. Kernel-space code (e.g.,
enqueueMessage) may create both a kernel
promise (for routing) and a JS promise (for the caller to await), bridged by a
subscription callback. See the
promise store methods.
The endpoint authorized to settle (fulfill or reject) a kernel promise.
Analogous to a function call: when vat A sends E(obj).foo() to vat B, vat A is the
caller waiting for a result, and vat B is the callee that computes it. B becomes the
decider of the result's kernel promise at delivery time, just as a callee
determines the return value of a function call. Only the decider can resolve the kernel
promise — attempts by other endpoints are rejected. After crank rollback, the
decider reverts to its pre-delivery value, which matters for error handling (e.g.,
rejecting the kernel promise of a message sent to a terminated vat). See
setPromiseDecider and the
authorization check in
resolvePromises.
The process of fulfilling or rejecting a kernel promise. Promise resolutions are delivered as notifications to vats and can trigger cascading resolutions of dependent kernel promises. See the promise store methods for implementation details.
The process of identifying and cleaning up unreachable objects. The kernel performs GC by tracking reference counts and delivering appropriate notifications to vats. Important: the garbage collection systems of the kernel, liveslots, and javascript are all mutually independent. See the GC methods and GC service for implementation details.
The process of invalidating an object reference, preventing further access to the object. Revoked objects return errors when accessed. See the revocation methods for implementation.
A communication pathway between different components, such as between a vat and the kernel, or between different clusters. Channels use streams for message passing. See the BaseDuplexStream for the core channel implementation.
A remote asynchronous iterator that provides bidirectional communication between
components. Streams implement the Reader interface from @endo/stream and can be used
for message passing between vats, kernel components, and external systems. See the
BaseDuplexStream for bidirectional
streams.
A logically related group of vats, intended to be operated together. Defined by a
ClusterConfig. When a subcluster is launched, all its vats start and the
bootstrap vat receives references to the other vats. See the ClusterConfig
type in packages/ocap-kernel/src/types.ts.
A subcluster declared at kernel initialization that can access
privileged (systemOnly) kernel services. System subclusters persist
across kernel restarts and are identified by a unique name. See the
SubclusterManager.
The kernel's main execution queue that processes messages, notifications, and garbage collection actions. Each crank processes one item from this queue. See the KernelQueue class and queue methods for implementation details.
The component responsible for routing messages to the correct vat based on target references and kernel promise states. The router handles delivery logic. See the KernelRouter for routing logic.
A clist (short for "capability list") is a bidirectional mapping between short, channel-specific identifiers and actual object references. The clist is unique to a channel-runtime pair, and translates between the javascript runtime which holds the object references and the channel which communicates about them.
An ERef (short for "endpoint reference") is a generic term for a ref which is either a vref or an rref.
A KRef (short for "kernel reference") designates an Object within the scope of the Kernel itself. It is used in the translation of References between one Vat and another. A KRef is generated and assigned by the Kernel whenever an Object reference is imported into or exported from a Vat for the first time.
An RRef (short for "remote reference") designates an object within the scope of an established point-to-point communications Channel between two Clusters. An RRef does not survive the Channel it is associated with. An RRef is generated when the Kernel for one Cluster exports an Object Reference into the Channel connecting it to another Cluster's Kernel.
A VRef (short for "vat reference") designates an Object within the scope of the Objects known to a particular Vat. It is used across the Kernel/Vat boundary in the marshaling of messages delivered into or sent by that Vat. A VRef is generated and assigned by the Kernel when importing an Object Reference into a Vat for the first time and by the Vat when exporting an Object Reference from it for the first time.