tiny.machine.admission

1/// A caller matches on these rejections of admission material to tell a malformed2/// input apart from one that arrived out of order. Every variant means one of four3/// things failed: validation of a field, a payload bound, the ordering against a4/// frontier, or the recomputation of a digest.5pub const Error = error{6    ContractDigestInvalid,7    EffectFrontierExhausted,8    EffectRequestInvalid,9    EffectRequestPending,10    EffectReceiptInvalid,11    EffectOutputRootInvalid,12    EntropyGenerationExhausted,13    EntropyGenerationMismatch,14    InputFrontierExhausted,15    DeliveryFenceInvalid,16    DeliveryFenceMismatch,17    NoncanonicalDelivery,18    NoncanonicalRecord,19    PayloadCapacityExceeded,20    PayloadEmpty,21    SourceRootInvalid,22    TerminalOffsetExhausted,23    TerminalOffsetMismatch,24    VirtualTimeMismatch,25};

1/// One admitted record with everything needed to recheck it: the contract fingerprint,2/// the source root, the input position, the frontiers before it, the record, the3/// frontiers expected after it, the outstanding effect before and after, and the4/// committing receipt.5/// Verification rebuilds the whole value from the basis and the record, then compares6/// that rebuild against the stored one.7pub const Admission = struct {8    contract: profile.ContractFingerprint,9    source_root: Digest,10    position: u64,11    frontiers: Frontiers,12    record: Record,13    expected: Frontiers,14    outstanding_effect: ?EffectRequest,15    expected_outstanding_effect: ?EffectRequest,16    receipt: Receipt,17};

1/// The authenticated position an input is admitted against, naming the source root2/// in force, the contract fingerprint, the five frontiers, and any effect still3/// outstanding.4/// A basis with an all-zero contract digest, an all-zero source root, or an out-of-order5/// outstanding request is rejected.6pub const Basis = struct {7    contract: profile.ContractFingerprint,8    source_root: Digest,9    frontiers: Frontiers,10    outstanding_effect: ?EffectRequest,11};

1/// One admission joined to an activation fence and to the source root that follows,2/// in the form written into the guest's request ring.3/// The delivery receipt commits the admission receipt, the next source root, and4/// all three fence fields.5pub const Delivery = struct {6    admission: Admission,7    next_source_root: Digest,8    fence: os.abi.ActivationFence,9    receipt: DeliveryReceipt,10};

1/// The digest committing one delivery.2pub const DeliveryReceipt = struct {3    digest: Digest,4};

1/// One outstanding guest request: the digest of its receipt and its correlation2/// value.3/// The correlation must be the effect frontier plus one, so requests answer in order.4pub const EffectRequest = struct {5    receipt: EffectRequestReceipt,6    correlation: u64,7};

1/// The receipt digest that names one guest effect request.2pub const EffectRequestReceipt = struct {3    digest: Digest,4};

1/// One admitted result for outside work, bound to the request it answers: the request,2/// the effect status, the output root, the payload length, and fixed payload storage.3/// The carried request must equal the outstanding effect, and admitting the result4/// clears that effect.5pub const EffectResult = struct {6    request: EffectRequest,7    status: os.abi.EffectStatus,8    output_root: Digest,9    length: u16,10    storage: [effect_result_bytes_max]u8,11};

1/// One admitted entropy block: its generation, its payload length, and fixed payload2/// storage.3/// The generation must be the entropy frontier plus one.4pub const Entropy = struct {5    generation: u64,6    length: u16,7    storage: [entropy_bytes_max]u8,8};

1/// The five counters that fix the order of admitted inputs and only rise, one for2/// the input position, one for the terminal offset, one for the time tick, one for3/// the entropy generation, and one for the effect count.4/// Every counter moves forward under overflow-checked arithmetic, and an exhausted5/// counter rejects the admission.6pub const Frontiers = struct {7    input: u64,8    terminal_input_offset: u64,9    virtual_time_tick: u64,10    entropy_generation: u64,11    effect: u64,12};

