tiny.machine.world

1/// The record left behind by an applied fault: the ledger transition holding its2/// record, the decision that was taken, and the moment the world reaches afterwards.3/// A caller reads this to see what the fault did to the ledger and where the world4/// now stands.5pub const Applied = struct {6    transition: fabric.Transition,7    decision: fault.Decision,8    moment: moment.Moment,9};

1/// A named failure carrying the node involved whenever the code can name one. A2/// caller reads this to learn which node the failure concerns.3pub const Rejection = struct {4    node: ?fabric.NodeId,5    failure: Error,6};

1/// The fault outcome. A world that rejected the call still holds the state it had2/// before and stays usable.3pub const Result = union(enum) {4    applied: Applied,5    rejected: Rejection,6};

1/// The activation outcome, so a caller switches on this to decide whether the world2/// can keep going. A world that rejected the call still holds the state it had before3/// and stays usable. A world marked invalid failed once mutation was already under4/// way, so its live instances were destroyed and it cannot continue.5pub const ActivateResult = union(enum) {6    activated: Activated,7    rejected: Rejection,8    invalidated: Rejection,9};

1/// What an activation yields: the node now awake and every event it emitted on the2/// way to its ready point. A caller reads this to see which node woke and what it3/// said on the way up.4pub const Activated = struct {5    node: fabric.NodeId,6    events: instance.EventBatch,7};

1/// What a settled turn yields: two ledger transitions record the admission and the2/// settlement, a moment marks where the world stands once both are in, the guest3/// events travel with them, and a quiescence receipt shows that the guest came to4/// its cooperative stop. A caller reads this to see everything one settled turn5/// produced.6pub const Advanced = struct {7    admission: fabric.Transition,8    settlement: fabric.Transition,9    moment: moment.Moment,10    events: instance.EventBatch,11    receipt: instance.QuiescenceReceipt,12};

1/// A named failure, carrying the node involved whenever the code can name one.2pub const Rejection = struct {3    node: ?fabric.NodeId,4    failure: Error,5};

1/// The outcome of a turn obeys the contract `ActivateResult` obeys, so a caller2/// switches on this the same way it switches on an activation outcome. Rejected3/// worlds continue, and invalidated worlds are gone.4pub const TurnResult = union(enum) {5    advanced: Advanced,6    rejected: Rejection,7    invalidated: Rejection,8};

1/// The encoding version for moments. A reader checks this version before trusting2/// a stored moment, and rejects a moment written under a version it does not speak.3/// One version exists today: `stable_world_v1`.4pub const Dialect = enum(u16) {5    stable_world_v1 = 1,6};

1pub const Error = error{2    ContractMismatch,3    FabricFrontierRegression,4    InvalidFabricRoot,5    InvalidWorldRoot,6    MomentMismatch,7};

1/// A place in one world's history, fixed by the origin cut it started from together2/// with the ledger root it stands at now. A caller compares moments to know whether3/// two worlds stand at the same place in the same history. Two moments match when4/// both the origin and the position match, and the digest covers the pair, so two5/// worlds that reached the same ledger position from different origins produce different6/// moments.7pub const Moment = struct {8    digest: os.abi.Digest,9    dialect: Dialect,10    origin: types.Root,11    fabric: fabric.Root,12};

1/// A step that replays a fault, holding the recorded transition together with the2/// root and the moment the replay has to land on, so a caller builds one for every3/// recorded fault in a plan.4pub const Fault = struct {5    reader: *std.Io.Reader,6    expected_root: fabric.Root,7    expected_moment: moment.Moment,8};

1/// A plan for replaying a prefix, holding a start moment already verified, no more2/// than `step_limit` recorded steps, and the end moment it declares, so a caller3/// hands one to `replayPrefix`.4pub const Input = struct {5    start: moment.Moment,6    steps: []const Step,7    end: moment.Moment,8};

1/// The running total of a prefix replay, counting steps and turns applied, naming2/// the moment reached, and keeping each applied turn's step index and event batch,3/// so a caller reads this to see how far a replay got and what the guest said along4/// the way.5/// The event arrays are fixed at the step limit, and only the first `turn_count`6/// entries of each are populated.7pub const Progress = struct {8    step_count: u8,9    turn_count: u8,10    moment: moment.Moment,11    turn_steps: [step_limit]u8,12    turn_events: [step_limit]instance.EventBatch,1314    /// The accessor returns each applied turn's step index, kept in application15    /// order, so a caller pairs event batches with their steps.16    pub fn eventSteps(self: *const @This()) []const u8 {17        std.debug.assert(self.turn_count <= self.turn_steps.len);18        return self.turn_steps[0..self.turn_count];19    }2021    /// The accessor returns each applied turn's event batch, kept in application22    /// order, so a caller reads the guest's output for the whole plan.23    pub fn eventBatches(self: *const @This()) []const instance.EventBatch {24        std.debug.assert(self.turn_count <= self.turn_events.len);25        return self.turn_events[0..self.turn_count];26    }27};

