tiny.machine.fault

1/// Rejections of fault material.2/// A caller matches on these to tell which piece failed, because every variant names3/// the digest or the encoding version that failed recomputation: the basis, the4/// chain, the decision, the point, or the subject.5pub const Error = error{6    InvalidFaultBasis,7    InvalidFaultChain,8    InvalidFaultDecision,9    InvalidFaultPoint,10    InvalidFaultSubject,11};

1/// The version number a fault record is written under, its encoding version. A reader2/// checks this before trusting a stored fault record. The reader rejects a record3/// written under a version it does not speak. One version exists today: `deterministic_fault_v1`.4pub const Dialect = enum(u16) {5    deterministic_fault_v1 = 1,6};

1/// Extends the running fault-chain digest by one decision it has verified.2/// Equal chain digests prove equal fault histories.3/// An all-zero previous digest is rejected, and the decision is verified before4/// it folds in.5pub fn advance(6    previous: os.abi.Digest,7    decision: types.Decision,8) Error!os.abi.Digest {9    try validateDigest(previous, error.InvalidFaultChain);10    try verifyDecision(decision);11    var hasher = Sha256.init(.{});12    hasher.update(chain_domain);13    hasher.update(&previous);14    hasher.update(&decision.digest);15    var digest: os.abi.Digest = undefined;16    hasher.final(&digest);17    return digest;18}

1/// Pairs a point it has verified with one choice, the outcome recorded at a fault2/// point, then hashes that pair into the decision digest.3/// The point is verified before the choice is bound to it.4pub fn decide(point: types.Point, choice: types.Choice) Error!types.Decision {5    try verifyPoint(point);6    var decision: types.Decision = .{7        .point = point,8        .choice = choice,9        .digest = undefined,10    };11    decision.digest = decisionDigest(decision);12    return decision;13}

1/// Assembles a fault point, one place a fault may occur, from its material and computes2/// the id that authenticates it, so that the same place in two runs comes out as3/// the same value.4/// An all-zero basis digest and an all-zero subject digest are both rejected before5/// the id is computed.6/// The id is a SHA-256 digest over the encoding version, the basis, the kind, and7/// the subject, under the point domain tag.8/// A domain tag is a distinct constant string hashed before a value, so digests9/// of different kinds never collide.10pub fn prepare(11    basis: os.abi.Digest,12    kind: types.Kind,13    subject: os.abi.Digest,14) Error!types.Point {15    try validateDigest(basis, error.InvalidFaultBasis);16    try validateDigest(subject, error.InvalidFaultSubject);17    var point: types.Point = .{18        .id = undefined,19        .dialect = .deterministic_fault_v1,20        .basis = basis,21        .kind = kind,22        .subject = subject,23    };24    point.id = pointDigest(point);25    return point;26}

1/// Verifies both halves of a stored decision to prove the record unchanged, checking2/// from the bottom up with the point id first and then the decision digest over3/// it.4pub fn verifyDecision(decision: types.Decision) Error!void {5    try verifyPoint(decision.point);6    if (!std.mem.eql(u8, &decision.digest, &decisionDigest(decision))) {7        return error.InvalidFaultDecision;8    }9}

1/// Recomputes a point's id from its fields and rejects any drift, proving the stored2/// record unchanged.3/// A point carrying an unknown encoding version is rejected first.4pub fn verifyPoint(point: types.Point) Error!void {5    if (point.dialect != .deterministic_fault_v1) {6        return error.InvalidFaultPoint;7    }8    try validateDigest(point.basis, error.InvalidFaultBasis);9    try validateDigest(point.subject, error.InvalidFaultSubject);10    if (!std.mem.eql(u8, &point.id, &pointDigest(point))) {11        return error.InvalidFaultPoint;12    }13}

1//! Testing how a system survives failure means choosing, at a named place, whether2//! the failure happens, and a replay has to make the same choices the recorded run3//! made. The place has to be named by the state it was derived from, so that the4//! same place in two runs is the same value. A run makes many such choices, and5//! comparing two runs means comparing their whole histories of choices. The choices6//! have to fall into one order together with the inputs the machines receive. Digests7//! of different kinds must never collide, and a stored record can be altered after8//! the fact.9//!10//! The namespace names each place where a fault may occur (a *fault point*) by the11//! digest of the state it grew from, its kind, and a digest for whatever it targets,12//! plus an id that commits the other three. The outcome recorded at such a place13//! (a *choice*) is either bypass, which leaves execution untouched, or inject, which14//! applies the fault effect. The namespace binds one verified point to the choice15//! taken there and carries a digest over the pair (a *fault decision*).16//!17//! `advance` folds each decision into one running digest (the *fault chain digest*),18//! so a single digest stands for an entire fault history and two histories agree19//! exactly when their digests agree. Each decision also enters the ordered record20//! of every admitted input, settlement, and fault decision across a world's nodes21//! (the *ledger*, `Fabric` in the code). There it takes one entry, which advances22//! the entry frontier and counts against the same admission budget as an admitted23//! input.24//!25//! Digests are SHA-256, taken under three distinct constant strings hashed before26//! the value (each a *domain tag*): one tag each for points, decisions, and the27//! chain. Every check hashes the material again and refuses a record whose stored28//! digest disagrees with the rebuilt one.29//!30//! - *fault kind*: one of the eleven fault families a point can name, from a machine31//!   crash through a host service failure.3233const canon = @import("canon.zig");34const types = @import("types.zig");3536pub const Choice = types.Choice;37pub const Decision = types.Decision;38pub const Dialect = types.Dialect;39pub const Error = canon.Error;40pub const Kind = types.Kind;41pub const Point = types.Point;42pub const advance = canon.advance;43pub const decide = canon.decide;44pub const prepare = canon.prepare;45pub const verifyDecision = canon.verifyDecision;46pub const verifyPoint = canon.verifyPoint;

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