1/// The receipt digest taken over one admission.2pub const Receipt = struct {3    digest: Digest,4};

1/// One record of an input crossing into the guest.2/// The four kinds are terminal bytes, a virtual-time advance, an entropy block,3/// and an effect result.4pub const Record = union(enum) {5    terminal: Terminal,6    virtual_time: VirtualTime,7    entropy: Entropy,8    effect_result: EffectResult,9};

1/// One terminal input after admission, holding where its bytes sit in the terminal2/// stream, how many bytes it carries, and the fixed storage those bytes occupy.3/// The offset must equal the terminal frontier at admission, and admitting the record4/// moves that frontier forward by the payload length.5/// Every storage byte past the payload length is zero.6pub const Terminal = struct {7    offset: u64,8    length: u16,9    storage: [terminal_bytes_max]u8,10};

1/// One clock advance after admission, holding the tick it leaves and the strictly2/// greater tick it moves to.3/// The source tick must equal the time frontier at admission.4pub const VirtualTime = struct {5    from_tick: u64,6    to_tick: u64,7};

1/// Joins one admission with a fence it has validated and with the source root that2/// follows, then hashes the whole into a delivery receipt, so a caller can produce3/// the delivery form the guest accepts. An all-zero next source root is rejected,4/// and so is a fence with a zero generation, an all-zero world, or an all-zero token.5pub fn bindDelivery(6    value: types.Admission,7    next_source_root: types.Digest,8    fence: os.abi.ActivationFence,9) Error!types.Delivery {10    try validateDigest(next_source_root, error.SourceRootInvalid);11    os.abi.wire.validateFence(fence) catch12        return error.DeliveryFenceInvalid;13    var result: types.Delivery = .{14        .admission = value,15        .next_source_root = next_source_root,16        .fence = fence,17        .receipt = .{ .digest = undefined },18    };19    result.receipt.digest = deliveryDigest(result);20    return result;21}

1/// Copies the caller's bytes into fixed storage for a caller answering the outstanding2/// guest request, pairing them with the receipt and correlation of the request being3/// answered, the status of the effect, and the root of its output. A payload longer4/// than the effect-result bound is rejected. By contrast, an empty payload is accepted,5/// so a result that reports a status and carries no bytes passes.6pub fn effectResult(7    request_receipt: types.Digest,8    correlation: u64,9    status: os.abi.EffectStatus,10    output_root: types.Digest,11    bytes: []const u8,12) Error!types.Record {13    if (bytes.len > types.effect_result_bytes_max) {14        return error.PayloadCapacityExceeded;15    }16    var value: types.EffectResult = .{17        .request = .{18            .receipt = .{ .digest = request_receipt },19            .correlation = correlation,20        },21        .status = status,22        .output_root = output_root,23        .length = @intCast(bytes.len),24        .storage = @splat(0),25    };26    @memcpy(value.storage[0..bytes.len], bytes);27    return .{ .effect_result = value };28}

1/// Builds an entropy record for one generation from the caller's bytes so a caller2/// can hand the guest a recorded block of randomness, copying them into the record's3/// fixed storage. An empty payload is rejected, and so is one longer than the entropy4/// bound.5pub fn entropy(generation: u64, bytes: []const u8) Error!types.Record {6    if (bytes.len == 0) return error.PayloadEmpty;7    if (bytes.len > types.entropy_bytes_max) return error.PayloadCapacityExceeded;8    var value: types.Entropy = .{9        .generation = generation,10        .length = @intCast(bytes.len),11        .storage = @splat(0),12    };13    @memcpy(value.storage[0..bytes.len], bytes);14    return .{ .entropy = value };15}

