Module offload 

v0.7.0 QW-3 — context-offload substrate primitive.

Substrate plumbing for the offload+deref pattern absorbed from the Tencent comparison (2026-05-15). The FULL pattern (Mermaid canvas, auto-cadence, node_id integration) targets v0.8.0; this module ships the substrate so v0.8.0 has plumbing to call.

Pipeline

• SHA-256 over the original bytes (decompressed) is the integrity commitment.
• ref_id format: ofl_<base32-of-sha256-first-8-bytes>. 13 chars of payload after the ofl_ prefix — short enough to keep in an agent’s working window, long enough that a 40-bit prefix collision is vanishingly rare for typical fleet scales.
• Body compressed with zstd level 3 — matches memory_transcripts (the existing sidechain transcripts pipeline) for cross-codebase parity.
• Ed25519 signature is over the canonical bundle { ref_id, content_sha256, stored_at, namespace } encoded as deterministic CBOR (RFC 8949 §4.2.1). Same encoder family as identity::sign::canonical_cbor (the H2 link signer).
• A sibling row lands in signed_events with event_type = context_offloaded or context_dereferenced, binding the substrate write into the H5 audit chain.

Tamper handling

deref recomputes the SHA-256 of the freshly-decompressed bytes and refuses with OffloadError::IntegrityFailed when it disagrees with the stored content_sha256. The signature is verified against the storing agent’s public key when that key is provided to the offloader at construction; absent the key, the integrity check alone is the load-bearing tamper guard.

Out of scope (v0.7.0)

• Mermaid canvas integration (v0.8.0).
• Auto-cadence trigger from the recall pipeline (v0.8.0).
• node_id cross-link into the memories table (v0.8.0).

Structs

ContextOffloader

Substrate-level engine for offload+deref. Composed from the caller’s keypair, the existing SQLite connection, and the OffloadConfig defaults.

DerefResult

Outcome of ContextOffloader::deref. Returns the original (decompressed) content alongside the metadata that committed it.

OffloadConfig

Static configuration consumed by ContextOffloader.

OffloadResult

Outcome of ContextOffloader::offload. Callers persist ref_id and discard the content payload — that is the whole point of offload+deref.

Enums

OffloadError

Domain errors callers may want to discriminate on (size limits, integrity failures, signature mismatches). All other failure modes bubble through anyhow::Error. Display and std::error::Error are implemented by hand to avoid pulling the optional thiserror crate into the default feature set.

Constants

DEFAULT_MAX_OFFLOAD_BLOB_BYTES

Default per-blob byte limit when no namespace policy override is set. 1 MiB — Tencent’s offload primitive uses ~256 KB chunks; 1 MiB gives headroom for batched tool outputs without crossing the hostile-bomb threshold above.

MAX_DECOMPRESSED_BYTES

Hard cap on the decompressed size of a single offloaded blob. Same 16 MiB ceiling the transcripts module enforces — defends against pathological zstd bombs landing through deref. v0.8.0 may raise this for the Mermaid-canvas use case after threat-modelling.

Functions

sweep_expired

Daily TTL sweep. Removes every blob whose stored_at + ttl_seconds < now. Bounded to max_per_run rows per call so a pathological backlog can’t monopolise the connection; callers (the daemon background loop) re-invoke at the configured cadence.