Crate graphrefly_core 

GraphReFly handle-protocol core dispatcher.

This crate is the heart of the protocol: dispatcher, message tiers, batch coalescing, wave engine, dep tracking, equals-substitution, first-run gate, PAUSE/RESUME with lockIds, INVALIDATE broadcast, versioning lifecycle, atomic dep mutation (set_deps).

It operates entirely on opaque HandleId integers — user values T never enter the core. Per-language bindings (napi-rs for JavaScript, pyo3 for Python, wasm-bindgen for WASM) hold the value-to-handle registry. Equals-substitution under EqualsMode::Identity is a u64 compare with zero FFI; user-fn invocation is the only mandatory boundary crossing per fn fire.

Status (2026-05-03)

M1 first slice — warm-up modules (message, handle, clock, boundary). The dispatcher itself, batch engine, PAUSE/RESUME, and set_deps follow incrementally. See ~/src/graphrefly-ts/docs/implementation-plan.md Phase 13.7 for the full slice plan; reference impl at ~/src/graphrefly-ts/src/__experiments__/handle-core/.

Safety

No unsafe is permitted in this crate or anywhere in the workspace. Enforced by #![forbid(unsafe_code)] at the root. See CLAUDE.md Rust invariant 1.

Re-exports

pub use boundary::BindingBoundary;

pub use boundary::CleanupTrigger;

pub use boundary::DepBatch;

pub use boundary::FnEmission;

pub use boundary::FnResult;

pub use clock::monotonic_ns;

pub use clock::wall_clock_ns;

pub use handle::FnId;

pub use handle::HandleId;

pub use handle::LockId;

pub use handle::NodeId;

pub use handle::NO_HANDLE;

pub use hash::sha256_hex;

pub use mailbox::CoreMailbox;

pub use mailbox::DeferFn;

pub use mailbox::DeferQueue;

pub use mailbox::MailboxOp;

pub use mailbox::SendDeferFn;

pub use message::Message;

pub use message::Messages;

pub use node::Core;

pub use node::CoreFull;

pub use node::DeferredProducerOp;

pub use node::EqualsMode;

pub use node::NodeFnOrOp;

pub use node::NodeKind;

pub use node::NodeOpts;

pub use node::NodeRegistration;

pub use node::OperatorOp;

pub use node::OperatorOpts;

pub use node::PausableMode;

pub use node::PauseError;

pub use node::RegisterError;

pub use node::ResumeReport;

pub use node::SetDepsError;

pub use node::SetPausableModeError;

pub use node::Sink;

pub use node::SubscribeError;

pub use node::SubscriptionId;

pub use node::TerminalKind;

pub use node::UpError;

pub use owned::OwnedCore;

pub use topology::TopologyEvent;

pub use topology::TopologySink;

pub use topology::TopologySubscriptionId;

Modules

boundary

The FFI surface — the only path from Core to user code.

clock

Centralised timestamp utilities.

handle

Identifier newtypes — the handle-protocol’s core type vocabulary.

hash

Synchronous SHA-256 hashing.

mailbox

CoreMailbox — the Send + Sync bridge between autonomous async producers (timer tasks) and an owned, relocatable crate::node::Core.

message

Message protocol — the unit of communication between nodes.

node

The dispatcher — node registration, subscription, wave engine.

owned

OwnedCore — the one canonical Core-ownership keystone (D246 rule 4).

timer

Tokio-based timer substrate for deferred emissions.

topology

Core-level topology-change notification primitive.

Structs

BatchGuard

RAII guard returned by Core::begin_batch.