1/// The prefix outcome, so a caller switches on this to learn whether the plan proved2/// what it claimed.3/// `reached` establishes that the replay finished on the end moment the plan declared.4/// Rejected worlds continue, and invalidated worlds are gone.5pub const Result = union(enum) {6    reached: Progress,7    rejected: Stopped,8    invalidated: Stopped,9};

1pub const Step = union(enum) {2    turn: Turn,3    fault: Fault,4};

1/// The record of a halted prefix, holding the progress reached, the step that failed,2/// the failure itself, and the node involved whenever the code can name one, so3/// a caller reads this to learn exactly where a plan stopped and why.4pub const Stopped = struct {5    progress: ?Progress,6    step: u8,7    node: ?fabric.NodeId,8    failure: Error,9};

1/// A step that replays a turn, holding the recorded input and the moment the replay2/// has to land on, so a caller builds one for every recorded turn in a plan.3pub const Turn = struct {4    replay: replay_owner.Input,5    expected_moment: moment.Moment,6};

1/// The yield of a replayed turn, namely the pair of ledger transitions, the moment2/// reached once both are in, and the guest events. A caller reads this to see what3/// the replayed turn produced.4pub const Advanced = struct {5    admission: fabric.Transition,6    settlement: fabric.Transition,7    moment: moment.Moment,8    events: instance.EventBatch,9};

1/// A recorded transition offered for replay, holding a reader over its wire bytes2/// and the ledger root the replay has to reproduce. A caller pairs each recorded3/// transition with the root it is supposed to reproduce.4pub const Frame = struct {5    reader: *std.Io.Reader,6    expected_root: fabric.Root,7};

1/// A recorded turn, holding the frame for the admission, the frame for the settlement,2/// and the activation fence the delivery was bound to. A caller assembles one of3/// these per recorded turn.4pub const Input = struct {5    admission: Frame,6    settlement: Frame,7    fence: os.abi.ActivationFence,8};

1/// A named failure, carrying the node involved whenever the code can name one. A2/// caller reads this to learn which node a failure concerns.3pub const Rejection = struct {4    node: ?fabric.NodeId,5    failure: Error,6};

1/// The outcome of a replay, which obeys the contract a live turn obeys. A caller2/// switches on this exactly as it does for a live turn. Rejected worlds continue,3/// and invalidated worlds are gone.4pub const Result = union(enum) {5    advanced: Advanced,6    rejected: Rejection,7    invalidated: Rejection,8};

1/// What one node brings to a restore: its identity, the checkpoint it restores from,2/// and its mode. A caller builds one of these per node and hands the array to `restore`.3pub const Binding = struct {4    node: fabric.NodeId,5    checkpoint: checkpoint.Source,6    mode: Mode,7};

1/// The form a node takes when it comes back. A caller sets this per node to say2/// whether that node comes back running. Live rebuilds an instance from caller storage,3/// and retained constructs no instance.4pub const Mode = union(enum) {5    live: Target,6    retained,7};

1/// A node after restore, naming itself and carrying a live instance if live was2/// the mode asked for. A caller reaches through these to drive one machine of a3/// restored world.4pub const Node = struct {5    id: fabric.NodeId,6    machine: ?instance.Instance,7};

1/// A named failure, carrying the node involved whenever the code can name one, so2/// a caller reads the value to learn which node a failure concerns.3pub const Rejection = struct {4    node: ?fabric.NodeId,5    failure: Error,6};

1/// A world rebuilt out of a cut, holding the origin root, the ledger the caller2/// supplied, the moment it stands at, and an entry for every node. Every turn owner3/// takes this value to own the live machines. Turn owners mutate a restored world4/// in place. `deinit` tears down every live instance and clears each entry.5pub const Restored = struct {6    root: types.Root,7    fabric: *fabric.Fabric,8    moment: moment.Moment,9    node_count: u8,10    nodes: [types.node_limit]Node,1112    /// Checks a stored moment against both the origin and the position the ledger13    /// holds, then hands it back. A caller reads the world's position through this,14    /// because the read verifies before it returns.15    pub fn currentMoment(self: *const @This()) moment.Error!moment.Moment {16        try moment.verify(self.moment, self.root, self.fabric.root());17        return self.moment;18    }1920    pub fn deinit(self: *@This()) void {21        for (&self.nodes) |*node| {22            if (node.machine) |*machine| machine.deinit();23            node.machine = null;24        }25    }26};

1/// The restore outcome, switched on by a caller so the caller takes ownership of2/// the live machines in exactly one arm. Ownership of the live instances passes3/// to the caller under `ready` and under no other outcome. The other two arms leave4/// nothing constructed, because construction tears down what it built before returning5/// them.6pub const Result = union(enum) {7    ready: Restored,8    unavailable: Unavailable,9    rejected: Rejection,10};

