Module script_cache 

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ EXTENSION — NO vendor/ COUNTERPART. rkyv-backed bytecode cache for .vim scripts, the same architecture as awkrs/strykelang/zshrs’s script_cache.

Single-file shard at ~/.cache/vimlrs/scripts.rkyv. On the 2nd+ run of a given script, lex/parse/compile is skipped — the cache hit is mmap + zero-copy ArchivedHashMap lookup + a bincode-decode of the inner fusevm::Chunk blob (the compiled program).

Storage layout (rkyv archived): ScriptShard { header: { magic, format_version, vimlrs_version, pointer_width, built_at_secs }, entries: HashMap<canonical_path, ScriptEntry> } ScriptEntry { mtime_secs, mtime_nsecs, binary_mtime_at_cache, cached_at_secs, chunk_blob }

Read path: lazy mmap, rkyv::check_archived_root validation, header magic/version/pointer-width/vimlrs-version checks, then per-entry source mtime + binary-mtime guards (any rebuild invalidates silently). Write path: flock(LOCK_EX), read-mutate-to_bytes, fsync to a .tmp.<pid>.<nanos>, atomic-rename. The cache format is versioned from day one so an old cached .vim that worked yesterday never breaks (compat-floor). ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Structs

ArchivedScriptEntry

An archived ScriptEntry

ArchivedScriptShard

An archived ScriptShard

ArchivedShardHeader

An archived ShardHeader

MmappedShard

mmap + validated *const ArchivedScriptShard. Self-referential — the pointer is valid for the lifetime of the wrapping struct.

ScriptCache

A handle to one shard file plus its writer lock.

ScriptEntry

One cached compiled script.

ScriptEntryResolver

The resolver for an archived ScriptEntry

ScriptShard

The whole shard: header + path → entry map.

ScriptShardResolver

The resolver for an archived ScriptShard

ShardHeader

Shard header: format identity + provenance.

ShardHeaderResolver

The resolver for an archived ShardHeader

Constants

SHARD_FORMAT_VERSION

Bumped on incompatible rkyv schema changes (and when the meaning of emitted builtin ids changes, e.g. the ignore-case comparison id remap).

SHARD_MAGIC

Magic header bytes — fail fast if a wrong-format file is mmap’d. (“VIML”)

Statics

CACHE

Process-wide cache rooted at default_cache_path; None when disabled or unopenable.

Functions

cache_enabled

VIMLRS_CACHE=0|false|no disables the cache entirely.

default_cache_path

Default shard path: ~/.cache/vimlrs/scripts.rkyv.

file_mtime

Source-file mtime as (secs, nsecs).

store

Store a compiled program for path (best-effort; errors ignored).

try_load

Try to load a cached CompiledProgram (the main chunk plus any user functions) for path.