ADR 0005: Private Sealed Workspaces, a Single SQLite Store, a Resident Daemon, and Honest Bus Semantics (v1.1.0)¶
Status¶
Accepted (2026-11-18). Supersedes in part ADR-0004 (the "lock-free, zero-copy /dev/shm" description of the file-backed bus and its latency figures).
Context¶
The v1.0.0 audit (docs/claude/) found four structural problems:
- Repository-local trust (ICX-AUD-010, ICX-AUD-013). The default workspace was
.icx/inside the repository, created with mode0755and not git-ignored. A cloned repository could ship a populated.icx/, andicxwould load it and inject its content into agent context. - Persistence (ICX-AUD-001, ICX-AUD-047). State was spread over three JSON files
(
cas_store.json,mmu_state.json,bitemporal_graph.json) that were rewritten in full and could not be replaced atomically as a set. Every hook reloaded them and re-encoded the HDC index, so hook cost grew with workspace size (940 ms at 338 artifacts). - Per-hook process cost. Even with faster persistence, a short-lived hook process must load the workspace on every call.
- Bus claims (ICX-AUD-046, ICX-AUD-054, ICX-AUD-055). ADR-0004 and the specification described
a lock-free, memory-mapped, zero-copy
/dev/shmring. The cross-process backend uses positional file I/O under a writer mutex and file lock on a file in the workspace, and dropped events were reported as successful publishes.
Decision¶
- Per-user, sealed workspaces outside the repository. The default workspace is
<state_dir>/workspaces/<first 16 hex of blake3(canonical project root)>, withstate_dirfromICX_STATE_HOME,$XDG_STATE_HOME/icxor~/.local/state/icx. Every workspace (default,--dir,ICX_DIR) must be owned by the effective uid, have no group/other permission bits, and carry anOWNERseal: a keyed BLAKE3 MAC of its canonical path under a per-install key ($XDG_CONFIG_HOME/icx/install.key,0600). A repository-local.icx/is never loaded implicitly;icx trust --dir <path>adopts an existing directory explicitly. No shared-directory fallback is used when no private root can be determined. - A single SQLite store with a MAC. All workspace state lives in one
icx.sqlite3file (WAL,0600): append-only CAS chunk and artifact rows, plusmetarows for derived state, including a binary HDC snapshot (ICXHDC03). Every save is one transaction and increments ageneration. Every save writes a store seal, a keyed BLAKE3 MAC over the canonical path, the generation and a digest of all persisted state; a sealed load rejects a store whose MAC does not verify. v1.0.x JSON workspaces are migrated on first load and left in place. - A resident daemon.
icx daemonkeeps one workspace in memory and servesicx hookrequests over a Unix socket in$XDG_RUNTIME_DIR/icx(0700), accepting only peers with the same uid (SO_PEERCRED). It replies first and flushes after 50 ms without requests (at most 1 s), holding the workspace lock while it has unsaved changes, so it is the single writer.icx hookuses the daemon when one is running and falls back to in-process handling otherwise. - Honest bus semantics. The specification describes two backends: an in-process atomic
seqlock ring, and a file-backed ring using
pread/pwriteunder a writer mutex and advisory file lock with optimistic lock-free readers. It is not memory-mapped and not zero-copy, and it is on/dev/shmonly ifICX_SHM_PATHpoints there. Publishing can fail (SlotLapped,SlotContended);publishcounts drops (dropped_publishes), and readers can learn how many events they missed (poll_since_with_loss). The bus file is opened withO_NOFOLLOW | O_CLOEXECand refused if not a private regular file owned by the user.unsafe_code = "forbid"is kept, which rules outmmap.
Consequences¶
- Positive: A cloned repository can no longer supply trusted context, and other local users cannot read workspaces. Saves are atomic; editing any persisted row of a sealed store is detected. Measured hook cost: 338 artifacts 940 ms to 14 ms in-process; about 2,000 artifacts 69 to 72 ms in-process and a median of 3.1 ms through the daemon. Bus documentation matches the code, and event loss is observable.
- Negative: Workspaces are no longer visible next to the project, and a copied or moved
workspace must be re-trusted because the seal binds the canonical path. Existing v1.0.x
.icx/directories need an expliciticx trust. The daemon is an additional long-lived process, and a request that overlaps a flush takes about 19 ms. File-backed bus writers can wait on the file lock (up to about 250 ms before failing), and measured file-backed propagation is tens of microseconds (worst 38 µs over 200 events), not the sub-microsecond figures in ADR-0004. - Unchanged limits: Same-user processes are trusted; they can read the install key and forge seals. See docs/security-and-threat-model.md §5.