1/// What restoring one live node requires: the activation fence, the K0 execution2/// manifest, the execution profile, instance storage, and aligned guest RAM. A caller3/// fills one of these in for every node it wants running again. The caller owns4/// the storage and the RAM, and both are borrowed for the life of the instance.5pub const Target = struct {6    profile: profile.Profile,7    execution_manifest: []const u8,8    fence: os.abi.ActivationFence,9    storage: *instance.Storage,10    ram: []align(instance.ram_alignment) u8,11};

1/// A node whose backend is missing on this host, together with the reason that backend2/// gives, so a caller tells a host that lacks the backend apart from a world that3/// failed to check out.4pub const Unavailable = struct {5    node: fabric.NodeId,6    backend: instance.Unavailable,7};

1/// The binding holds what `seal` needs from one node: its identity, its profile,2/// the checkpoint it seals from, and the authority proving it live or retained.3/// A caller builds one binding per node and hands the array to `seal`.4pub const Binding = struct {5    node: fabric.NodeId,6    execution_profile: profile.Profile,7    checkpoint: checkpoint.Source,8    source: Source,9};

1/// A cut is a boundary complete enough to restore from, made of one root and the2/// checkpoint root of each node. A caller stores one cut as the boundary it can3/// come back to. A cut carries no live state. The node array is fixed at the node4/// limit, and every slot past the node count holds the padding value.5pub const Cut = struct {6    root: Root,7    nodes: [node_limit]Node,8};

1/// The encoding version names the version number a world root is written under,2/// and a reader rejects a root written under a version it does not speak. A reader3/// checks this value before trusting a stored world root. One version exists today,4/// `connected_world_v1`.5pub const Dialect = enum(u16) {6    connected_world_v1 = 1,7};

1/// A node once sealed is named by its identity and by the checkpoint root of its2/// machine. A caller reads these nodes out of a cut to know what each node was holding.3pub const Node = struct {4    id: fabric.NodeId,5    machine: checkpoint.Root,6};

1/// A world root is one world state folded into a single digest, covering the contract2/// that binds every node, the ledger root, and the node count. A caller compares3/// this digest to know whether two worlds are at the same state. The digest commits4/// the encoding version, the contract, the whole ledger root, and every node in5/// order.6pub const Root = struct {7    digest: os.abi.Digest,8    dialect: Dialect,9    machine_contract: profile.ContractFingerprint,10    fabric: fabric.Root,11    node_count: u8,12};

1/// The union names the origin of one node's sealed state. A caller sets this per2/// node to say whether a live instance stands behind the checkpoint it is sealing.3/// A live source carries the instance, whose current receipt must agree with the4/// checkpoint. A retained source carries no instance, and the ledger must already5/// mark that node unavailable.6pub const Source = union(enum) {7    live: *const instance.Instance,8    retained,9};

1/// Hashes a cut's material again and refuses the cut when the result differs from2/// the stored root. A node slot holding no node carries the empty padding value.3/// The cut's own contract must equal the contract its ledger root carries.4pub fn verify(cut: types.Cut) Error!void {5    const count = cut.root.node_count;6    if (count == 0 or count > types.node_limit) {7        return error.NodeCountMismatch;8    }9    for (cut.nodes[count..]) |node| {10        if (!std.meta.eql(node, emptyNode())) return error.CutInvalid;11    }12    const nodes = cut.nodes[0..count];13    try validateMaterial(cut.root.fabric, nodes);14    if (cut.root.dialect != .connected_world_v1 or15        !std.meta.eql(16            cut.root.machine_contract,17            cut.root.fabric.machine_contract,18        ))19    {20        return error.CutInvalid;21    }22    const expected = rootFor(cut.root.fabric, nodes);23    if (!std.meta.eql(expected, cut.root)) return error.RootMismatch;24}

1pub const Error = fabric.Error ||2    fabric.transition.Error ||3    restore.StableError ||4    source.Error ||5    FaultOwnerError;

1/// Applies one fault input to a candidate ledger, then commits that ledger and the2/// moment together. Injecting a machine crash destroys the live instance on that3/// node and marks the node unavailable. A process fault requires a provider that4/// this owner never holds, so the call rejects it. The candidate's node set must5/// match the restored world's, node for node, before it commits.6pub fn applyFault(7    restored: *restore.Restored,8    input: fabric.FaultInput,9) Result {10    validateCapabilities(restored) catch |failure|11        return reject(null, failure);12    if (std.meta.activeTag(input.effect) == .process_crash) {13        return reject(14            input.effect.process_crash.node,15            error.ProcessFaultProviderUnavailable,16        );17    }18    var candidate = restored.fabric.*;19    const faulted = candidate.applyFault(input) catch |failure|20        return reject(faultNode(input.effect), failure);21    return commit(22        restored,23        candidate,24        .{ .entry = faulted.entry, .root = faulted.root },25    );26}

