docs(fspy): tighten Linux backend decision record

Co-authored-by: GPT-5 Codex <codex@openai.com>

Author: wan9chi

crates/fspy_shm/src/linux/README.md

@@ -1,55 +1,32 @@
 # Linux backend
 
-The Linux backend stores data in an anonymous `memfd` and uses a Linux
-abstract Unix-domain socket as a descriptor broker. The broker is a control
-plane used only when opening a view. Once mapped, all frame reads and writes
-access memory directly.
+The Linux backend stores data in a sealed `memfd`. An abstract Unix-domain
+socket broker distributes the descriptor when a process opens the mapping;
+the data path remains memory-mapped.
 
-## Requirements
-
-The fspy channel reserves a large logical region so intercepted processes can
-append without coordinating a resize. The Linux backend must:
-
-- avoid the container's `/dev/shm` mount limit,
-- avoid allocating the mapping's full logical size up front,
-- let another process open the mapping from a serialized identifier,
-- support clients that run in preload code before `main`,
-- keep data writes free of per-record syscalls, and
-- preserve already-open views when the owner stops accepting new views.
-
-The
-[`constrained_dev_shm`](../../../vite_task_bin/tests/e2e_snapshots/fixtures/constrained_dev_shm/)
-fixture captures the key constraint. It mounts a one-page `/dev/shm` and
-forces file-access tracking to write beyond that mount's capacity.
+The design must avoid `/dev/shm` quotas, allocate a large logical mapping on
+demand, support synchronous opens from preload code, and stop new opens when
+the owner is dropped without invalidating existing views.
 
 ## Options considered
 
-| Option | Decision |
-| --- | --- |
-| POSIX `shm_open` | Rejected. Linux normally places the object on `/dev/shm`, so container tmpfs limits can fault mapped writes even when the host has enough memory. |
-| Memory-map a temporary file | Rejected. It introduces path discovery, cleanup, and possible disk writeback without providing a better identifier. |
-| Inherit a `memfd` | Rejected. Every process would need to propagate the descriptor to later children and across `exec`, increasing descriptor-leak risk. |
-| Send every record through a socket or pipe | Rejected. Every file-access record would require a syscall under concurrent writes. |
-| `memfd` with descriptor broker | Selected. It avoids `/dev/shm`, preserves string-based discovery, and pays socket overhead only when a process opens a view. |
+| Option                         | Decision                                                                                                            |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| POSIX shared memory            | Rejected because Linux backs it with `/dev/shm`.                                                                    |
+| System V shared memory         | Rejected because IPC namespace quotas affect availability and segment lifetime is not tied to descriptor ownership. |
+| Sparse temporary file          | Rejected because dirty pages may reach disk and the file needs a separate lifetime protocol.                        |
+| `memfd` with descriptor broker | Selected. It avoids mount and IPC quotas while retaining descriptor-based lifetime.                                 |
 
-The broker is asynchronous so one descriptor transfer cannot stop it from
-accepting another client. Opening remains synchronous because preload code may
-run before an application provides an async runtime. Creating the owner
-requires an ambient Tokio runtime to host the broker.
+The broker accepts and serves clients asynchronously. The client is
+synchronous because it can run before `main`; creating an owner therefore
+requires an ambient Tokio runtime only on the broker side.
 
 ## Why not `shared_memory`
 
-The `shared_memory` Unix backend creates mappings with POSIX `shm_open`. Its
-API cannot accept an existing `memfd` or distribute that descriptor, so
-wrapping it would retain the `/dev/shm` dependency.
-
-Extending or forking the general-purpose crate would add more surface than
-fspy needs. The local backend only implements the descriptor, mapping, broker,
-and lifetime behavior required by the channel contract.
+`shared_memory` uses POSIX `shm_open` on Linux and cannot construct a mapping
+from a `memfd`, so it retains the `/dev/shm` dependency.
 
 ## Lifetime semantics
 
-Dropping the owner stops the broker, so later opens fail. Descriptors already
-delivered to other processes remain valid, and their mapped views stay usable
-independently of the owner. Neither the `memfd` nor the abstract socket needs a
-filesystem pathname or cleanup file.
+Dropping the owner stops the broker. Existing views remain valid; later opens
+fail.