Module record_seal

Expand description

A session’s records, made checkable by anyone holding the host’s public key and nothing else.

Three parts, each the one implementation mur, the escape-conformance harness and a check capsule call:

The host key (HostKey): an Ed25519 seed in ~/.murmur/keys/record-seal.key (64 hex characters, 0600, directory 0700) and its public half in record-seal.pub (64 hex characters, 0644). Only the mur process reads the seed; no capsule grant at scoped or sealed reaches ~/.murmur/keys.
The chain. Every trace.jsonl line ends with a "prev_hash" key naming the line_hash of the line before it (GENESIS on line 1), written through one InlineChain per file however many appenders hold it. hooks/eval.jsonl, completion.json and a conversation record keep their bytes as written; their chain is the list of line hashes in the seal.
The seal (Seal): <stream>.seal beside the stream, signing the chain’s head, line count, stream name and sealing session with the host key, written temp-and-rename.

verify_session_records checks every stream of one records directory with a public key alone and reports a Verdict per stream and for the whole record.

What is not sealed: a records directory’s home/, tmp/, logs/, out/ and blobs/ (blobs are named by their own sha256). Deleting a stream together with its seal reads as Verdict::Absent.

Structs§

ChainHead: A chain’s head after its last line: GENESIS and 0 for an empty file.
ConversationPointer: trace.jsonl.seal’s pointer to the conversation record its session appended to. Not signed.
HostKey: The host’s record-seal key pair. Only the mur process holds one.
InlineChain: One trace.jsonl’s chain, shared by every appender holding the same file.
PublicKey: A public key a seal is checked against, with the id seals name it by.
PublicKeyReport: The key a record was checked against.
RecordReport: A whole records directory’s verdict: mur trace verify --json.
Seal: One <stream>.seal file.
SealedHead: What a session-end seal hands the OTel capsule.session span.
StreamReport: One stream’s verdict.

Enums§

Verdict: How a stream, or a whole record, reads. Ordered best to worst; the worst wins.

Constants§

CHAIN_INLINE: chain of a seal whose stream carries its own prev_hash on every line.
CHAIN_LISTED: chain of a seal that lists every line’s hash itself.
CLI_SEALER: The session_id a conversation seal carries when no session rewrote it: mur conversation truncating a record from the command line.
COMPLETION_STREAM: A delegated child’s outcome, relative to its records directory. Sealed as one “line”: the whole file’s bytes.
CONVERSATIONS_DIR: ~/.murmur/conversations, relative to the murmur home: where conversation records live.
CONVERSATION_STREAM_PREFIX: Prefix of a conversation record’s stream name: conversation:<record>/<context-id>.
EVAL_STREAM: The scoring hook’s stream, relative to the records directory.
GENESIS: Line 1’s prev_hash.
KEYS_DIR: ~/.murmur/keys, relative to the murmur home.
KEYS_DIR_MODE: Mode of ~/.murmur/keys.
PREV_HASH_KEY: The key every trace.jsonl line ends with.
PRIVATE_KEY_FILE: The Ed25519 seed, as 64 lowercase hex characters and a newline.
PRIVATE_KEY_MODE: Mode of PRIVATE_KEY_FILE; a key file with any group or other bit is refused.
PUBLIC_KEY_FILE: The Ed25519 public key, as 64 lowercase hex characters and a newline.
PUBLIC_KEY_MODE: Mode of PUBLIC_KEY_FILE.
REPORT_SCHEMA: schema of RecordReport, and of mur trace verify --json.
SEAL_ALGORITHM: The only algorithm a seal names.
SEAL_FORMAT: The format of every seal this build writes, and the first line of its signed message.
SEAL_SUFFIX: Appended to a stream’s file name to name its seal.
TRACE_STREAM: The trace’s stream name, which is also its file name in the records directory.

Functions§

appended_conversation: The first conversation record the session in records_dir appended to.
conversation_stream: The conversation record a session’s trace.jsonl.seal points at.
key_id_of: The first 16 hex characters of the SHA-256 of a raw 32-byte public key.
keys_dir: <murmur home>/keys.
line_hash: "sha256:" and the lowercase hex SHA-256 of bytes: one line without its newline.
listed_head: A "listed" seal’s head: "sha256:" and the hex SHA-256 of the line hashes joined by \n.
note_conversation_append: Notes that the session whose records directory is records_dir appended to the conversation record in conversation_dir, so seal_session_teardown seals it.
private_key_path: <murmur home>/keys/record-seal.key.
public_key_path: <murmur home>/keys/record-seal.pub.
read_seal: The seal beside stream_file in root, Ok(None) when there is none.
seal_conversation: Seals the conversation record in dir (.../<record>/<context-id>/conversation.jsonl) for session_id. A failure is reported and leaves the record reading as unsealed.
seal_inline: Seals stream (an inline-chained file in records_root, normally TRACE_STREAM) at its current head, signed for session_id.
seal_listed: Seals stream_file in dir_root as a listed chain: every complete line’s hash in order (the whole file as one line when whole_file, as for completion.json), written to <stream_file>.seal at mode. A failure is reported on stderr and leaves the stream reading as unsealed; it never fails the caller.
seal_session_end: The seal a session writes once session_end is on disk: trace.jsonl at its head, naming the conversation record the session appended to. Returns the head for the OTel session span.
seal_session_teardown: The seals a session writes at teardown, once its door is shut and every hook has drained: trace.jsonl again when a line landed after its last seal, hooks/eval.jsonl when it exists, and every conversation record the session appended to.
signed_message: The UTF-8 bytes a seal’s signature covers: murmur.seal/1\n<stream>\n<session_id>\n<lines>\n<head>\n.
verify_inline: Checks an inline-chained stream’s bytes against its seal.
verify_listed: Checks a listed-chain stream’s bytes against its seal. whole_file treats the file as one line, as completion.json is sealed.
verify_session_records: Checks every stream of the records directory records_dir with public_key alone.
worst: The worst of verdicts, ignoring Verdict::Absent; Absent when every one is.