1/// Reads one recorded fault transition back from its wire bytes so a caller proves2/// the recording reproduces the same ledger position, and demands that the replay3/// land on the root the record declares. The reader is checked against the world's4/// live memory before anything is read. The call accepts a fault entry alone, and5/// it rejects a recorded process crash. The call commits exactly like `applyFault`.6pub fn replayFault(7    restored: *restore.Restored,8    reader: *std.Io.Reader,9    expected_root: fabric.Root,10) Result {11    source.validate(restored, &.{reader}) catch |failure|12        return reject(null, failure);13    validateCapabilities(restored) catch |failure|14        return reject(null, failure);15    var candidate = restored.fabric.*;16    const transition = fabric.transition.replayDisjoint(17        &candidate,18        reader,19        expected_root,20    ) catch |failure| return reject(null, failure);21    const entry = switch (transition.entry.value) {22        .fault => |value| value,23        else => return reject(null, error.FaultTransitionExpected),24    };25    if (std.meta.activeTag(entry.effect) == .process_crash) {26        return reject(27            entry.effect.process_crash.node,28            error.ProcessFaultProviderUnavailable,29        );30    }31    return commit(restored, candidate, transition);32}

1pub const Error = fabric.Error ||2    instance.AcknowledgeError ||3    instance.DeliveryError ||4    instance.EventBatchError ||5    instance.EventError ||6    instance.QuiescenceReceiptError ||7    instance.ReactivateError ||8    instance.RunError ||9    moment.Error ||10    os.abi.wire.FenceError ||11    restore.StableError ||12    LiveOwnerError;

1/// Brings one restored node up and carries it as far as its ready point, so a caller2/// activates a node once after restore, before it can take turns. The fence carries3/// the authority for this activation, so a machine waiting to be reactivated takes4/// the fence as its own, and the batch of events it emits has to verify under that5/// same fence. The call demands a stable world, and the node's machine has to be6/// either booting or waiting to be reactivated. An exit other than a ready doorbell7/// invalidates the world.8pub fn activate(9    restored: *restore.Restored,10    node: fabric.NodeId,11    fence: os.abi.ActivationFence,12) ActivateResult {13    _ = restore.validateStable(restored) catch |failure|14        return activationReject(node, failure);15    os.abi.wire.validateFence(fence) catch |failure|16        return activationReject(node, failure);17    const machine = findMachine(restored, node) orelse18        return activationReject(node, error.MachineNodeUnavailable);19    switch (machine.phase()) {20        .booting => {},21        .awaiting_reactivation => machine.reactivate(fence) catch |failure|22            return activationInvalidate(restored, node, failure),23        else => return activationReject(node, error.MachinePhaseMismatch),24    }25    const exit_value = machine.run() catch |failure|26        return activationInvalidate(restored, node, failure);27    if (!std.meta.eql(28        exit_value,29        instance.Exit{ .doorbell = .{ .code = .ready } },30    )) {31        return activationInvalidate(32            restored,33            node,34            error.ActivationExitMismatch,35        );36    }37    var events: instance.EventBatch = undefined;38    machine.takeEvents(&events) catch |failure|39        return activationInvalidate(restored, node, failure);40    instance.verifyEventBatch(&events, fence) catch |failure|41        return activationInvalidate(restored, node, failure);42    return .{ .activated = .{ .node = node, .events = events } };43}

1/// Carries one connected terminal turn from end to end, so a caller feeds one node2/// input and lets the guest settle it: the call admits the bytes into a candidate3/// ledger, hands them to the node, runs the guest until it quiesces, checks the4/// events it produced against the quiescence receipt and the fence, settles the5/// ledger, and moves the moment forward. The call commits the candidate ledger once6/// every check has passed. The call requires a stable world, a valid fence, and7/// a node awaiting input. A failure before delivery rejects, and a failure from8/// delivery onward invalidates.9pub fn terminal(10    restored: *restore.Restored,11    node: fabric.NodeId,12    fence: os.abi.ActivationFence,13    bytes: []const u8,14) TurnResult {15    _ = restore.validateStable(restored) catch |failure|16        return turnReject(node, failure);17    os.abi.wire.validateFence(fence) catch |failure|18        return turnReject(node, failure);19    const machine = findMachine(restored, node) orelse20        return turnReject(node, error.MachineNodeUnavailable);21    if (machine.phase() != .awaiting_input) {22        return turnReject(node, error.MachinePhaseMismatch);23    }24    var candidate = restored.fabric.*;25    const admitted = candidate.terminal(26        node,27        machine,28        fence,29        bytes,30    ) catch |failure| return turnReject(node, failure);31    machine.deliverAdmitted(&admitted.delivery) catch |failure|32        return turnInvalidate(restored, node, failure);33    const exit_value = machine.run() catch |failure|34        return turnInvalidate(restored, node, failure);35    if (!std.meta.eql(36        exit_value,37        instance.Exit{ .doorbell = .{ .code = .quiescent } },38    )) {39        return turnInvalidate(40            restored,41            node,42            error.QuiescenceExitMismatch,43        );44    }45    var events: instance.EventBatch = undefined;46    machine.takeEvents(&events) catch |failure|47        return turnInvalidate(restored, node, failure);48    machine.acknowledge(admitted.delivery.receipt) catch |failure|49        return turnInvalidate(restored, node, failure);50    const receipt = machine.quiescenceReceipt() catch |failure|51        return turnInvalidate(restored, node, failure);52    instance.verifyEventBatchReceipt(53        &events,54        receipt,55        fence,56    ) catch |failure| return turnInvalidate(restored, node, failure);57    const settled = candidate.settle(node, receipt) catch |failure|58        return turnInvalidate(restored, node, failure);59    const next_moment = moment.prepare(60        restored.root,61        candidate.root(),62    ) catch |failure| return turnInvalidate(restored, node, failure);63    restored.fabric.* = candidate;64    restored.moment = next_moment;65    return .{ .advanced = .{66        .admission = .{ .entry = admitted.entry, .root = admitted.root },67        .settlement = .{ .entry = settled.entry, .root = settled.root },68        .moment = next_moment,69        .events = events,70        .receipt = receipt,71    } };72}

