Module fs 

Filesystem state sync (docs/fs-watch.md): opcodes, record codecs, and the client-side mirror reducer. Filesystem state sync wire protocol (docs/fs-watch.md).

The server maintains a canonical replica of a watched tree and streams per-client state diffs (FS_UPDATE). Clients apply records to a map and acknowledge. Snapshots and recovery are RESET … SYNC staged series; loss and overflow are not wire concepts.

All integers little-endian, tightly packed, as everywhere in the protocol.

Structs

FsMirror

The complete client obligation: apply updates, read live.

FsNode

One node in a mirrored tree.

FsOp

A metadata op (C2S_FS_OP): op selects mkdir/remove/rename; a is the primary path, b the rename destination. base/mode are used by only some ops (like LSP_QUERY’s line/col).

FsRecordIter

Iterate records in an uncompressed FS_UPDATE payload. Unknown kinds are skipped via record_len; a malformed record ends iteration (the update is applied up to that point and the rest dropped — forward-compatible with future record extensions).

FsWrite

A content write (C2S_FS_WRITE). base is the CAS precondition: the current on-disk content hash to match (non-zero), zero for create-exclusive, ignored under FS_WRITE_NO_CAS.

Enums

FsContent

FsGrepRecord

One record of an FS_GREP response.

FsRecord

One decoded record from an FS_UPDATE payload.

Constants

C2S_FS_ACK

Cumulative acknowledgement: [0x42][sync_id:2][update_id:4]

C2S_FS_FETCH

Fetch full content of one file: [0x43][nonce:2][sync_id:2][path_len:2][path:N]

C2S_FS_GREP

Content search under a root (no sync), docs/design/fs-grep.md: [0x48][nonce:2][flags:1][max_matches:2][max_per_file:2][root_len:2][root:N][query_len:2][query:N]. flags is FS_GREP_CASE_SENSITIVE | FS_GREP_REGEX; zero maxima mean the server defaults. Unlike FS_INDEX the walk does not skip ignored files — it ranks them last.

C2S_FS_INDEX

Fetch the candidate file list under a root (no sync), for client-side fuzzy search (docs/design/fs-search.md): [0x47][nonce:2][flags:1][root_len:2][root:N]. flags is reserved; nonzero answers INVALID.

C2S_FS_OP

Metadata op (mkdir/remove/rename): [0x45][nonce:2][sync_id:2][op:1][flags:1][base:16][mode:4][a_len:2][a:N][b_len:2][b:N]

C2S_FS_SEARCH

Fuzzy file search under a root (no sync): [0x46][nonce:2][limit:2][root_len:2][root:N][query_len:2][query:N]. Returns paths (root-relative) whose basename subsequence-matches query.

C2S_FS_STOP

Stop a sync: [0x41][sync_id:2]

C2S_FS_SYNC

Start (or replace) a sync: [0x40][nonce:2][flags:2][latency_ms:2][inline_max:4][path_len:2][path:N] then, when FS_SYNC_EXCLUDE is set, [exclude_len:2][exclude:M]; then, when FS_SYNC_FROM_PTY is set, [src_pty_id:2].

C2S_FS_WRITE

Write file content (CAS): [0x44][nonce:2][sync_id:2][flags:1][base:16][mode:4][content_kind:1][path_len:2][path:N][content:LZ4]

FEATURE_FS

S2C_HELLO feature bit: server supports the FS_* message family, reads and writes alike (docs/design/fs-watch.md, docs/design/fs-write.md). A read-only deployment (BLIT_FS_WRITE=0) still advertises this bit and answers FS_WRITE/FS_OP with FS_DONE_PERMISSION.

FS_CLOSED_BACKEND_FAILED

FS_CLOSED_CLIENT_REQUEST

FS_CLOSED_PERMISSION_LOST

FS_CLOSED_RESOURCE_LIMIT

FS_CLOSED_ROOT_GONE

FS_CONTENT_DELTA

FS_CONTENT_FULL

FS_CONTENT_NONE

FS_DONE_BUDGET

FS_DONE_CONFLICT

A precondition failed (CAS mismatch, create-exclusive on an existing path, conditional remove on a changed file). On CONFLICT, FS_DONE.hash carries the current on-disk hash so the client rebases without a round trip. Added in lsp’s 10 WARMING extension style.

FS_DONE_INVALID

FS_DONE_NOT_FOUND

FS_DONE_OK

FS_DONE_OTHER

FS_DONE_PERMISSION

FS_DONE_TOO_LARGE

FS_DONE_WRONG_TYPE

