Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
1c0a6fd
fix(daemon): flush only the export volume on macOS before Commit
jiangkoumo Nov 10, 2026
c5d5df2
fix(persistence): admit Store writes on macOS through the directory lane
jiangkoumo Nov 11, 2026
4f9a966
fix(store): keep a refused file-digest write a definite Busy Commit
jiangkoumo Nov 11, 2026
1df9185
test(store): expect the refused digest write as a definite Busy cause
jiangkoumo Nov 11, 2026
368b108
docs(architecture): describe macOS writer admission in Store pages
jiangkoumo Nov 11, 2026
c0bd28b
fix(persistence): take the directory lane for a seal on macOS too
jiangkoumo Nov 11, 2026
42aa0ca
test(api): hold the writer lane on macOS for the running-call open ca…
jiangkoumo Nov 11, 2026
97a02e1
test(store-service): cover direct open refusals on both lane platforms
jiangkoumo Nov 11, 2026
0711348
Merge docs sync for macOS writer admission
jiangkoumo Nov 11, 2026
7d2bfbd
docs(architecture): take a seal's directory lane on both lock platforms
jiangkoumo Nov 11, 2026
95d0aef
Merge upstream/layerfs_v2_0_0 into pr647-r1
jiangkoumo Nov 13, 2026
523f7fd
test: bound the concurrent-open children and make the Store fixture p…
jiangkoumo Nov 13, 2026
9030b8e
fix(persistence): hold a seal's lane across its sidecar check
jiangkoumo Nov 13, 2026
59b143f
docs(engine, api): name the export-volume flush and the Busy open
jiangkoumo Nov 13, 2026
2d4bac0
test(nfs): stop claiming the mounter test observes the flush fallback
jiangkoumo Nov 13, 2026
180ef59
docs(flows): a macOS writer waits on the directory lane too
jiangkoumo Nov 13, 2026
30c0e56
test: keep a fixture's Store in its own private directory
jiangkoumo Nov 13, 2026
5534c3e
test: stop concurrent-open child group on early failure and attach st…
jiangkoumo Nov 13, 2026
19a6398
Merge upstream/layerfs_v2_0_0 into pr647-r1
jiangkoumo Nov 13, 2026
e24c1b4
docs(architecture): port #647's macOS flush, lane and seal notes into…
jiangkoumo Nov 13, 2026
19aaeb1
docs(project-init): align the seal block's two columns
jiangkoumo Nov 13, 2026
11b30f0
fix(daemon): refuse the Commit when the macOS volume flush fails
yifanxuaaa Nov 14, 2026
7b3a375
Merge layerfs_v2_0_0 (d2f1429c05: #678, #663, #642) into fix/578-sync…
yifanxuaaa Nov 14, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions api/crates/layerfs-api/tests/store_open_cache.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
//! open copy holds a lease under its root and is closed by the steps that
//! read, replace or delete the file, so a Store is pulled back at once after a
//! write and a Store that returns is never served from a stale handle; and
//! (Linux, where a writer waits on its Store directory's lock) a call that
//! is running keeps its Store open against a push or remove.
//! (where a writer waits on its Store directory's lock, Linux and macOS) a
//! call that is running keeps its Store open against a push or remove.
use layerfs_api::home::{self, paths, write_record};
use layerfs_bridge::control::SdkValue;
use std::net::TcpListener;
Expand Down Expand Up @@ -156,9 +156,9 @@ fn a_worker_closes_its_open_copy_so_a_store_is_pulled_at_once_and_returns_fresh(
let _ = std::fs::remove_dir_all(folder);
}

/// A write waits for the Store directory's writer lock (Linux): holding it
/// here keeps one call running for as long as this test wants.
#[cfg(target_os = "linux")]
/// A write waits for the Store directory's writer lock (Linux and macOS):
/// holding it here keeps one call running for as long as this test wants.
#[cfg(any(target_os = "linux", target_os = "macos"))]
#[test]
fn a_running_call_keeps_its_store_open_against_a_push_or_remove() {
use nix::fcntl::{Flock, FlockArg};
Expand Down
1 change: 1 addition & 0 deletions control/crates/layerfs-store/src/service.rs
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ fn open(store: &Path, args: &OpenArgs) -> Result<Opened, SdkRefusal> {
.map_err(|refusal| match refusal {
OpenRefusal::Unsupported(reason) => refused("Unsupported", reason.0),
OpenRefusal::Missing(reason) => refused("NoStore", reason),
OpenRefusal::Busy(reason) => refused("Busy", reason),
OpenRefusal::Failed(reason) => refused("Failed", reason),
})
}
Expand Down
4 changes: 2 additions & 2 deletions docs/architecture/api/calls/errors-and-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ front ends carry it unchanged.
| `NoSuchPath`, `IsDirectory`, `NotDirectory`, `NotFile`, `NotEmpty`, `Binary` | path refusals of the `file` calls | [`write/mutation.rs`](../../../../engine/crates/layerfs-store-service/src/write/mutation.rs), [`read/`](../../../../engine/crates/layerfs-store-service/src/read) |
| `Exists`, `NameTaken`, `ReservedName` | a name is taken or reserved; a database already connected | [`postgresql/connect.rs`](../../../../control/crates/layerfs-store/src/postgresql/connect.rs), [`history/branch.rs`](../../../../engine/crates/layerfs-store-service/src/history/branch.rs) |
| `InUse` | held: running Sandboxes, processes with the Store open, Stores on a machine | [`open.rs`](../../../../control/crates/layerfs-store/src/open.rs), [`inventory.rs`](../../../../control/crates/layerfs-control/src/inventory.rs) |
| `Busy` | another operation runs on the entity (`detail {entity, phase, op}`), or no daemon connection came free; nothing was attempted | [`op.rs`](../../../../control/crates/layerfs-home/src/op.rs), [`daemon/pool.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/pool.rs) |
| `Busy` | another operation runs on the entity (`detail {entity, phase, op}`), no daemon connection came free, or a Store's writable open met SQLite's busy lock before any effect (the open wrote nothing, so the caller may repeat the call); nothing was attempted | [`op.rs`](../../../../control/crates/layerfs-home/src/op.rs), [`daemon/pool.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/pool.rs), [`store_service.rs`](../../../../engine/crates/layerfs-store-service/src/store_service.rs) |
| `Unresolved` | an earlier operation on the entity ended `Unknown` and its process is gone | [`op.rs`](../../../../control/crates/layerfs-home/src/op.rs) |
| `Conflict`, `HeadMoved` | a merge or Commit conflict, or the Branch head moved; for `backup.restore`, the Store changed since its last transfer | [`daemon/values.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/values.rs), [`history/lookup.rs`](../../../../engine/crates/layerfs-store-service/src/history/lookup.rs) |
| `Dirty`, `MountsActive` | unmount with uncommitted changes; `sandbox.close` while Workspaces are mounted | [`daemon/values.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/values.rs), [`lifecycle.rs`](../../../../control/crates/layerfs-sandbox/src/lifecycle.rs) |
Expand Down Expand Up @@ -100,7 +100,7 @@ The CLI refuses a wrong command line itself, with exit 2, before any call
| `Unresolved` | an earlier `Unknown` on this entity stands; this call did nothing | [`op.rs`](../../../../control/crates/layerfs-home/src/op.rs) `blocks` |
| daemon `Unknown` | a Workspace operation's outcome is uncertain at the daemon | [`control_types.rs`](../../../../engine/crates/layerfs-bridge/src/control_types.rs) `ControlCode::Unknown` |
| `Failed` with `attempted: true` after a daemon exchange | uncertain, though the code is `Failed`: a lost daemon reply is not mapped to `Unknown` | [`lifecycle.rs`](../../../../control/crates/layerfs-sandbox/src/lifecycle.rs) `operation` |
| `Busy` | known: nothing was attempted | [`op.rs`](../../../../control/crates/layerfs-home/src/op.rs), [`daemon/pool.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/pool.rs) |
| `Busy` | known: nothing was attempted, including a `Busy` Store open (the open changed nothing) | [`op.rs`](../../../../control/crates/layerfs-home/src/op.rs), [`daemon/pool.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/pool.rs), [`service.rs`](../../../../control/crates/layerfs-store/src/service.rs) |
| `Unavailable`, `Denied`, `TooLarge` from a worker | known: the request was not sent | [`worker/client.rs`](../../../../control/crates/layerfs-machine/src/worker/client.rs) (`Unreached`) |

Intents are written by
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/engine/daemon/control-calls.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ differs. `Exported`, `ExportLeaving` and `ExportKept` mirror `Ready`,
| Step | NFS route | Source |
| --- | --- | --- |
| Attach | Serve the engine mount as one loopback NFSv3 export on a fresh port; the client mounts it with the mount helper; Ready only after the helper reports the mount. The receipt has `abi_major == 0` and `mount_id` = the port | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) |
| Commit | Flush first (flush helper, or `sync(2)`), close the export's descriptors, run the unchanged Commit; after an install of another root, close them again | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs), [`invalidate.rs`](../../../../engine/crates/layerfs-daemon/src/control/invalidate.rs) |
| Commit | Flush first (flush helper, or the export volume's own flush: `sync_volume_np(<dir>, SYNC_VOLUME_WAIT)` on macOS, `sync(2)` elsewhere; a failed flush refuses the Commit as `Failed` at `commit:flush`), close the export's descriptors, run the unchanged Commit; after an install of another root, close them again | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs), [`invalidate.rs`](../../../../engine/crates/layerfs-daemon/src/control/invalidate.rs) |
| Unmount | Helper unmount (busy is reversible), stop the export, revoke, Close | [`export.rs`](../../../../engine/crates/layerfs-daemon/src/control/export.rs) |
| ForceUnmount | Force helper once, then the same teardown | same |
| Helper run | One attempt, at most `HELPER_WAIT` 60 s, then killed and reported | [`export_helper.rs`](../../../../engine/crates/layerfs-daemon/src/control/export_helper.rs) |
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/engine/kernel-routes/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ so NFS calls charge nothing.
| Hard links | Aliases share one serial, so one kernel inode | `fileid` is the serial | [`link.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/link.rs), [`attributes.rs`](../../../../engine/crates/layerfs-nfs/src/attributes.rs) |
| Ticket release | After the one reply attempt (fuser reports no send result) | After `write_record` returns | [`reply_order.rs`](../../../../engine/crates/layerfs-fuse/src/coherence/reply_order.rs), [`server.rs`](../../../../engine/crates/layerfs-nfs/src/server.rs) |
| After a Commit installs a root other than the one shown | `inval_inode` / `inval_entry` per stale serial or name before the answer | Mode-preserving SETATTR refresh through the client | [`invalidate.rs`](../../../../engine/crates/layerfs-daemon/src/control/invalidate.rs); [FUSE](fuse.md), [NFS](nfs.md) |
| Durability of a reply | `FLUSH`/`FSYNC`/`FSYNCDIR` answer `ENOSYS` once; the kernel then reports success and stops sending them | WRITE answers `FILE_SYNC`, meaning published; the daemon flushes the client before each Commit | [`flush.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/flush.rs), [`changing.rs`](../../../../engine/crates/layerfs-nfs/src/changing.rs) |
| Durability of a reply | `FLUSH`/`FSYNC`/`FSYNCDIR` answer `ENOSYS` once; the kernel then reports success and stops sending them | WRITE answers `FILE_SYNC`, meaning published; the daemon flushes the client before each Commit: the flush helper when set, else the export volume's own flush (`sync_volume_np(<dir>, SYNC_VOLUME_WAIT)` on macOS, `sync(2)` elsewhere); a failed flush refuses the Commit as `Failed` at `commit:flush` | [`flush.rs`](../../../../engine/crates/layerfs-mount-ports/src/operations/flush.rs), [`changing.rs`](../../../../engine/crates/layerfs-nfs/src/changing.rs) |

An install of the Workspace's own captured root sends nothing: the tree the
mount shows is unchanged. The overlay is disposable and never synchronized to
Expand Down
3 changes: 2 additions & 1 deletion docs/architecture/engine/kernel-routes/nfs.md
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,8 @@ reaches the Workspace or a Commit; everything is dropped with the export.
Attach: bind 127.0.0.1:0 -> Server::start -> port P
helper mount_nfs -o vers=3,tcp,port=P,mountport=P,... <dir>
client MOUNT MNT "/" -> root handle, AUTH_UNIX
Commit: flush helper (sync(2) by default), close_files, Commit
Commit: flush helper (else the export volume's own flush: sync_volume_np
on macOS, sync(2) elsewhere), close_files, Commit
Unmount: unmount helper (busy is reversible), Server::stop,
revoke the engine mount, Close
```
Expand Down
19 changes: 10 additions & 9 deletions docs/architecture/engine/project-init/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,19 +118,20 @@ readiness wait, not a retry ([`import/batch.rs`](../../../../engine/crates/layer
### Seal and install

```text
SqliteHandles::seal install_file --> daemon
sole session (else Busy) manifest Request, Claim
wal_checkpoint(TRUNCATE) (busy -> Busy) <= 65,519 B Transfer
close; no -wal/-shm/-journal remains per record
macOS: release unused allocation "LFSF\x01" Publish (rename)
--> SealedStore{path, profile, ..} Open, check binding
<-- Installed(manifest + daemon
SQLite version)
SqliteHandles::seal install_file --> daemon
sole session (else Busy) manifest Request, Claim
take the writer lane (Linux and macOS) <= 65,519 B Transfer
wal_checkpoint(TRUNCATE) (busy -> Busy) per record
close; no -wal/-shm/-journal remains "LFSF\x01" Publish (rename)
release the writer lane Open, check binding
macOS: release unused allocation
--> SealedStore{path, profile, ..} <-- Installed(manifest + daemon
SQLite version)
```

| Rule | Source |
| --- | --- |
| Seal consumes the sole session after `Save::finish` and publication; it is never called on a live daemon's shared Store. `initialize` then builds a `StoreManifest` and returns a `SealedProject`. | [`store/seal.rs`](../../../../engine/crates/layerfs-persistence/src/store/seal.rs), [`store/init.rs`](../../../../engine/crates/layerfs-project/src/store/init.rs) |
| Seal consumes the sole session after `Save::finish` and publication; it is never called on a live daemon's shared Store. `initialize` then builds a `StoreManifest` and returns a `SealedProject`. The lane is held across the checkpoint, the close and the sidecar check, so an opener waiting for the lane cannot create a `-wal` in the gap and turn a sealed Store into `Refused`. | [`store/seal.rs`](../../../../engine/crates/layerfs-persistence/src/store/seal.rs), [`store/init.rs`](../../../../engine/crates/layerfs-project/src/store/init.rs) |
| Install checks Disposable, file kind and length against the manifest, streams `MAX_PLAINTEXT_BYTES` records from one fixed buffer, then the finish marker; it never opens the file as a database. A reply manifest that differs from the sent one plus the daemon's SQLite version is a protocol mismatch. | [`store/install.rs`](../../../../engine/crates/layerfs-project/src/store/install.rs), [`control.rs`](../../../../engine/crates/layerfs-bridge/src/control.rs) |
| On a failure after the request was attempted the caller closes its send side (the fence), unless the failure was a channel error. | [`store/install.rs`](../../../../engine/crates/layerfs-project/src/store/install.rs) |

Expand Down
9 changes: 8 additions & 1 deletion docs/architecture/engine/store-calls/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,11 +62,18 @@ StoreService::open_direct(store, binding, cursor_key, template)
2 store.is_file() -> Missing
3 open_store_observed(sqlite, Disposable, CALLS=64, cache 64 KiB)
writer session + read-only control reader
-> Failed("Store open: ..")
-> Busy("Store open: ..") /
Failed("Store open: ..")
4 Owner::start(template, pager 4096 KiB, namespaces 64)
-> Failed("overlay template: ..")
```

A writable `Session::connect` takes the Store directory's writer lane, so two
openers queue instead of meeting SQLite's `Busy`; a `Busy` open therefore
means a writer that bypasses the lane (an uncoordinated raw SQLite process)
held the lock, and it is a definite refusal that changed nothing: the caller
may repeat the call. Any other open failure stays `Failed`.

| Field or constant | Meaning | Source |
| --- | --- | --- |
| `CALLS` = 64 | Private Workspaces one process holds at once (one per SDK binding worker thread); `bind` refuses `Capacity` at the limit. | [`store_service.rs`](../../../../engine/crates/layerfs-store-service/src/store_service.rs) |
Expand Down
Loading