1/// Produces the moment that belongs to a given origin world root and current ledger2/// root, so a caller records where the world now stands after every ledger change.3/// A contract mismatch between the origin and the current position rejects. Any4/// ledger counter that moved backward relative to the origin rejects: the entry,5/// admission, and fault frontiers are each checked.6pub fn prepare(origin: types.Root, current: fabric.Root) Error!Moment {7    try validateMaterial(origin, current);8    return rootFor(origin, current);9}

1/// Derives the moment the material should yield and refuses a value that has drifted2/// from it, so a reader who holds a stored moment proves it belongs to this origin3/// and this position. The comparison covers every field, digest included.4pub fn verify(5    value: Moment,6    origin: types.Root,7    current: fabric.Root,8) Error!void {9    const expected = try prepare(origin, current);10    if (!std.meta.eql(value, expected)) return error.MomentMismatch;11}

1pub const Error = canon.Error ||2    checkpoint.Error ||3    fabric.Error ||4    instance.QuiescenceReceiptError ||5    profile.Error ||6    SealError;

1/// Proves that the caller's checkpoints sit at the semantic boundaries the ledger2/// currently holds, then joins them into a single cut so a caller can store the3/// boundary now and restore it later. A live binding has to carry the semantic digest4/// that its instance's quiescence receipt carries. A retained binding has to name5/// a node that the ledger already marks unavailable. The ledger's machine contract6/// has to appear in every binding. The binding count must equal the ledger's node7/// count, and each binding must name the ledger's node at the same index. Each binding's8/// profile fingerprint must equal the one recorded in its checkpoint root.9pub fn seal(10    fabric_owner: *const fabric.Fabric,11    bindings: []const types.Binding,12) Error!types.Cut {13    const fabric_cut = try fabric_owner.cut();14    if (bindings.len != fabric_cut.node_count) {15        return error.NodeCountMismatch;16    }17    var nodes: [types.node_limit]types.Node = @splat(canon.emptyNode());18    for (bindings, 0..) |binding, index| {19        const boundary = fabric_cut.nodes[index];20        if (!std.meta.eql(binding.node, boundary.id)) {21            return error.NodeMismatch;22        }23        if (boundary.machine.kind != .semantic) {24            return error.MachineBoundaryUnavailable;25        }26        const live_semantic: ?os.abi.Digest = switch (binding.source) {27            .live => |machine| live: {28                if (!boundary.available) return error.MachineSourceMismatch;29                const receipt = try machine.quiescenceReceipt();30                const semantic = try instance.projectSemanticReceipt(receipt);31                break :live try instance.semanticReceiptDigest(semantic);32            },33            .retained => retained: {34                if (boundary.available) return error.MachineSourceMismatch;35                break :retained null;36            },37        };38        try profile.validate(binding.execution_profile);39        const contract = try profile.contractFingerprint(binding.execution_profile);40        if (!std.meta.eql(contract, fabric_cut.root.machine_contract)) {41            return error.ContractMismatch;42        }43        const identity = try binding.checkpoint.identity();44        const profile_fingerprint = try profile.profileFingerprint(45            binding.execution_profile,46        );47        if (!std.meta.eql(profile_fingerprint, identity.root.profile)) {48            return error.ProfileMismatch;49        }50        if (!std.mem.eql(51            u8,52            &identity.semantic,53            &boundary.machine.digest,54        )) {55            return error.SemanticBoundaryMismatch;56        }57        if (live_semantic) |semantic| {58            if (!std.mem.eql(u8, &semantic, &identity.semantic)) {59                return error.SemanticBoundaryMismatch;60            }61        }62        nodes[index] = .{ .id = binding.node, .machine = identity.root };63    }64    return canon.prepare(65        fabric_cut.root,66        nodes[0..fabric_cut.node_count],67    );68}