1/// Applies one record to a basis it has validated, then hashes the outcome into2/// the receipt it returns, so a caller can deliver the resulting admission and a3/// verifier can recheck it. The input position is the input frontier plus one. While4/// an effect request is outstanding, only its result admits. Frontier arithmetic5/// is checked for overflow, so a counter at its limit rejects the record and holds6/// its value.7pub fn prepare(basis: types.Basis, record: types.Record) Error!types.Admission {8    try validateBasis(basis);9    const position = std.math.add(u64, basis.frontiers.input, 1) catch10        return error.InputFrontierExhausted;11    var expected = basis.frontiers;12    var expected_outstanding_effect = basis.outstanding_effect;13    expected.input = position;14    try fold(&expected, &expected_outstanding_effect, record);15    var result: types.Admission = .{16        .contract = basis.contract,17        .source_root = basis.source_root,18        .position = position,19        .frontiers = basis.frontiers,20        .record = record,21        .expected = expected,22        .outstanding_effect = basis.outstanding_effect,23        .expected_outstanding_effect = expected_outstanding_effect,24        .receipt = .{ .digest = undefined },25    };26    result.receipt.digest = digest(&result);27    return result;28}

1/// Builds a terminal record at one offset from the caller's bytes for each chunk2/// of input bytes the caller wants the guest to read, copying them into the record's3/// fixed storage. An empty payload is rejected, and so is one longer than the terminal4/// bound.5pub fn terminal(offset: u64, bytes: []const u8) Error!types.Record {6    if (bytes.len == 0) return error.PayloadEmpty;7    if (bytes.len > types.terminal_bytes_max) return error.PayloadCapacityExceeded;8    var value: types.Terminal = .{9        .offset = offset,10        .length = @intCast(bytes.len),11        .storage = @splat(0),12    };13    @memcpy(value.storage[0..bytes.len], bytes);14    return .{ .terminal = value };15}

1/// Rejects a basis whose contract digest, source root, or outstanding effect request2/// fails validation, so a caller can check the basis before building a record against3/// it. An all-zero contract digest and an all-zero source root are both rejected.4/// An outstanding request whose correlation is other than the effect frontier plus5/// one is rejected.6pub fn validateBasis(basis: types.Basis) Error!void {7    try validateDigest(basis.contract.digest, error.ContractDigestInvalid);8    try validateDigest(basis.source_root, error.SourceRootInvalid);9    try validateEffectRequest(basis);10}

1/// The call recomputes the expected admission from the basis and the record, then2/// rejects a value that differs anywhere, so a reader holding a recorded admission3/// can prove it unchanged. The comparison covers every field, receipt included,4/// so a changed payload byte fails it.5pub fn verify(basis: types.Basis, value: *const types.Admission) Error!void {6    const expected = try prepare(basis, value.record);7    if (!std.meta.eql(expected, value.*)) return error.NoncanonicalRecord;8}

1/// Checks a delivery in three layers, innermost first, so a reader holding a recorded2/// delivery can prove both the delivery and the admission inside it: its fence has3/// to equal the one the caller names, the admission it wraps has to verify against4/// the basis, and its own receipt has to hash to the stored value.5pub fn verifyDelivery(6    basis: types.Basis,7    fence: os.abi.ActivationFence,8    value: *const types.Delivery,9) Error!void {10    try validateDigest(value.next_source_root, error.SourceRootInvalid);11    os.abi.wire.validateFence(value.fence) catch12        return error.DeliveryFenceInvalid;13    if (!os.abi.wire.equalFence(fence, value.fence)) {14        return error.DeliveryFenceMismatch;15    }16    try verify(basis, &value.admission);17    const expected = try bindDelivery(18        value.admission,19        value.next_source_root,20        value.fence,21    );22    if (!std.meta.eql(expected, value.*)) return error.NoncanonicalDelivery;23}

1/// Builds a clock advance from one tick to another so a caller can move the guest's2/// clock. The clock advance is admitted only when the tick it moves to is strictly3/// greater than the tick it leaves.4pub fn virtualTime(from_tick: u64, to_tick: u64) Error!types.Record {5    if (to_tick <= from_tick) return error.VirtualTimeMismatch;6    return .{ .virtual_time = .{7        .from_tick = from_tick,8        .to_tick = to_tick,9    } };10}

