Module detlog 

Module contains macroses that help tracing DETLOG entires for the purpose of verifiying determinism [‘detlog’] can be used to write a deterministic log entry at INFO level [’detlog_debug] can be use to write a deterministic log entry at DEBUG level

Structs

CoordinatorForwardingReceipt

A coordinator-local observation of a checked forwarding boundary.

DetLogRecord

Versioned serialized form appended to the human log record.

ForwardPolicy

Which emitting modules a forwarded process may send DETLOG records from.

NativeForwardedSourceReceipt

Coordinator-local source identity retained at native source registration. It does not authenticate an image or authorize any exec/lifecycle transition.

Enums

CoordinatorForwardingCutError

Why the coordinator cannot establish a strict counted forwarding boundary.

DetLogEvent

Producer-owned facts needed by log comparison.

ForwardingCutError

Why the process-local forwarding state cannot cross an image replacement.

Constants

DETERMINISM_LOSS_RECORD_TARGET

The target of the evidence record that reports this process’s determinism_loss where the verifier cannot read it: under the DBT backend Detcore runs in the guest’s DynamoRIO client, so the client writes the reason into its protected evidence stream at process exit, and hermit’s DBT adapter refuses the comparison when a run’s evidence holds one.

FORWARDING_AMBIGUOUS_ORDER_NOTICE

The FORWARDING_LOSS_NOTICE the coordinator writes when more than one guest thread sends a request before the first turn, so the forwarded records’ order would depend on the host.

FORWARDING_LOSS_NOTICE

Starts the line send_forwarded_record sends in place of a record it could not deliver, followed by the record’s length and the error number. Its presence means the forwarded records are incomplete, so verification must not compare them.

FORWARDING_RETIRED_NOTICE

The message an in-guest runtime sends on the forwarding socket when it has to give the socket up (reverie-liteinst’s reserve_tool_output_fd retirement message): a FORWARDING_LOSS_NOTICE, since no later record can arrive.

FORWARDING_UNTAGGED_RECORD_NOTICE

The FORWARDING_LOSS_NOTICE the coordinator writes when a forwarded record arrives without a sender tag (a guest runtime older than the tag), so its place in the log would be the host’s choice.

PLAIN_INFO_MAGIC

Dedicated typed payload on the existing counted message socket. This is not a textual INFO acceptance rule and grants no execution authority.

RECORD_SCHEMA

Current schema written beside each structured DETLOG event.

RECORD_SEPARATOR

Delimits the machine-readable record appended to a human DETLOG message.

UNCOUNTED

The count a request reports when some thread’s records could not be counted.

Traits

NativePhysicalExitCompletion

Actual physical exit-watch completion carried by a private affine backend receipt, not a caller’s assertion that an exit happened.

NativePhysicalWatchIdentity

Identity retained by the actual backend watch for this run’s root process.

Functions

check_empty_forwarding_cut

Inspect an empty forwarding boundary without consuming or resetting it.

check_forwarded_count

The COMPLETENESS RULE. A counted request from guest thread tid says it produced produced records for forwarding since its previous counted request (take_forwarded_since_request); it sent them before this request, and a send on a message socket queues a record on the receiver before it returns, so all of them have been received by now, as indexes 1 to produced in order. Anything else means the records the coordinator holds for that thread are not the ones it produced: fewer, or a skipped index, were lost on the way (the guest disturbed the socket, the Tool could not adopt it, or a stale descriptor was refused); more, or a repeated or earlier index, came from something other than the Tool. Either way the coordinator writes a loss notice and records the determinism loss, so verification refuses to compare the run. UNCOUNTED (a thread could not be counted) is refused the same way. Without a registered source it does nothing.

check_native_exec_forwarding_cut

Collect, write and check one owner’s actual counted interval, then require the registered forwarding source to have no unchecked or queued records.

clear_forwarded_source

Unregisters the source set with set_forwarded_source, after taking the last waiting records and writing every queued record, thread by thread in thread-id order, and closes its socket.

decode_plain_info

Decode the complete envelope, rejecting unsupported classes and trailing bytes. Returned slices borrow the exact counted datagram payload.

determinism_loss

The first determinism loss record_determinism_loss recorded in this process, if any.

drain_forwarded

Takes every message waiting on the registered forwarding socket into the queue of its sending thread, without blocking and without writing it. An untagged message is written at once as ForwardedOrder::untagged says. Without a registered source it does nothing.

drain_forwarded_at_request

Takes waiting messages as drain_forwarded does at the top of the handler of a request from thread tid, and writes tid’s queued records now when its request is a point the schedule fixes (the order rule at set_forwarded_source).

encode_plain_info

Encode only the message-only INFO class. Geometry/UTF-8 are checked again by the host; no raw INFO line can substitute for this envelope.

finish_native_forwarded_source_after_exit

Complete native DETLOG teardown after an actual physical-watch receipt. The unchanged counted/order rules must have credited every final record; unchecked tail records, legacy/order/loss notices, receive/poll errors and a replaced source all remain errors. On failure the source is retained. The successful operation consumes this registered source once.

forward_tail_start

Called only by the explicit InitialImage shared Reverie delivery hook. The existing policy/count/socket own delivery; this adds no logging owner.

forward_to_stderr

A DetlogForwarder for a tool that runs inside the guest process and shares the guest’s standard error: it writes each record as one [forwarded_line] there, where Hermit’s verification separates the records from the guest’s own output by their text.

info_enabled_for_target