FS_ENTRY_DIR

FS_ENTRY_FILE

FS_ENTRY_FILTERED

Set on a directory whose enumeration skipped at least one child the sync’s exclusion rules cover (docs/design/fs-watch.md “Ignoring”). Excluded paths are absent rather than marked, so without this a client cannot tell an empty directory from a filtered one — a file browser needs it to say “some items hidden” instead of showing a folder that looks wrong.

FS_ENTRY_LINK_DIR

Set on an FS_ENTRY_SYMLINK whose target is a directory, which the sync enumerates like any other. Clients need it to know the entry is expandable: the type alone cannot distinguish a link to a directory from one to a file, and a non-recursive sync has no children listed yet to infer it from.

FS_ENTRY_NO_CONTENT

Content omitted: over inline_max or the sync did not request content.

FS_ENTRY_OTHER

FS_ENTRY_SYMLINK

FS_ENTRY_TYPE_MASK

FS_ENTRY_UNREADABLE

Entry exists but its content could not be read.

FS_ENTRY_UNSTABLE

File changed repeatedly while being read; content omitted, another upsert follows once it settles.

FS_FILE_NOT_FOUND

FS_FILE_OK

FS_FILE_OTHER

FS_FILE_UNREADABLE

FS_GREP_CASE_SENSITIVE

Match case exactly. Unset (the default) is case-insensitive.

FS_GREP_FILE_IGNORED

The file is gitignored. It still gets searched — ignore rules rank rather than filter here — but sorts after every non-ignored file.

FS_GREP_FLAGS_KNOWN

Bits a request may set; anything else answers INVALID.

FS_GREP_MAX_LINE

Longest matched line returned, in bytes; longer lines are truncated on a UTF-8 boundary so a minified bundle costs one line of wire, not one line of megabyte.

FS_GREP_NO_IGNORE

Search gitignored files too, ranked after every tracked one. Unset (the default) applies ignore rules and skips them — on a real repo that is the difference between milliseconds and seconds, because the ignored pass is what has to descend into target/.

FS_GREP_RECORD_FILE

FS_GREP_RECORD_MATCH

FS_GREP_REGEX

query is a regex. Unset (the default) treats it as a literal string.

FS_GREP_TRUNCATED

A budget clipped the search: matches exist that are not in this response. Exact — set only when something was actually dropped.

FS_GREP_WORD

Match only whole words: the pattern is wrapped in \b(?:...)\b after any literal escaping, so it composes with either mode. Same semantics as blit terminal grep --word-regexp.

FS_INDEX_MAX_COUNT

Protocol cap on S2C_FS_INDEX.count. The server’s entry budget clamps to this, and parsers treat a larger count as malformed — without it, a hostile count of tiny records could force a giant preallocation from a small frame (the decompression guard bounds bytes, not record counts).

FS_INDEX_TRUNCATED

The walk hit its entry or byte budget; the list is a prefix, not the whole tree. Clients should keep server-side FS_SEARCH for this root.

FS_MAX_DECOMPRESSED

Cap on any single LZ4-decompressed fs payload — the protocol-wide crate::MAX_DECOMPRESSED guard (docs/protocol.md). Checked against the prepended size before allocating, so a hostile or corrupt length cannot force a giant allocation (the terminal path has the same guard). Large trees arrive as many bounded updates, never one huge one; content records are bounded by the sync’s inline_max (16 MiB default).

FS_OP_HARDLINK

Create a hard link at b to the regular file at a (both wire paths under the root). base CASes on the current entry at b.

FS_OP_MKDIR

FS_OP_MKPARENTS

FS_OP_NO_CAS

FS_OP_REMOVE

FS_OP_RENAME

FS_OP_SYMLINK

Create or retarget a symlink at b whose target is the verbatim string a (not a wire path; not confined to the root). base CASes on the current entry at b — a symlink’s content hash is BLAKE3-128 of its target bytes (docs/design/fs-write.md “Links”).

FS_RECORD_DELETE

FS_RECORD_MOVE

FS_RECORD_UPSERT

FS_STATUS_NOT_FOUND

FS_STATUS_OK

FS_STATUS_OTHER

FS_STATUS_PERMISSION_DENIED

FS_STATUS_RESOURCE_LIMIT

FS_SYNC_CONTENT

FS_SYNC_CROSS_FILESYSTEM

FS_SYNC_DOTIGNORE

Honor .ignore in and above the root — ripgrep’s convention, which a project uses to hide things from tooling without telling git to stop tracking them. Separate from GITIGNORE because the two answer different questions, and .ignore brings none of git’s repository-wide sources with it. FS_INDEX and FS_GREP apply both together; a sync picks.

