hanzoai/dev
2
0
Fork 0
mirror of https://github.com/hanzoai/dev.git synced 2026-10-17 15:34:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(dev): say at restore what a checksum does not prove

Browse Source 
A snapshot's checksum catches a store that lost or changed bytes. It says
nothing about whether the sequence the snapshot restores agrees with the host's
journal, and a snapshot older than the journal mints again ids the host has
already dispatched under — the one way to run an effect twice that the id ledger
cannot see from inside.

That warning lived only on pack(). It is now at the three doors a host author
opens to restore a session — Session::restore, dev_restore and dev.h — each
pointing back to pack() for why the check is the host's.

Co-authored-by: Hanzo Dev <[email protected]>
This commit is contained in:
zeekay
2026-09-18 22:42:51 -07:00
co-authored by Hanzo Dev
parent d98844f76a
commit 04bb3f4da6
3 changed files with 17 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/core/src/lib.rs
+6
View File
@@ -153,6 +153,12 @@ impl Session {
}
/// Rebuild a session from its snapshot.
///
/// A checksum that matches proves the bytes are intact, not that the
/// sequence agrees with the host's journal: a snapshot older than the
/// journal mints again ids the host has already dispatched under. Reconcile
/// [`Session::next_id`] with the journal before dispatching — see
/// [`dev_protocol::pack`].
pub fn restore(state: &[u8]) -> Result<Self, Malformed> {
dev_protocol::unpack(state)
}
crates/ffi/include/dev.h
+5 -1
View File
@@ -64,7 +64,11 @@ int32_t dev_step(uint64_t session, const uint8_t *event, size_t len, dev_buf *ou
/* Write the session's snapshot to out. */
int32_t dev_snapshot(uint64_t session, dev_buf *out);
/* Rebuild a session from a snapshot; writes its new handle to out. */
/* Rebuild a session from a snapshot; writes its new handle to out. DEV_OK
* proves the bytes are intact, not that the sequence agrees with the host's
* journal: a snapshot older than the journal mints again ids the host has
* already dispatched under. Reconcile the ids this session answers with
* against the journal before dispatching one (see `pack` in dev-protocol). */
int32_t dev_restore(const uint8_t *state, size_t len, uint64_t *out);
/* End a session and retire its handle. */
crates/ffi/src/lib.rs
+6
View File
@@ -190,6 +190,12 @@ pub unsafe extern "C" fn dev_snapshot(session: u64, out: *mut Buf) -> i32 {
/// Rebuild a session from a snapshot and write its new handle to `out`.
///
/// [`DEV_OK`] proves the bytes are intact, not that the sequence agrees with
/// the host's journal: a snapshot older than the journal mints again ids the
/// host has already dispatched under. Reconcile the ids this session answers
/// with against the journal before dispatching one — see
/// [`dev_protocol::pack`].
///
/// # Safety
/// `state` must be valid for `len` bytes unless `len` is zero, and `out` must
/// be writable.