1//! Replaying a run requires feeding the guest exactly the inputs the first run saw,2//! in the same order, and this namespace records each one so a later reader can3//! check the whole history from the receipts alone. Four kinds of input cross into4//! the guest: terminal bytes, a virtual-time advance, an entropy block, and an effect5//! result. Each input is checked against where the guest stood when it arrived.6//! Each input reaches the guest through its request ring, together with the authority7//! to run the guest work that settles it.8//!9//! Terminal, entropy, and effect-result payloads are held in fixed storage sized10//! by the machine ABI message bounds. While a guest request for an outside effect11//! awaits its result, every other kind of input is refused until that result is12//! admitted. The counters that order inputs are checked for overflow, so a counter13//! at its limit rejects the input and holds its value. Verification recomputes a14//! receipt from its material and rejects an input that changed. Receipts of different15//! kinds must never collide.16//!17//! The namespace admits each recorded outside influence (an *admission*): it folds18//! the influence into an authenticated position and produces a receipt committing19//! the input and that position. That position (the *basis*) names the authenticated20//! state in force, the identity of the shared execution rules, the five ordering21//! counters, and any effect request still outstanding. `prepare` applies one input22//! to a basis it has validated, then hashes the outcome into a receipt. `bindDelivery`23//! joins one admission with the world, generation, and token authorized for one24//! run turn (an *activation fence*), and with the authenticated state that follows.25//! The guest's request ring receives that joined bundle, a *delivery*. Receipts26//! are SHA-256 digests, each taken under a distinct constant string hashed before27//! the value (a *domain tag*), with one tag for admissions and another for deliveries.28//!29//! - *record*: one input crossing into the guest.30//! - *admission receipt*: the digest committing one admission.31//! - *source root*: the digest naming the authenticated state a basis stands on.32//! - *contract fingerprint*: the identity of the shared execution rules, computed33//!   over the encoded profile with the backend field and the claim fields zeroed.34//! - *frontiers*: the five counters that order admitted inputs and only rise, one35//!   each for the input position, the terminal offset, the time tick, the entropy36//!   generation, and the effect count.3738const canon = @import("canon.zig");39const types = @import("types.zig");4041pub const Admission = types.Admission;42pub const Basis = types.Basis;43pub const Delivery = types.Delivery;44pub const DeliveryReceipt = types.DeliveryReceipt;45pub const Digest = types.Digest;46pub const EffectResult = types.EffectResult;47pub const EffectRequest = types.EffectRequest;48pub const EffectRequestReceipt = types.EffectRequestReceipt;49pub const Entropy = types.Entropy;50pub const Error = canon.Error;51pub const Frontiers = types.Frontiers;52pub const Receipt = types.Receipt;53pub const Record = types.Record;54pub const Terminal = types.Terminal;55pub const VirtualTime = types.VirtualTime;56pub const effect_result_bytes_max = types.effect_result_bytes_max;57pub const entropy = canon.entropy;58pub const entropy_bytes_max = types.entropy_bytes_max;59pub const effectResult = canon.effectResult;60pub const bindDelivery = canon.bindDelivery;61pub const prepare = canon.prepare;62pub const terminal = canon.terminal;63pub const terminal_bytes_max = types.terminal_bytes_max;64pub const validateBasis = canon.validateBasis;65pub const verify = canon.verify;66pub const verifyDelivery = canon.verifyDelivery;67pub const virtualTime = canon.virtualTime;

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

1/// The 32-byte digest type every root and receipt in this namespace carries.2/// The type comes from the machine ABI, so an admission digest and a message digest3/// are one type.4pub const Digest = os.abi.Digest;

1/// The largest effect-result payload the machine ABI allows, in bytes.2/// An effect result built from more bytes than this is rejected.3pub const effect_result_bytes_max: usize = os.abi.message.effect_result_bytes_max;

1/// The largest entropy payload the machine ABI allows, in bytes.2/// An entropy record built from more bytes than this is rejected.3pub const entropy_bytes_max: usize = os.abi.message.entropy_bytes_max;

1/// The largest terminal payload the machine ABI allows, in bytes.2/// A terminal record built from more bytes than this is rejected.3pub const terminal_bytes_max: usize = os.abi.message.terminal_bytes_max;