FS_SYNC_EXCLUDE

A trailing [exclude_len:2][exclude:M] carries client patterns — gitignore syntax, one per line, anchored at the sync root and applied above every other rule, so !keep re-includes. The flag is what makes the field parseable, and what makes a server too old to filter refuse the sync outright instead of silently mirroring the whole tree.

FS_SYNC_EXCLUDE_GIT

Omit every entry whose final component is exactly .git — directory or gitfile — from enumeration, hashing, hints, and records. A pure name filter: no git data is read (docs/design/fs-watch.md “Ignoring”).

FS_SYNC_EXCLUSION_FLAGS

Every exclusion flag, which is also the set SINGLE rejects.

FS_SYNC_FLAGS_KNOWN

Bits a C2S_FS_SYNC may set; anything else answers with the unknown-flags refusal.

FS_SYNC_FROM_PTY

Resolve the sync’s base directory from a pty’s live cwd: a trailing [src_pty_id:2] names a pty and the server joins path onto its cwd (docs/ide.md Decision 3). It comes last, after any EXCLUDE field.

FS_SYNC_GITIGNORE

Honor .gitignore in and above the root, plus the governing repository’s $GIT_DIR/info/exclude, the user’s core.excludesFile, and its core.ignorecase. Off by default, so a sync only narrows when asked.

FS_SYNC_HEADER

Fixed part of C2S_FS_SYNC, up to and including path_len.

FS_SYNC_ID_INVALID

sync_id reported by a failed FS_SYNCED.

FS_SYNC_RECURSIVE

FS_SYNC_SINGLE

The sync root is a single FILE, not a directory: the mirror holds exactly one entry — the root itself — keyed by the empty relative path “” (the same key a directory sync gives its root). Combining with RECURSIVE is invalid, and a directory root answers the invalid-path error (docs/design/fs-watch.md “Single-file sync”). Content, inline_max, FS_FETCH, and the write family behave as for any other sync, addressing path “”.

FS_UPDATE_RESET

Begin a staged snapshot: apply this and subsequent records to an empty staging map instead of the live map.

FS_UPDATE_SYNC

Atomically replace the live map with the staging map (no-op without one).

FS_WRITE_CONTENT_DELTA

FS_WRITE_CONTENT_FULL

FS_WRITE_DURABLE

fsync the file and its parent (F_FULLFSYNC on macOS) before returning.

FS_WRITE_FOLLOW_SYMLINK

Write through a final-component symlink whose resolved target stays under the root; default refuses one.

FS_WRITE_MKPARENTS

Create missing parent directories.

FS_WRITE_NO_CAS

Ignore base; unconditional overwrite/create (“Save As, replace”).

S2C_FS_CLOSED

Sync terminated: [0x43][sync_id:2][reason:1]

S2C_FS_DONE

Write/op result: [0x44][nonce:2][status:1][hash:16][mtime_ns:8]

S2C_FS_FILE

Fetch response: [0x42][nonce:2][status:1][data:LZ4]

S2C_FS_GREP

Grep result: [0x47][nonce:2][status:1][flags:1][detail_len:2][detail:N][records:LZ4] where the decompressed payload is a [record_len:4][kind:1][..] stream of FILE/MATCH records (docs/design/fs-grep.md). Status is the unified table (FS_DONE_*); detail carries a regex compile error on INVALID.

S2C_FS_INDEX

Index result: [0x46][nonce:2][status:1][flags:1][count:4][paths:LZ4] where the decompressed payload is repeated{ [path_len:2][path:N] }, root-relative, sorted. Status is the unified table (FS_DONE_*).

S2C_FS_SEARCH

Search result: [0x45][nonce:2][status:1][count:2] repeated{ [path_len:2][path:N] }

S2C_FS_SYNCED

Sync accepted or rejected: [0x40][nonce:2][sync_id:2][status:1][detail_len:2][detail:N] On success detail is the canonical root (UTF-8); on failure a diagnostic.

S2C_FS_UPDATE

State diff: [0x41][sync_id:2][update_id:4][flags:1][records:LZ4]

Functions

append_fs_grep_record

Append one record to an uncompressed FS_GREP records buffer.

append_fs_record

Append one record to an uncompressed FS_UPDATE records buffer.

apply_fs_delta

Apply a content delta (LEB128 COPY/INSERT instruction stream) to a base.

fs_done_status_text

Human-readable name for an FS_DONE status code.