1pub const Error = fault_owner.Error ||2    moment.Error ||3    replay_owner.Error ||4    restore.StableError ||5    source.Error ||6    PrefixOwnerError;

1/// Replays a plan of recorded steps on a restored world, bounded in length, beginning2/// at a verified start and finishing at the declared end, so a caller replays a3/// stretch of recorded history in one call with the plan proved consistent before4/// the guest runs at all.5/// Validation covers the entire plan before the first step runs.6/// A turn moves the entry frontiers forward by two and a fault moves them forward7/// by one, and any other advance is rejected.8/// Each moment a step expects has to verify under the world's origin.9/// The first failing step halts the replay.10/// The start moment must equal the world's verified current moment.11/// The plan's step array is checked against the world's live memory before it is12/// copied.13pub fn replayPrefix(restored: *restore.Restored, input: Input) Result {14    const current = restore.validateStable(restored) catch |failure|15        return rejected(null, 0, null, failure);16    var progress = initialProgress(current);17    if (!std.meta.eql(current, input.start)) {18        return rejected(progress, 0, null, error.PrefixStartMismatch);19    }20    if (input.steps.len > step_limit) {21        return rejected(22            progress,23            0,24            null,25            error.PrefixStepCapacityExceeded,26        );27    }28    source.validateMemory(restored, std.mem.sliceAsBytes(input.steps)) catch |failure|29        return rejected(progress, 0, null, failure);30    var steps: [step_limit]Step = undefined;31    @memcpy(steps[0..input.steps.len], input.steps);32    validatePlan(33        restored.root,34        current,35        steps[0..input.steps.len],36        input.end,37    ) catch |failure| return rejected(progress, 0, null, failure);38    for (steps[0..input.steps.len], 0..) |*step, index| {39        switch (step.*) {40            .turn => |turn| switch (replay_owner.replayTurn(41                restored,42                turn.replay,43            )) {44                .advanced => |advanced| {45                    std.debug.assert(std.meta.eql(46                        advanced.moment,47                        turn.expected_moment,48                    ));49                    std.debug.assert(progress.turn_count < step_limit);50                    progress.turn_steps[progress.turn_count] = @intCast(index);51                    progress.turn_events[progress.turn_count] = advanced.events;52                    progress.turn_count += 1;53                    progress.step_count += 1;54                    progress.moment = advanced.moment;55                },56                .rejected => |failure| return rejected(57                    progress,58                    index,59                    failure.node,60                    failure.failure,61                ),62                .invalidated => |failure| return invalidated(63                    progress,64                    index,65                    failure.node,66                    failure.failure,67                ),68            },69            .fault => |fault| switch (fault_owner.replayFault(70                restored,71                fault.reader,72                fault.expected_root,73            )) {74                .applied => |applied| {75                    std.debug.assert(std.meta.eql(76                        applied.moment,77                        fault.expected_moment,78                    ));79                    progress.step_count += 1;80                    progress.moment = applied.moment;81                },82                .rejected => |failure| return rejected(83                    progress,84                    index,85                    failure.node,86                    failure.failure,87                ),88            },89        }90    }91    std.debug.assert(std.meta.eql(progress.moment, input.end));92    return .{ .reached = progress };93}

1/// The maximum number of steps one prefix replays, for a caller sizing its plan2/// before calling.3/// A plan longer than this rejects before any step runs.4pub const step_limit: usize = 16;

1pub const Error = fabric.transition.Error ||2    fabric.Error ||3    instance.AcknowledgeError ||4    instance.DeliveryError ||5    instance.EventError ||6    instance.QuiescenceReceiptError ||7    instance.ReactivateError ||8    instance.RunError ||9    os.abi.wire.FenceError ||10    restore.StableError ||11    source.Error ||12    ReplayOwnerError;

