smelt.fs.file_state¶

Tier: Host — Available in every runtime, including headless mode.

Cached file-state tracker used by tools to detect external modifications between reads and writes.

smelt.fs.file_state.get¶

fun(p: string): any

Look up the cached file-state entry for p. Returns { content, mtime_ms, read_range } or nil when no entry exists.

smelt.fs.file_state.has¶

fun(p: string): boolean

Return true if the file-state cache has a recorded entry for p.

smelt.fs.file_state.mtime_ms¶

fun(p: string): integer?, string?

Return the modification time of p in milliseconds since the UNIX epoch. Returns (ms, nil) or (nil, err_string) on failure.

smelt.fs.file_state.record_read¶

fun(p: string, content: string, offset: integer, limit: integer): nil

Record that p was read at byte range [offset, offset+limit) with content so subsequent staleness checks know what the agent has seen.

smelt.fs.file_state.record_write¶

fun(p: string, content: string): nil

Record that p was written with content so subsequent staleness checks see the latest state.

smelt.fs.file_state.staleness_error¶

fun(p: string, noun: string?): string?

Return an error message describing why the cached state of p is stale relative to disk, or nil if it is up to date. noun (default "file") labels the entity in the message.