fs_grep_records

Decode an uncompressed FS_GREP records buffer. Unknown kinds are skipped via record_len; a record whose body overruns ends the stream, matching the TypeScript mirror.

fs_records

fs_sync_exclude

Client exclude patterns from a C2S_FS_SYNC — "" when EXCLUDE is unset. None means malformed: a truncated field or non-UTF-8 patterns.

fs_sync_flags

The flags field of a C2S_FS_SYNC, or None if it is truncated.

fs_sync_flags_valid

C2S_FS_SYNC flag-combination validity: SINGLE syncs exactly one file, so RECURSIVE contradicts it and the pair is rejected at validation (docs/design/fs-watch.md “Single-file sync”). The exclusion flags apply to enumeration, which SINGLE does none of, so they are rejected with it too rather than silently doing nothing.

fs_sync_rebase

Rebase a FROM_PTY C2S_FS_SYNC onto a resolved cwd: join cwd/path and clear FROM_PTY, producing a plain path-based sync the handler consumes unchanged. cwd None (source pty gone) keeps path verbatim. Any exclude field rides along — the filter is the client’s, not the pty’s, and dropping it here would silently widen the sync.

fs_sync_src_pty

Extract the trailing src_pty_id from a FROM_PTY C2S_FS_SYNC; None when the flag is unset or the field is missing.

fs_update_records

Decompress an FS_UPDATE’s records buffer (for consumers that want the records themselves, e.g. event display), with the standard guard.

msg_fs_ack

msg_fs_closed

msg_fs_done

Build an S2C_FS_DONE. On success hash/mtime_ns are the post-op stat; on CONFLICT, hash is the current on-disk hash.

msg_fs_fetch

msg_fs_file

msg_fs_grep

Build a C2S_FS_GREP.

msg_fs_grep_result

Build an S2C_FS_GREP from an uncompressed records buffer.

msg_fs_index

Build a C2S_FS_INDEX.

msg_fs_index_result

Build an S2C_FS_INDEX result. paths should be root-relative and sorted — sorted lists share prefixes, which is what makes the LZ4 payload small.

msg_fs_op

msg_fs_search

Build a C2S_FS_SEARCH.

msg_fs_search_result

Build an S2C_FS_SEARCH result.

msg_fs_stop

msg_fs_sync

msg_fs_sync_excluding

Build a C2S_FS_SYNC carrying client exclude patterns: gitignore syntax, one per line, anchored at the sync root (docs/design/fs-watch.md “Ignoring”). Sets FS_SYNC_EXCLUDE; an empty exclude builds the plain form instead, so a caller need not special-case “no patterns”.

msg_fs_sync_from_pty

Build a C2S_FS_SYNC whose base directory the server resolves from a pty’s live cwd: sets FS_SYNC_FROM_PTY and appends [src_pty_id:2] last (docs/ide.md Decision 3). path is joined onto the resolved cwd server-side (empty = the cwd itself).

msg_fs_sync_full

Every C2S_FS_SYNC variant, in field order. The optional trailers are self-describing through their flags — EXCLUDE first, FROM_PTY last — which is what lets a parser skip one to reach the other.

msg_fs_synced

msg_fs_update

Build an FS_UPDATE from an uncompressed records buffer.

msg_fs_write

parse_fs_done

Parse an S2C_FS_DONE into (nonce, status, hash, mtime_ns).

parse_fs_file

Parse an S2C_FS_FILE message (starting at the opcode byte) into (nonce, status, data). Applies the same decompression guard as FsMirror::apply_update; None = malformed or over-sized.

parse_fs_grep

Parse a C2S_FS_GREP → (nonce, flags, max_matches, max_per_file, root, query).

parse_fs_grep_result

Parse an S2C_FS_GREP → (nonce, status, flags, detail, records) with the records decompressed under the standard guard.

parse_fs_index

Parse a C2S_FS_INDEX → (nonce, flags, root).

parse_fs_index_result

Parse an S2C_FS_INDEX → (nonce, status, flags, paths). Applies the standard decompression guard; None = malformed, over-sized, or a payload that disagrees with count.

parse_fs_op

Parse a C2S_FS_OP. None = malformed or a non-UTF-8 path.

parse_fs_search

Parse a C2S_FS_SEARCH → (nonce, limit, root, query).

parse_fs_search_result

Parse an S2C_FS_SEARCH → (nonce, status, paths).

parse_fs_write

Parse a C2S_FS_WRITE. None = malformed, non-UTF-8 path, or content whose declared decompressed size exceeds the protocol cap.