1/// Runs one recorded turn again on a restored world so a caller proves the recording2/// and the guest still agree. Both recorded transitions replay against candidate3/// ledgers before the guest runs. The guest executes the delivery as recorded, and4/// the settlement it produces has to come out identical to the recorded transition.5/// Ledger and moment commit together on agreement. Both readers are checked against6/// the world's live memory before anything is read. The two recorded transitions7/// must name the same node, and that node must have a live instance.8pub fn replayTurn(restored: *restore.Restored, input: Input) Result {9    const prepared = preflight(restored, input) catch |failure|10        return reject(null, failure);11    const phase = prepared.machine.phase();12    switch (phase) {13        .booting, .awaiting_input, .awaiting_reactivation => {},14        else => return reject(prepared.node, error.MachinePhaseMismatch),15    }16    switch (phase) {17        .booting => activate(prepared.machine) catch |failure|18            return invalidate(restored, prepared.node, failure),19        .awaiting_reactivation => {20            prepared.machine.reactivate(input.fence) catch |failure|21                return invalidate(restored, prepared.node, failure);22            activate(prepared.machine) catch |failure|23                return invalidate(restored, prepared.node, failure);24        },25        .awaiting_input => {},26        else => unreachable,27    }28    prepared.machine.deliverAdmitted(&prepared.delivery) catch |failure|29        return invalidate(restored, prepared.node, failure);30    const exit_value = prepared.machine.run() catch |failure|31        return invalidate(restored, prepared.node, failure);32    if (!std.meta.eql(33        exit_value,34        instance.Exit{ .doorbell = .{ .code = .quiescent } },35    )) return invalidate(restored, prepared.node, error.QuiescenceExitMismatch);36    var events: instance.EventBatch = undefined;37    prepared.machine.takeEvents(&events) catch |failure|38        return invalidate(restored, prepared.node, failure);39    prepared.machine.acknowledge(prepared.delivery.receipt) catch |failure|40        return invalidate(restored, prepared.node, failure);41    const receipt = prepared.machine.quiescenceReceipt() catch |failure|42        return invalidate(restored, prepared.node, failure);43    var actual_fabric = prepared.after_admission;44    const settled = actual_fabric.settle(prepared.node, receipt) catch |failure|45        return invalidate(restored, prepared.node, failure);46    const actual: fabric.Transition = .{47        .entry = settled.entry,48        .root = settled.root,49    };50    if (!std.meta.eql(actual, prepared.settlement) or51        !std.meta.eql(actual_fabric, prepared.after_settlement))52    {53        return invalidate(54            restored,55            prepared.node,56            error.SettlementTransitionMismatch,57        );58    }59    restored.fabric.* = actual_fabric;60    restored.moment = prepared.next_moment;61    return .{ .advanced = .{62        .admission = prepared.admission,63        .settlement = actual,64        .moment = prepared.next_moment,65        .events = events,66    } };67}

1pub const Error = canon.Error ||2    checkpoint.Error ||3    fabric.Error ||4    instance.RestoreError ||5    moment.Error ||6    profile.Error ||7    RestoreOwnerError;

1/// Brings a world back from a sealed cut so a caller brings a stored boundary back2/// as running machines. The ledger has to sit at precisely the position the cut3/// recorded. Each binding is checked against both the cut and the ledger boundary,4/// covering the identity, the checkpoint root, the semantic digest, the contract5/// fingerprint, the profile fingerprint, and the fence. Live storage buffers must6/// not overlap each other, the ledger, or any checkpoint. The first backend missing7/// on this host halts construction, and everything built so far is torn down.8pub fn restore(9    cut: types.Cut,10    fabric_owner: *fabric.Fabric,11    bindings: []const Binding,12) Result {13    canon.verify(cut) catch |failure| return reject(null, failure);14    const fabric_cut = fabric_owner.cut() catch |failure|15        return reject(null, failure);16    if (!std.meta.eql(fabric_cut.root, cut.root.fabric)) {17        return reject(null, error.FabricMismatch);18    }19    if (bindings.len != cut.root.node_count or20        bindings.len != fabric_cut.node_count)21    {22        return reject(null, error.NodeCountMismatch);23    }24    var owned: [types.node_limit]Binding = undefined;25    @memcpy(owned[0..bindings.len], bindings);26    validateAliases(fabric_owner, owned[0..bindings.len]) catch |failure|27        return reject(null, failure);28    for (owned[0..bindings.len], 0..) |binding, index| {29        const boundary = fabric_cut.nodes[index];30        const node = cut.nodes[index];31        if (!std.meta.eql(binding.node, node.id) or32            !std.meta.eql(binding.node, boundary.id))33        {34            return reject(binding.node, error.NodeMismatch);35        }36        if (boundary.machine.kind != .semantic) {37            return reject(binding.node, error.MachineBoundaryUnavailable);38        }39        const identity = switch (binding.mode) {40            .live => |target| live: {41                if (!boundary.available) {42                    return reject(binding.node, error.MachineModeMismatch);43                }44                validateTarget(cut.root, node.machine, target) catch |failure|45                    return reject(binding.node, failure);46                break :live instance.validateRestore(47                    target.storage,48                    target.ram,49                    .{50                        .checkpoint = binding.checkpoint,51                        .expected_root = node.machine,52                        .profile = target.profile,53                        .execution_manifest = target.execution_manifest,54                        .fence = target.fence,55                    },56                ) catch |failure| return reject(binding.node, failure);57            },58            .retained => retained: {59                if (boundary.available) {60                    return reject(binding.node, error.MachineModeMismatch);61                }62                break :retained binding.checkpoint.identity() catch |failure|63                    return reject(binding.node, failure);64            },65        };66        if (!std.meta.eql(identity.root, node.machine)) {67            return reject(binding.node, error.CheckpointRootMismatch);68        }69        if (!std.mem.eql(u8, &identity.semantic, &boundary.machine.digest)) {70            return reject(binding.node, error.SemanticBoundaryMismatch);71        }72    }73    const initial_moment = moment.prepare(cut.root, fabric_cut.root) catch |failure|74        return reject(null, failure);75    return construct(76        cut,77        fabric_owner,78        initial_moment,79        owned[0..bindings.len],80    );81}