Whether the current subscriber would log a detlog! record emitted in the module target. In-process that record passes two checks: detlog!’s own tracing::enabled!(INFO), a hint with no fields, and then the tracing::info! event itself, which carries one field, the message. A directive with a field filter (detcore::random[{name}]=warn) applies to the hint whatever its fields but to the event only when the event has that field, so the two checks can disagree; the record is logged only when both pass, and so this answers true only when both probes do.

parse_tool_output_env_value

The descriptor and socket identity a tool_output_env_value names.

record_determinism_loss

Records that this run’s records can no longer be trusted to compare: a record was lost, or an event happened at a moment the host chose. The first reason is kept. Verification refuses to compare a run whose determinism_loss is set, independently of whether the corresponding loss notice reached the log.

record_replay_refusal

Records that a recording made by this process cannot be replayed faithfully, for the recorder to persist in its metadata (replay_refused), so that replay refuses before it starts the guest. The first reason is kept. It also records a determinism loss.

release_forwarded_count

Releases this thread’s count slot, at its deregistration, after its last count was taken.

replay_refusal

The first replay refusal record_replay_refusal recorded in this process, if any.

require_forwarding

Called by a Tool image whose coordinator requires in-guest forwarding by the policy expected encodes (Config::in_guest_detlog_forward_policy). Without a forwarder in this image, or with one that forwards by another policy (records its policy drops are never counted), the records cannot be accounted for, so every later count is UNCOUNTED and the coordinator refuses the run (check_forwarded_count).

retain_native_forwarded_source

Bind the actual source to its living watched root before releasing guest startup. EOF later requires completion of this exact retained birth.

send_forwarded_record

Sends one record as one [forwarded_line] message on socket, a message-oriented socket (such as one end of a SOCK_SEQPACKET pair) that carries nothing but records, from which Hermit’s verification moves them into the run’s log.

send_plain_info_record

Send the already counted record on its actual authenticated socket. None deliberately sends nothing; the produced index remains outstanding and the existing request/terminal cut must refuse the missing record.

set_forwarded_source

Registers the receiving end of the socket an in-guest Tool sends its records on (send_forwarded_record) and the sink that writes them to the run’s log.

set_forwarder

Installs a process-local sink for deterministic INFO records.

set_plain_info_forwarder

Select counted delivery for the two shared semantic INFO producers. Requires the actual existing DETLOG policy/channel to be installed first.

socket_identity

The socket fd names, as (st_dev, st_ino); None when it names no socket.

split_forwarded_message

The sender’s thread id, the record’s index and the record, for a message tagged by tagged_forwarded_message; None for an untagged message (a FORWARDING_LOSS_NOTICE or FORWARDING_RETIRED_NOTICE sent raw, or a record from a runtime older than the tag).

tagged_forwarded_message

Prefixes a forwarded record with the id of the guest thread that sent it and the record’s index in that thread’s counted interval, T<tid>.<index> , so the coordinator can write each thread’s records at that thread’s own scheduler turn (write_forwarded_for) and check that it holds exactly the records the thread produced, in order (check_forwarded_count). The coordinator strips the tag before the record reaches the log.

take_forwarded_since_request

How many records this guest thread produced for forwarding since its last counted request, and starts its next count. The in-guest Tool sends it with that request (check_forwarded_count), on its RPC connection, which does not depend on the forwarding socket. A forked child starts from zero: its thread id is new. UNCOUNTED once any thread could not be counted.

tool_output_env_target

The descriptor a tool_output_env_value names, if it still names that socket in this process.

tool_output_env_value

The value Hermit passes an in-guest Tool for its output socket fd (reverie_sabre::TOOL_OUTPUT_ENV, detcore_liteinst::DETLOG_FORWARD_ENV): <fd>:<st_dev>:<st_ino>, the identity in 16 hexadecimal digits each. Guest code can run before the Tool adopts the descriptor (an executable’s .preinit_array) and close it or put a socket of its own at that number; the Tool adopts it only if it is still this socket (tool_output_env_target), so its records never reach the guest’s socket. The fixed width keeps the value’s length, which a scrubbed environment block keeps, independent of the host.

validate_plain_info_directives

Refuses filters whose meaning cannot be reproduced by the existing target-only ForwardPolicy. Call before enabling the ordered INFO runtime. This does not alter the policy or guess answers for span/field directives.

write_forwarded_for

Takes waiting messages as drain_forwarded does, then writes every queued record thread tid sent, in the order it sent them. The scheduler calls this immediately before it commits a turn of tid; exclusive is false for a BACKGROUND turn, which runs alongside later turns, and true for an ordinary one.

write_loss_notice

Writes a FORWARDING_LOSS_NOTICE line with reason through the registered forwarding sink, the unfiltered raw path, and records the determinism loss. Without a registered source the loss is still recorded.

Type Aliases

DetlogForwarder

A process-local sink for deterministic INFO records: the emitting module’s path (the target tracing would give the record), the record suffix, the record’s index in its thread’s current counted interval (1 for the first record after the thread’s last counted request; see take_forwarded_since_request), and the message.

ForwardedRecordSink

Receives each record the coordinator writes from a forwarding socket: a [forwarded_line] (its sender tag removed), or a FORWARDING_LOSS_NOTICE.

PlainInfoForwarder

Explicitly selected only by the genuine InitialImage runtime. Existing preload/DBT callers never select this delivery mode merely by installing the historical DETLOG forwarder.