1pub const world = @import("world/root.zig");

1//! Machines that talk to each other advance separately, so stopping them all at2//! one instant, storing that instant, and bringing it back later takes a definition3//! of what one instant is, and this namespace supplies it. The namespace folds the4//! state of every running machine, every machine's saved state, and the order of5//! 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 after10//! its changes have begun. Running machines together adds places where two runs11//! 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 record14//! of every admitted input, packet, settlement, and fault decision across them,15//! the *ledger*. The namespace runs one deterministic execution across up to four16//! machines, together with the ledger (a *world*). The instant is a complete restorable17//! boundary holding one digest of the whole world state together with the checkpoint18//! 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 settles21//! it (a *turn*). Each turn runs under the world, generation, and token authorized22//! for it (its *activation fence*). Every mutation works on a copy of the ledger23//! (a *candidate ledger*), verifies the result on that copy, then commits the record24//! and the world's new position in its history together, once every verification25//! 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 ends27//! the world (*invalidated*).28//!29//! The namespace answers for exactly three named places where two runs of the same30//! program could differ (each a *divergence source*): the activation fence, turn31//! 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 contract35//!   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 world37//!   grew from with the ledger root it has reached since.38//! - *instance*: one live K0 execution that borrows caller-owned storage and guest-memory39//!   backing until `deinit`.40//! - *checkpoint*: captured machine execution state carrying an identity that any41//!   holder of the bytes can recompute.4243const fault_owner = @import("fault.zig");44const live_owner = @import("live.zig");45const moment_owner = @import("moment.zig");46const owner = @import("owner.zig");47const prefix_owner = @import("prefix.zig");48const profile = @import("../profile/root.zig");49const replay_owner = @import("replay.zig");50const restore_owner = @import("restore.zig");51const types = @import("types.zig");5253pub const manifest = @import("manifest/root.zig");5455pub const Binding = types.Binding;56pub const Cut = types.Cut;57pub const Dialect = types.Dialect;58pub const Error = owner.Error;59pub const FaultApplied = fault_owner.Applied;60pub const FaultError = fault_owner.Error;61pub const FaultRejection = fault_owner.Rejection;62pub const FaultResult = fault_owner.Result;63pub const LiveActivated = live_owner.Activated;64pub const LiveActivateResult = live_owner.ActivateResult;65pub const LiveAdvanced = live_owner.Advanced;66pub const LiveError = live_owner.Error;67pub const LiveRejection = live_owner.Rejection;68pub const LiveTurnResult = live_owner.TurnResult;69pub const Moment = moment_owner.Moment;70pub const MomentDialect = moment_owner.Dialect;71pub const MomentError = moment_owner.Error;72pub const Node = types.Node;73pub const PrefixError = prefix_owner.Error;74pub const PrefixFault = prefix_owner.Fault;75pub const PrefixInput = prefix_owner.Input;76pub const PrefixProgress = prefix_owner.Progress;77pub const PrefixResult = prefix_owner.Result;78pub const PrefixStep = prefix_owner.Step;79pub const PrefixStopped = prefix_owner.Stopped;80pub const PrefixTurn = prefix_owner.Turn;81pub const Root = types.Root;82pub const RestoreBinding = restore_owner.Binding;83pub const RestoreError = restore_owner.Error;84pub const RestoreMode = restore_owner.Mode;85pub const RestoreRejection = restore_owner.Rejection;86pub const RestoreResult = restore_owner.Result;87pub const RestoreTarget = restore_owner.Target;88pub const RestoreUnavailable = restore_owner.Unavailable;89pub const Restored = restore_owner.Restored;90pub const RestoredNode = restore_owner.Node;91pub const ReplayAdvanced = replay_owner.Advanced;92pub const ReplayError = replay_owner.Error;93pub const ReplayFrame = replay_owner.Frame;94pub const ReplayInput = replay_owner.Input;95pub const ReplayRejection = replay_owner.Rejection;96pub const ReplayResult = replay_owner.Result;97pub const Source = types.Source;98pub const node_limit = types.node_limit;99pub const prefix_step_limit = prefix_owner.step_limit;100pub const applyFault = fault_owner.applyFault;101pub const activate = live_owner.activate;102pub const prepareMoment = moment_owner.prepare;103pub const replayFault = fault_owner.replayFault;104pub const replayPrefix = prefix_owner.replayPrefix;105pub const seal = owner.seal;106pub const restore = restore_owner.restore;107pub const replayTurn = replay_owner.replayTurn;108pub const terminal = live_owner.terminal;109pub const verify = owner.verify;110pub const verifyMoment = moment_owner.verify;111112pub const determinism_sources = [_]profile.DeterminismSource{113    .activation_fence,114    .turn_selection,115    .replay_source,116};