v0.1.7: competitive result against v0.1.6 behind FUSE — mount and first-read latency on matched semantics

[yifanxuaaa]

Status: Not started; no measurement exists on either side for the number this issue is about. Filed 2026-09-20 from the #205/#190 attribution round (ledger L53).

Related: #179 (projection/runtime, the FUSE design this depends on) · #205 (where the gap was measured) · #190 (read path) · #70 (FUSE request overhead, older numbering).

The requirement

The replacement core must be competitive with v0.1.6 behind a FUSE projection, measured on matched semantics. Today it is not comparable, and the reason is a scope difference rather than a demonstrated slowness — so the first deliverable is a matched comparison, not an optimization.

Why this is not yet a comparison

v0.1.6's recorded create phase — create_workspace_session, the FUSE mount — is 9–11 ms, and it is flat across history depth (issue154/final-complete-matrix.json):

case	create (mount)	commit
boundary-cycle k10 → k100	11.14 → 9.14 ms	3.19 → 3.11 ms
large-hotset k10 → k100	10.17 → 9.77 ms	3.44 → 3.06 ms
namespace-inode k10 → k100	9.90 → 9.82 ms	4.31 → 4.15 ms

That call materialises no content: it pins the branch, creates a state dir, attaches the projection and reads initial tree metadata (crates/layerfs-workspace/src/lifecycle.rs:452). Construction on the legacy side happens inside Commit/push.

The replacement core, by contrast, pays eagerly and inside the measured operation: at stride10 content 1.585 s, filesystem 5.146 s, accept_loop 8.820 s — for work the FUSE design defers to first read.

  v0.1.6 mount  = branch pin + dir + attach + tree-metadata read   ->  9-11 ms
  core (today)  = construct every changed path + rebuild + publish ->  1.04-5.15 s / state
  v0.1.6 first read after mount                                    ->  NEVER MEASURED

So "9–11 ms vs 1–5 s" measures a lazy mount against an eager materialisation, and the decisive half is missing on both sides. v0.1.6's historical_access family is exactly the missing operation — mount a retained state, perform declared reads — and it declares performance N/A in all six cases. No read-after-history case has ever been run on the core either.

Acceptance criteria

1. A core FUSE-backed projection exists per v0.1.7 co-design pair 1: projection and runtime — FUSE against the workspace accumulator #179 and can be measured on the retained-history corpus.
2. A mount node, so the core has a direct counterpart to v0.1.6's 9–11 ms. Expectation from measured neighbours (store.create 4–5 ms) is single-digit to low-double-digit ms; that is an expectation to test, not a number to claim.
3. First read after mount, measured, with the read fraction declared — the fraction of the stored history the workload actually touches. This is the number that decides the trade and it currently exists nowhere.
4. A matched v0.1.6 figure for the same operation (its deferred read cost), or an explicit statement that the comparison is unmatched and no speed claim is made.
5. Both axes reported where the design trades space for time, per the owner's standing ruling.

The condition the requirement must be stated with

FUSE relocates this cost; it does not delete it. Ingest still has to construct and admit whatever it serves. The trade is decided by the read fraction:

workload shape	expected outcome
reads a small fraction of what it stores	FUSE wins — v0.1.6's shape
reads most of what it stores	FUSE loses — same construction, plus fault/round-trip overhead

This lane's history-stride1 row is the second shape (904,143 path-states, 4,936,693,030 bytes of cumulative logical history, 217,646 changed paths). So "competitive with v0.1.6" is only meaningful once the read fraction is fixed; the honest target is a crossover curve, not a single number.

What must not happen

• No cost moved into setup to make the timed region look fast. Deferring construction to read time is legitimate design; moving it outside the timer is not. The rule is the same as the harness's: if a phase's work is going to happen, the phase that is measured must pay for it.
• No invented cold stance, no pre-touched inputs, no shrunk selection, and no comparison against a v0.1.6 number measured on a different corpus or a different operation.
• No percentage or shortfall claim from unmatched arithmetic. The historical 11,370,679,212 ns is v0.1.6's Commit, excludes its fixture install and workload exec, and is not a matched figure.
• Preserve authentication, bounds, error/visibility behaviour and the single construction worker.

Open questions for the owner

1. Is the core's eager filesystem cost intended? It is what makes the Store dedupe a whole history in one operation — this lane's actual claim — so it is not obviously a defect.
2. Which read fraction defines "competitive"? Without a ruling the requirement cannot be satisfied or failed.
3. Does the v0.1.6 side get re-measured for the deferred read (a matched arm), or is the comparison declared unmatched and closed as descriptive only? The scaling handoff currently says do not rerun v0.1.6 for the v0.1.7: retained-history read optimizations and remaining qualification gaps #190 continuation; that constraint needs an explicit exception if criterion 4 is to be met.

[yifanxuaaa]

How v0.1.6's live FUSE mechanism actually works — diagrams, from source

Read from the reference source at codex/190-pooled-scope. Everything below is structural, from code; the only measured numbers are marked [MEASURED] and come from this lane's runs or issue154/final-complete-matrix.json. There are no new latency claims here — the point is to fix the mechanism's shape before #207 measures it.

1. Read path — the map is cached, the territory is selectively prefetched

  kernel  read(2)/stat(2)/readdir(3)/execve(2)
     │
     ▼
┌──────────────────────── FUSE (crates/layerfs-fuse) ─────────────────────────┐
│                                                                             │
│   namespace / inode / attr queries                                          │
│     └──► LiveWorkspace nodes + DirectoryLookupCache         ──── CACHED     │
│                                                                             │
│   file content                                                              │
│     ├── edited this session ──► piece tree + host spool     ──── LOCAL      │
│     │                                                        (on disk)      │
│     └── immutable (FileData::Base)                                          │
│           ├── len ≤ 8 KiB ──► PREFETCHED into host backing  ──── CACHED     │
│           │                   live_backing.rs:81                            │
│           └── len > 8 KiB ──► SnapshotReader                ──── UNCACHED   │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │ miss
                     ┌─────────────▼──────────────────┐
                     │  SnapshotCache                 │
                     │  8 MiB FIFO  (workspace.rs)    │
                     │  ✗ SKIPS >1 KiB chunks:        │
                     │    "large content chunks must  │
                     │     not displace the metadata  │
                     │     needed to locate them"     │
                     └─────────────┬──────────────────┘
                                   │ miss
                     ┌─────────────▼──────────────────┐
                     │  overlay (uncommitted writes)  │
                     └─────────────┬──────────────────┘
                                   │ miss
                     ┌─────────────▼──────────────────┐
                     │  db.read_object_row(id)        │  objects.rs:3852
                     │   location lookup              │  ✗ no cache beneath
                     │   + visit_locations → pack     │
                     └────────────────────────────────┘

The load-bearing constant is IMMUTABLE_PREFETCH_FILE_BYTES = 8 * 1024 (crates/layerfs-fuse/src/live_wire.rs:17). It splits the workload in two:

	tier	consequence
≤ 8 KiB immutable	prefetched into host backing	cheap, cached
> 8 KiB immutable	SnapshotReader, uncached at every layer	pays on every read

So ls -R, find, git status live in the cached band. grep -r over large files, and execve of any binary above 8 KiB, live in the uncached band and re-pay per invocation.

Correction to something I posted earlier in this thread: I said v0.1.6 had no prefetch and that the prefetch counters were dead code. The counters are dead (small_file_prefetch_eligible, small_file_prefetch_bytes, anchor_prefetch_count, snapshot_store_wide_scans each have exactly one reference — their own declaration), but the prefetch itself is real at live_backing.rs:81. I was wrong, and the 8 KiB threshold is the number that matters, not the telemetry fields.

2. Write path — where the accumulator actually is

  kernel  write(2)/create(2)/mkdir(2)/rename(2)/unlink(2)
     │        per-call, concurrent, UNORDERED
     ▼
┌──────────────────────────────────────────────────────────────────────────┐
│  LiveWorkspace  (crates/layerfs-workspace-core)                          │
│                                                                          │
│   write() → prepare_write(node, offset, bytes, spool_slice)              │
│              • validates bounds, bumps inode revision                    │
│              • mutates the piece tree          ← in-memory, fast         │
│              • bytes land in the HOST SPOOL    ← on disk, bounded        │
│                                                                          │
│   create/mkdir/unlink/rename → live tree namespace ops                   │
│                                                                          │
│   NO STORE TRAFFIC ON THIS PATH.                                         │
│   "DB traffic happens at four events: create · commit · merge · end"     │
└───────────────────────────────────┬──────────────────────────────────────┘
                                    │  accumulated, unordered
                                    ▼
                        ┌───────────────────────────┐
                        │  COMMIT POINT             │
                        └───────────┬───────────────┘
                                    ▼
                        ┌───────────────────────────────────────┐
                        │  CaptureState::Running                │
                        │   sender + thread (capture.rs)        │
                        │   construct_stream → chunk/hash       │
                        │   → CapturedFile{root, objects}       │
                        │   → DeferredObjectStore               │
                        └───────────┬───────────────────────────┘
                                    │ atomic publish
                        ┌───────────▼───────────────────────────┐
                        │  Store: canonical objects + packs     │
                        └───────────────────────────────────────┘

This is the answer to pair 1's "where does the accumulator live". The gap between FUSE's per-call unordered mutations and C1's demand for sorted, unique, complete per-directory bindings is closed by three stacked mechanisms, not one:

1. the live piece tree — in-memory edits, the mutable view;
2. the host spool — the bytes, on disk, bounded;
3. the capture thread — construction, deferred to the commit point.

3. The same operation in both systems

  "mount a workspace, then read a 1 MiB file that already exists"

  v0.1.6  ─────────────────────────────────────────────────────────────
     create_workspace_session                     9-11 ms   [MEASURED]
       branch pin + dir + FUSE attach + tree metadata read
     ─────────────────────────────────────────────────────────
     first read of that file                      per read  [from code]
       SnapshotReader → cache MISS (>8 KiB)
       → SQLite lookup → pack extract → authenticate
       → and AGAIN on every subsequent read

  core    ─────────────────────────────────────────────────────────────
     content   (construct the file)                1.585 s   [MEASURED]
       = 1.039 s construction + ~0.55 s predecessor reads
     filesystem (build + publish the tree)         5.146 s   [MEASURED]
     accept_loop (store the objects)               8.820 s   [MEASURED]
     ─────────────────────────────────────────────────────────
     read of that file                             ~0        [structural]
       already a canonical object, already stored

The asymmetry in one line: v0.1.6's mount is fast because it reads a map a previous Commit already paid to build; the core's construction is slow because it is that Commit. They are not the same operation, which is why the 10 ms vs 1–5 s comparison is not a speed comparison.

4. Why this is a crossover, not a winner

  total cost
     │
     │                                        ╱  core: eager
     │                                       ╱   pays once, up front
     │                                      ╱
     │                                     ╱
     │  v0.1.6: lazy                     ╱
     │  ┌───────────────────────────────╱──────────────────
     │  │ flat mount (9-11 ms)         ╱
     │  │ + rising per-read line      ╱
     │  │                            ╱
     │  │                           ╱
     │  └──────────────────────────╱───────────────────────
     │                          ╱
     │                        ╱
     └──────────────────────╳──────────────────────────────► reads
                          crossover
                    (unmeasured on both sides)

  left of crossover:  read a few files → v0.1.6 wins (never built the rest)
  right of crossover: read everything  → core wins   (built once, read free)

This lane's own workload sits far right — 904,143 path-states over 4,936,693,030 bytes of cumulative history, reading everything — which is why the core's eager cost is the correct bill for that workload rather than a defect.

5. What this implies for #207 and pair 1

A concrete first experiment, testable before any crossover curve exists: measure execve latency for a binary above 8 KiB, repeated. It is the most common shell operation, it falls in the uncached band by construction, and it is the case where an eager model should win outright. If the core cannot beat a lazy loader there, it will not beat it anywhere.

For pair 1's open design items, these diagrams supply two of them:

• "Overlay byte ceiling" and "flush policy" — the reference's answer is the host spool with a high-water mark (spool_high_water, spool_bytes_peak) and construction deferred to commit. That is a working precedent to price, not a guess.
• "Where the accumulator lives" — three tiers, above. A second projection (materialization) would share tier 1 and 2 and not tier 3, which is the trade pair 1 has to decide.

Unchanged bounds: these are structural readings of reference source, not measurements of the core; nothing here claims a core-side number, and the [MEASURED] figures are the ones already receipted in this lane and in issue154. No v0.1.6 re-run was performed and none is proposed.

[yifanxuaaa]

Handoff prompt written and pushed: issue207-fuse-enablement-handoff.md

It carries the three investigations this issue needs, design-first per #179's boundary ("no claim in this pair is measurable until a mount exists"):

1. How to enable FUSE — the operation set mapped onto C1/C2 calls, mount topology, the accumulator's home, the numeric overlay ceiling and flush policy, and the 4,096-binding rename ceiling a shell's mv will find. Plus the staging question that decides the rest: the reference's 8 MiB cache and 8 KiB prefetch threshold were tuned with reader and store co-located, and pair 3's topology inserts a process boundary and a transport, which makes those constants unjustified rather than wrong.
2. How to make it universal across host / Docker / remote — reusing pair 3's portability requirements and adding the four things FUSE must contribute, including round-trip count per operation as a first-class metric and behaviour under a slow or dead peer.
3. How to incorporate with pair 3 — the authoritative order is pair 3 → pair 1 → pair 2, and pair 3's component table constrains the design in three ways: the bridge must not own "automatic mutation replay", so the accumulator cannot live there; C1/C2 stay together at the host, so canonical objects may not be resolved one at a time across the bridge; and pair 1 consumes pair 3's operation surface rather than inventing a parallel one.

It names the one experiment worth running once a mount exists — repeated execve of a binary above 8 KiB, the most common shell operation and uncached by construction — and records which questions belong to #180 rather than answering them here.

[yifanxuaaa]

#207 / #179 — FUSE enablement decision set, 2026-09-20

Status: Research; informative and not a product contract. Design decisions
proposed for the next implementation rounds, not a design freeze, implemented
mount, measurement, or release admission. No builds or measurements in this
investigation. #179, #180, #181, #190, #205 and #207 remain open.

1. Basis and corrections to the handoff

Read the existing mechanism
first, at ae1d514d2; its historical receipts are carried by reference, not rerun
or relabelled. This decision set pins current product/API findings to
7b8a7d9d30cabf208229380020cd5442519574a5, the merge of
PR #200 at
2026-09-20 11:51:38 UTC. The PR is now merged, although its description still
contains earlier draft wording. Dirty work in the pair 3 and history worktrees
is excluded. Three parallel read-only investigations checked callback mapping,
pair 3 integration, and portability/resource policy.

Three source corrections materially affect this design:

• DirectoryUpdate requires sorted, unique final bindings for changed names;
  unchanged names remain in the base. A rename supplies removal/addition together,
  not a full copy of both directories. C1 input
• The 4,096-entry validation bound remains. Its cost is broader than the moved
  subtree: parent-alias validation can traverse the entire base namespace when
  rebinding a directory or symlink. Even moving a small directory in a large
  namespace can fail. Validation
• A stored canonical file is not a materialized file or a free read. The old
  mechanism document's read ~0 and guaranteed crossover language are hypotheses,
  not conclusions used here. Kernel executable/page caches also determine whether
  repeated execve calls reach the FUSE read path. Both arms still need measurement.

The implementation order remains pair 3 → pair 1 → pair 2. The shortest next
enablement round is one fixed-root, read-only Linux mount using the existing
service operations. It needs no logical Commit, new inode allocation, or
prefetch policy experiment. This is an initial capability slice; it does not
complete writable Workspace acceptance or #207's matched performance requirement.
The writable design below identifies the dependencies before its own round.

2. Consume the existing operation surface

C1/C2 stay together in the host service. FUSE calls Workspace methods; Workspace
uses the bridge's logical operations. Neither FUSE nor Workspace receives SQL,
SQLite credentials, physical pack knowledge, or a per-canonical-object RPC.
Direct and stream delivery use Service::handle. Request contract
Read handlers Write handlers
Filesystem handler

Bridge operation	Logical input/result	Service-local C1/C2 calls
Inspect::Stat	Filesystem root + relative path → serial, kind, reference count, content/metadata roots, mode, mtime; no file length	FilesystemRead::new, resolve, read_portable, C2 StoreProvider
Inspect::File	File root → logical length and representation	C1 FileView::open, C2 StoreProvider
Inspect::List	Filesystem root + path + continuation + count/byte allowance → name/serial page; no kind/attributes	C1 FilesystemRead::list, C2 StoreProvider
Inspect::Readlink	Filesystem root + path → link target	C1 FilesystemRead::readlink, C2 StoreProvider
ReadFile	File root + half-open byte range → bounded logical bytes and terminal length	C1 read_range, C2 StoreProvider; all canonical traversal remains local
ConstructFile	Declared complete input length + exact bytes → saved file root/length and inserted/reused counts	C1 construct_stream, C2 begin_save / SaveHandoff / finish
EditFile	Base file root/length + supported ordered edits + stable replacement bytes → saved file root/length and counts	C1 EditStream, apply_edits; bounded service replacement input; C2 save/finish
UpdatePreparedFilesystem	Prepared base/scope/root serial + sorted changed-name and existing-inode records → saved filesystem root and counts	C1 FilesystemInput, FilesystemObjects, update_filesystem_timed; C2 save/finish

Current filesystem updates require existing serials and set
new_inodes: &[]. They cannot allocate a file, directory or symlink, change an
inode's kind, or replace a directory root wholesale. They accept retained
metadata roots, but no operation constructs portable/generic metadata or symlink
objects. C1 exposes more public functions than the bridge does; those functions
are not permission to invent private calls. A prepared root's scope/root serial
must be supplied for writes; the current read result is not a root-descriptor API.

3. Complete callback decision set

R means served in the first fixed-root read-only mount; W describes a
later writable profile, conditional on the listed gaps. All mutations return
EROFS in R. This table covers the existing fuser 0.18 callback vocabulary;
capabilities absent from the selected Linux build are not advertised.
The adapter remains thin and platform-gated; no dependency is added this round.

Callback(s)	Decision and C1/C2 mapping, or reason for no call
init, destroy	R: configure/tear down the kernel session, authenticate/configure the existing bridge, validate the explicit root via Inspect::Stat with empty path. Local lifecycle; no filesystem construction or logical Commit.
lookup, getattr	R: bounded retained inode metadata first; miss → Inspect::Stat (resolve + read_portable). Regular-file size additionally uses Inspect::File; symlink size uses Inspect::Readlink. No separate remote resolve opcode.
forget, batch_forget	R: release lookup references locally; never release an open handle's state or a dirty/frozen input. No C1/C2 call.
access	R: local mount-owner identity and portable mode checks, with kernel default_permissions. Service Store/operation authorization remains independent. A requested write fails EROFS. No extra C1 call after metadata is known.
open	R: check access/kind, retain mount identity/serial, pinned filesystem/content roots, length and metadata in a bounded handle. No remote file handle or storage mutation. W additionally uses the explicitly supplied allocation scope; O_TRUNC joins the local mutation transaction.
read	R/W: compose local replacement/zero spans and immutable-base ranges. Each base miss becomes ReadFile → C1 read_range. Clamp to EOF; C1 rejects out-of-range ends. Hold bounded returned bytes until successful terminal completion before replying to the kernel.
readlink	R: retained target or Inspect::Readlink → FilesystemRead::readlink; no canonical-object fetch from the daemon.
opendir, readdir, releasedir	R: local directory handle/cookies bound to immutable root/path. Inspect::List → C1 list; current fuser typed directory replies also need Inspect::Stat for each uncached entry's kind. Emit one bounded page, including locally defined ./..; do not scan the directory to answer its first page. W needs mutation-aware directory-cookie rules.
readdirplus	Not advertised in the first profile. Same C1 list/stat/portable/file inspection could implement it, but the present bridge lacks an entry-plus-attributes page. Return unsupported if dispatched; do not fabricate attrs. A bounded richer Inspect result is an explicit pair 3 extension.
flush, release	R: local handle/error accounting. W: flush reports accepted local visibility/pending errors; release drops only handle references. Neither silently submits a save or promises durability. Dirty input remains owned after close.
fsync, fsyncdir	Explicit EOPNOTSUPP in this profile. No durable C1/C2 operation exists; do not acknowledge a guarantee or call OS sync. This is a user-visible limitation.
statfs	Local projection information only, with unknown backing capacity reported as zero rather than made-up host free space. Read-only flag in R; name_max=255. No Store statistics call exists.
write	W: reserve bounded byte segments and update the final piece tree atomically before acknowledging the exact accepted bytes. No ordinary callback save. Explicit save lowers supported final edits to EditFile, then updates the inode via UpdatePreparedFilesystem; completely new files use ConstructFile. Metadata/mtime creation remains a surface dependency.
setattr	W: size change updates the piece tree and follows the file-save path; mode/mtime require C1 filesystem::attributes::apply_patches and update_filesystem through a missing agreed service operation. Unsupported uid/gid/other timestamp fields fail explicitly. No silent partial field application.
create, mknod, mkdir, symlink	W: allocate namespace/inode state locally only after #180's allocation agreement. File bytes eventually use ConstructFile; C1 FilesystemInput.new_inodes / update_filesystem, filesystem::symlink::emit_symlink and filesystem::attributes::apply_patches need agreed bridge exposure. Current UpdatePreparedFilesystem cannot perform creation. Special-device/socket/FIFO mknod stays unsupported.
unlink, rmdir	W: validate name/type and empty-directory semantics, remove the changed name locally, later submit DirectoryUpdate removal via UpdatePreparedFilesystem. Retain open-unlinked file content and metadata until last use; rmdir is not recursive deletion. Timestamp/validation-error gaps still apply.
rename	W: atomic source removal/destination final binding, with type/empty-directory checks, lowered together via UpdatePreparedFilesystem. Support ordinary rename and NOREPLACE only when preconditions can be enforced; exchange/whiteout flags are unsupported initially. Directory/symlink moves remain gated by bounded prevalidation and typed-limit reporting, described below.
link	W: regular-file hard links only; another changed-name binding uses the same existing serial through UpdatePreparedFilesystem; C1 derives reference counts. Directory/symlink hard links violate C1's single-parent rules. Open-handle lifetime remains local.
getxattr, listxattr	Unsupported initially: C1 FilesystemRead::read_attribute / attribute_keys exist, but pair 3 exposes neither. Do not return false empty success for stored attributes. No implicit ACL/capability xattr semantics.
setxattr, removexattr	W dependency: C1 filesystem::attributes::apply_patches + update_filesystem requires an agreed service operation. Unsupported in the initial profiles until that operation and namespace semantics exist.
getlk, setlk	Unsupported; no lock contract in C1/C2. Do not claim remote/distributed locking.
bmap, ioctl, poll, fallocate, lseek, copy_file_range	Unsupported optional callbacks, no current logical service counterpart. Ordinary kernel SEEK_SET/CUR/END offset handling is separate from special FUSE seek support. No physical block map, implicit allocation promise or private copy operation.
setvolname, exchange, getxtimes	macOS-specific callbacks outside the first Linux mount. No Apple metadata contract or silent platform substitute.

execve and mmap are not independent callbacks. Kernel lookup/open/read and
loader activity drive them. The initial executable-read profile uses a declared
kernel cached-I/O mode with writeback disabled, not an unverified direct-I/O
mode that prevents executable mappings. Kernel caching is separately accounted
and never labelled cold by default. Linux FUSE I/O modes

Projection metadata is explicit: canonical mode/mtime and regular-file reference
count come from C1; uid/gid are the configured mount owner; atime/ctime are
synthetic copies of mtime; regular/symlink length comes from the operations above;
directory size is 0 and directory nlink is a declared synthetic 2; rdev is 0;
blocks are logical 512-byte units, not allocated Store bytes. Reject unsupported
inode kinds. These are projection values, not persisted POSIX metadata. Use
nosuid, nodev, mount-owner access and default_permissions; do not enable
allow_other implicitly. Linux FUSE mount policy

For R an inode/handle identifies (mount identity, pinned filesystem root, serial, local revision), not its latest pathname. No scope-discovery call is needed.
W additionally retains its explicitly supplied allocation scope after that
agreement. File reads retain content root/length across rename and unlink.
For R, directory handles retain the immutable root and original path. For W,
changed namespace visibility and directory cookies belong to Workspace; no
mutable-path re-resolution may silently retarget an open file.

Rename limitation must reach the user

Keep the existing 4,096 examined-binding ceiling; this round neither raises
it nor bypasses validation. A moved directory whose effective traversal exceeds
the ceiling cannot be saved. Parent-alias checking can also exceed it on a large
base tree when the moved directory/symlink itself is small. This is a limitation
of mv, independent of the bridge's separate 128 changed-binding limit.

Today C1 emits InvalidRecord("cycle check work limit"), and the service maps
that to generic InvalidInput, as it does genuine invalid topology. A correct
typed capacity errno is not available yet. Do not parse the diagnostic string or
label a capacity refusal a detected cycle. Before enabling those writable rename
cases, agree a bounded host-side validation/result unit and a distinct public
limit error, or keep them explicitly unsupported. Do not report successful local
mv and hide a known validation refusal until save. Any future validation change
is its own operation/round with equivalent cycle/alias proofs and unchanged-worker
evidence; no limits are raised here. Error mapping

4. Accumulator and numeric resource decision

Use ordinary Workspace modules in layerfs-daemon, independent of FUSE
types and transport selection. Extract a runtime crate only when an actual
second consumer/build boundary needs it. This follows the merged integration
proposal; no provider registry or extra framework is needed.

Reference tier	Pair 1 decision	Placement with remote service
Live piece tree	Workspace owns final file spans, changed names, inode revisions, handles and frozen generation	Daemon beside the calling kernel, never bridge/service
Payload spool	First writable profile uses bounded in-memory byte segments; it omits a disk spool. Segments remain readable until all live/frozen/read references release them	Same daemon, including inside Docker; no host-service spool dependency or shared path
Capture thread	Workspace owns freeze, stable-input lowering, submission and result reconciliation; do not port the reference construction thread	Control stays daemon-side; canonical construction/save executes through existing service C1/C2 with one construction worker

All three responsibilities are independent of the FUSE adapter and can be shared
by a real later materialization caller. Only the projection-specific handle-number
translation stays in FUSE. Host service replacement replay is operation-local
pair 3 input handling, not a pending Workspace overlay.

Proposed numeric profile, not an implemented or measured resource claim:

Item	Decision
First R mount dirty bytes	0
Workspace-owned allocation ceiling per consumer	8 MiB total, shared across all its workspaces, including live/frozen/read-referenced allocated segment capacity, piece/name/inode/handle state, retained metadata and owned scratch/reply buffers
Maximum per workspace	At most the same 8 MiB, never 8 MiB multiplied by its consumer's workspace count; actual pending payload is less once metadata/buffers are reserved
FUSE read reply reservation	At most 128 KiB per admitted callback, charged inside the total; negotiate the read limit accordingly
Frozen submissions	1 per consumer, charged inside the same total; no successor write generation while a save runs
Additional immutable content cache / speculative prefetch	0 bytes for the first profile; required handle metadata/page state is charged above
Spill	None; no implicit tmpfs/disk fallback or cache-eviction hint presented as a memory bound

The 8 MiB choice is a deliberately small, unmeasured support envelope compatible
with pair 3's maximum replacement replay; it is not justified by the old
8 MiB snapshot-cache constant. Allocate/charge capacity before making a write or
namespace change visible. Refuse a non-fitting mutation with ENOSPC, without
partial namespace effects; busy/frozen local generation gives EBUSY. Reservations
cover normalization and completion, not only the final live payload. Exhausted
handle/metadata capacity likewise refuses further admission rather than evicting
state still needed by an open handle.

Flush is caller-driven only: explicit root-save freezes the generation and
blocks new writes for that consumer until a terminal result. Reads of accepted
local bytes can continue within budget. No size-triggered save, timer-triggered
save, background retry, or save hidden inside write, flush or release.
The triggering save waits; an ordinary write never waits for a pressure save.
The explicit Workspace save/control entry point is pair 1 work, not a new bridge
filesystem algorithm and not an invented logical Commit.

Lower the final piece tree, not the chronological FUSE write log. Derive
monotone base/replacement edits in C1's supported current-result coordinates,
coalescing overwritten replacement spans before submission. Before mutation
visibility, validate the entire resulting submission: at most 256 edits and
8 MiB replacements, EditFile base and final lengths at most 64 MiB, at most
128 directory records, 128 inode updates and 128 total changed-name bindings,
and at most 32 KiB encoded request metadata. A one-byte edit to a 100 MiB base
or a 129th changed name must be refused before acknowledgement even if the
Workspace byte budget has room. Do not hide a split into extra saves.
Use complete-file construction for a genuinely new file; do not fall back to
reconstructing an existing complete file after an edit refusal. If lowering does
not fit, refuse explicitly. External tests must prove overwritten replacements,
truncate/extend/zero spans and base-root retention before W is enabled.

Save changed files sequentially, then submit one filesystem update. F files
cost F+1 logical calls; F=0 still needs the tree update for namespace changes.
Earlier saved objects may remain after a later failure. Install a new local base
only on a known terminal filesystem-root success covering the frozen revision.
Known failure retains the input; unknown outcome quarantines and retains it,
still charged, with no resend. Restart recovery/discard semantics remain a
dependency, not a durable spool claim. Losing the daemon can lose these segments;
neither write acknowledgement nor root-save implies crash durability.

The 8 MiB number is not total RSS or cgroup memory. Bridge allocations/thread
stacks, kernel FUSE/page cache, service replay/C1/C2 scratch and process baseline
remain separate resource scopes to qualify. There is no file-size-proportional
disk-spool/page-cache loophole in this profile. A larger selected workload that
cannot fit remains unsupported/NOT_RUN for that profile; it is not shrunk or
silently split into smaller saves to obtain acceptance. A larger envelope needs
an explicit owner decision and its own accounting, not an implementation tweak.

5. Mount topology and deployments

Choose N mounts for N workspaces, with separate kernel sessions and
workspace-local locking/cancellation. One daemon may own a consumer's mounts and
shared charged budget; no process-per-workspace requirement or eager mount/session
preallocation. Do not hold a workspace state lock over a service call. This gives
separate unmount/failure control and prevents one callback from holding every
workspace lock. It costs N kernel sessions and additional bounded handle state.

This is not full neighbour isolation. At the pinned pair 3 version the service
admits one active operation globally across all Stores, queue 0. A slow
operation makes other remote misses receive Capacity; extra mounts or sockets
do not solve that. Workspace-local reads can proceed, but read/control progress
through a busy service is unqualified. Cross-workspace memory admission also
shares the declared consumer cap. Any service-admission change belongs to pair 3
and requires separate evidence without adding construction workers. Owner

Deployment	Mount and callers	Workspace / byte segments	C1/C2 and Store
Native Linux host	In the callers' host kernel/mount namespace	Host-local daemon RAM	Configured local service (direct parity uses the same handler)
Linux Docker caller, host service	Inside the Linux container's mount namespace; explicit /dev/fuse/mount capability required	Container daemon RAM, charged to that consumer/container	Host service; configure a real reachable endpoint, not container localhost
Local Linux caller, remote service	Local caller kernel; service distance does not move the mount	Local daemon RAM	Remote service with C1/C2 beside its Store and explicit authenticated endpoint
Remote Linux execution node	Kernel on that execution node	Daemon RAM on that same node	Configured service elsewhere or colocated there
macOS host caller / managed isolate	No native Linux-FUSE claim; a Linux VM/container mount serves callers there, not automatically a macOS path	Requires the selected executor or another explicit projection	Native service placement is independent; managed/cloud provider/carrier qualification remains future work

A truly remote FUSE daemon cannot directly answer another machine's kernel
without a local projection endpoint. Move the service, or move the callers and
mount together; do not confuse remote operation execution with a remote kernel.
No shared data volume, host-path protocol, SQLite exposure, permanent-process
assumption or universal provider registry is introduced.

6. Logical exchanges, separate from latency

These are source-derived request/result counts, not performance measurements.
Assume an already authenticated connection, explicit immutable root, and no
retained metadata for the cold examples. A logical exchange can stream many
16 KiB frames and take many TCP packet RTTs. TCP/Noise/HELLO setup, queue refusal,
reconnect and kernel cache effects are counted separately; they are not hidden.

Let P be listing pages, U the uncached entries needing a kind/stat, F the regular
files needing length, S the symlinks needing target/length, and R the submitted
immutable range reads after kernel/local hits and range splitting.

Caller activity	Current cross-boundary logical exchanges	Avoidable work / dependency
lookup / full getattr of regular file	2: Stat + File; retained complete attrs → 0	Enrich existing bounded Inspect::Stat result with length to make miss 1; not implemented
Directory stat	1, or 0 retained	Portable/synthetic attrs require no file read
Symlink full stat	2: Stat + Readlink, or retained parts	Bounded richer result could combine them
readdir	P+U using current fuser typed entries; each page has up to 128 entries and 16 KiB, so P is not determined by count alone	List returns no kind; do not claim P-only without an adapter supporting unknown type or an agreed richer List result
readdirplus (future)	P+U+F+S without retained attrs	Entry-plus-attrs pages can remove per-entry requests, under existing bounds; disabled initially
read with known root/length	R; one for a fitting contiguous base range, 0 for entirely local data	Adjacent demanded ranges can coalesce if bounds and reply ordering permit; disjoint missing spans may require more than one
execve	M+R, where M is the actual metadata exchanges for executable/path components/interpreter/libraries	No fixed count; retained metadata, loader/kernel caches and bounded batching change it. Count real callbacks and bridge operations in later execution

For illustration only, one regular file with known parent, cold attrs, a single
base-read range and no loader dependencies entails 2 metadata + 1 range = 3
logical exchanges. This is not a universal execve count or a latency claim.
All mount reads and all service work remain inside their declared phase when
eventually measured.

7. Slow peer, failure and visibility

Use the current bounded bridge and its fixed limits, not a new transport. The
committed limits are 16 KiB frames, 32 KiB metadata, 64 MiB construction/input and
response allowance, 8 MiB edit replacements, 256 edits, 128 directories/inode
updates/total changed bindings, 128-entry/16 KiB list pages, paths 4,096 bytes,
names 255 bytes, 4 admitted sessions plus one refusal slot, and request deadline
at most 10 seconds. Connect/handshake/idle policy is 5 seconds.
No dirty-worktree increases are incorporated. Request Client

Use one absolute callback budget of at most 10 seconds, including prerequisite
queries; dependent calls receive only the remaining budget. Do not reset it for
each child call. Slow transfers backpressure at existing bounds. Local resource
admission refuses rather than queues unbounded work; interrupts/unmount cancel
local waiting without asserting that an already submitted mutation rolled back.
Current admission Capacity does not identify busy versus size, so retain its
original category rather than guessing from timing.

Failure meaning	FUSE-facing decision
Confirmed namespace PathNotFound	ENOENT
Missing canonical content, integrity or provider failure	EIO; preserve original typed failure separately, never ENOENT
Invalid caller data	EINVAL; apply known local POSIX preconditions before remote submission
Unauthorized peer/Store/operation	EACCES; content hashes do not authorize access
Storage ownership unavailable	EBUSY, preserving Ownership
Capacity / unsupported operation	ENOSPC / EOPNOTSUPP, preserving the original class and phase
Explicit service Deadline	ETIMEDOUT
Transport loss after mutation may have started	EIO with unknown outcome retained; input remains charged and frozen, no automatic retry

Actual gaps: the native client's delivery path collapses read transport
failures to Io, and mutation delivery failures to Unknown; conversion from
io::Error loses socket timeout kind. Therefore a universal timeout-versus-I/O
errno promise is currently unavailable. Pair 3 must preserve it before that
portability requirement is accepted. Some C2 read causes also become generic C1
provider failures. Preserve what is known; never reconstruct categories by
parsing strings. The kernel errno alone cannot carry every distinction: pair 1
must expose the consumer's generation, original Failure, unknown flag and
cleanup result through its explicit save/status result, whose control surface
still needs definition. No private xattr or bridge replay ledger is invented.

8. Fate of 8 KiB and the later measurement

The reference's 8 KiB prefetch threshold and 8 MiB snapshot cache are currently
unjustified in the new topology, not proven wrong. They are not copied as tuned
defaults. The first profile is demand-driven with no added immutable content
cache/prefetch. This is a design baseline, not a claim that turning prefetch off
is faster. The reference control retains its own declared policy.

A threshold should depend on measured request cost, bandwidth, expected reuse,
decoded work and the same fixed memory budget; it cannot be derived from transport
latency alone. A static threshold may still suffice. Do not build an adaptive
policy before evidence exists. Compare saved exchanges against extra fetched
bytes and retained memory, rather than using file size as a proxy for everything.

Once a real mount exists, the first prospective matched workload is an identical
binary above 8 KiB, first execution and a predetermined repeated-execution
sequence, including the same interpreter/libraries and declared read fraction.
Measure on both v0.1.6 and core: mount, first required read, execution sequence,
and total required work. Then, in a separate policy round, compare demand-only
core with 8 KiB prefetch and a prospectively declared transport-aware candidate
under the same owner-approved cache budget. The v0.1.6 arm supplies its previously
missing deferred-read cost; the core arm supplies callback/service/transport work
and any claimed savings. Local/direct, Docker-to-host and remote endpoints are
separate topology rows; an unavailable topology stays NOT_RUN.

Record callback counts, logical exchanges, connection setup, useful/transferred
bytes, read fraction, authenticated reconstruction work, latency phases and both
client/host resource scopes. Separate explicitly enforced cold and warm rows;
repeated invocations within a declared workload do not authorize extra samples or
best-of reruns. One sample per case/arm; fresh append-only output; all failures
retained. No pre-touching or shifting read/construction work into setup. Preserve
the handoff's dual-lock/quiet-resource protocol, fixed command budgets and one
construction worker; init_namespace alone retains its multi-worker exception
and 2.7 s cold target. Nothing in this document registers or executes a campaign.

9. Agreements and next rounds

Only the four initial cross-pair agreements are required before code; they do not
require either pair's complete implementation:

Agreement	Concrete dependency
Inputs	Authorized explicit filesystem/file roots; prepared scope/root serial for updates; supported final-edit lowering and stable bounded bytes. New inode and metadata/symlink operations need explicit shared input shapes, not object RPCs.
Results	Current separate Stat/file-length calls are sufficient for R. Agree richer bounded metadata/list results only if selected for the next operation. Separate saved file root, saved filesystem root and future Commit. Distinct validation-capacity errors are missing.
Identity	Peer/Store grants remain pair 3. Workspace inode/handle/frozen generations remain pair 1. Request generation is currently carried but not enforced as persistent identity; IDs are connection-scoped, not dedup keys. Reconnect must not imply replay. Endpoint-independent auth evidence remains a pair 3 portability gap (VerifiedPeer currently comes from its native adapter).
Completion	Read data becomes replyable after terminal success; saved roots replace only the covered frozen revision. Agree timeout/error fidelity and explicit status/cleanup observation. Unknown input is retained, never resubmitted automatically.

#180 owns: what logical commit returns; stage durability/advisory meaning;
publication/parent/head semantics; discard/restart fate; inode serial allocation,
uniqueness and nonreuse. No Commit schema, stage durability, allocator or stronger
acknowledgement is decided here. Current MEMORY journal, synchronous=OFF, no
sync and no WAL remain unchanged. Early explicit-root save is not Commit.

Pair 3 owns: shared operation extensions (new-inode/metadata/symlink inputs if
W is selected), richer results if selected, transport timeout fidelity,
endpoint-independent authentication evidence, operation identity across connection
lifetimes, admission/read-control progress and actual non-native carrier support.
No second content/storage implementation is introduced.

Pair 1 owns: R callback implementation; bounded local state and POSIX projection
metadata; N-mount lifecycle; W accumulator/lowering/handle/cookie behavior;
save/status control results; Linux mounting and resource/error verification.
Writable directory/symlink rename additionally needs a public bounded validation
path that can refuse before visibility. #207 retains the owner decision on read
fraction, matched comparator and competitive acceptance.

Sequence one operation per round: (1) fixed-root readable mount with existing
operations; (2) a selected missing shared-contract operation, if needed; (3) a
selected writable Workspace operation with allocation/metadata dependencies
resolved; (4) separately declared mounted comparison; (5) separately justified
prefetch/cache experiment. No bundled FUSE/portability/pair 3 refactor.

Validation for this research is source/API/status review and documentation-link/
whitespace checking only. Cargo test/clippy/fmt, product-boundary tests, Linux
mount tests and benchmark commands are NOT_RUN: no implementation was changed.
The existing main checkout and other worktrees were not edited.

[yifanxuaaa]

Owner platform direction, 2026-09-21: Linux only initially; macFUSE and a Windows filesystem projection later.

The architecture remains:

Linux FUSE now / macFUSE later / Windows adapter later
    → daemon-owned Workspace
    → pair 3 bridge
    → layerfs-service
    → local C1 + C2 + storage

Adapters live beside the applications and their kernel, inside the execution-side daemon. They are not part of layerfs-service. Keep platform callbacks, native handles and error translation in the adapters; keep Workspace state and logical service operations independent of those platform types.

Implement only Linux now. Windows framework selection and macOS/Windows implementation and qualification are deferred; no placeholder adapters or provider registry are needed. Future platform naming, permission, handle and metadata mappings must be explicit rather than assumed equivalent.

This records platform scope only. No mount, measurement or additional platform support is claimed; C1/C2, pair 3 and #180 ownership remain unchanged. All related issues remain open.

[yifanxuaaa]

Handoff revised — pair 3 landed while the prompt was in draft. PR #200 merged as 7b8a7d9d3, so the prompt was rewritten against what actually landed rather than what was forecast:

issue207-fuse-enablement-handoff.md (commit c6d9d7691)

Three substantive changes:

1. The predicted boundary is confirmed in code. core/crates/layerfs-bridge contains no FUSE, overlay or accumulation logic — so "the accumulator cannot live in the bridge" is now a verified constraint rather than a forecast. core/crates/ carries layerfs-bridge, layerfs-daemon and layerfs-service beside the original three.

2. The prompt is now explicitly subordinate to pair 3's own forward design, 06-future-fuse-and-cloud.md, which is authoritative for responsibilities and layout. A new §0.1 records what that document already settles: the Workspace/FUSE responsibility split, that v0.1.6's combined LiveOwner must not be recreated, and that the callback/operation mapping largely exists — so the first deliverable becomes reviewing and filling gaps in that table rather than authoring one.

3. A hard C1 constraint that shapes the whole write path. FUSE can overwrite bytes written earlier in the same dirty generation, but C1's EditStream rejects an edit reaching into an earlier replacement — InvalidEdit { what: "range inside an earlier replacement" } (core/crates/layerfs-content/src/file/edit/input.rs:10-15). Workspace must lower its final piece/namespace state to a supported stable operation input, and must not sort or coalesce raw edits in the bridge, nor silently flatten to a complete file to evade the replay limit. The same file carries MAXIMUM_EDITS_PER_OPERATION = 4_096, the ceiling v0.1.7 co-design pair 1: projection and runtime — FUSE against the workspace accumulator #179 already cites.

What remains genuinely open is narrowed to: the numeric overlay ceiling and flush policy, mount topology, the fate of the 8 MiB cache and 8 KiB prefetch threshold under a cross-boundary topology, round-trip counts per operation, and the lowering algorithm's canonical/profile consequences.

[yifanxuaaa]

Pair 1 design updated for merged Pair 2 — source pin 152b9c3a2e8ec2536a1d63601b681e1f7ef34455. This is a design update, not implementation, a benchmark, or closure. PRs #211/#212/#213 are merged; #210 remains open for H04/H06/H08/H14 qualification.

The daemon-owned Workspace remains between FUSE and the existing bridge. It consumes profile-1 reads/file operations and profile-2 HistoryQuery/HistoryCommand (opcodes 6/7, explicit grants 0x20/0x40); it never accesses C5 SQLite or duplicates history/transport logic.

The revised lifecycle is:

1. Existing Branch → GetBranch; new Branch → Fork then GetBranch. Only GetBranch supplies the C1-validated root serial. InitLayerStack creates bounded genesis/stack, not a Branch.
2. Freeze G with its original Branch head/base/effective-root/scope/profile/root serial, retaining one live G+1 under the same proposed consumer budget.
3. Save G's changed file content with ConstructFile/EditFile; build PreparedChanges using those acknowledged roots and the captured filesystem base.
4. Use composite Commit(PreparedChanges) for ordinary explicit Commit, or StageChanges → exact CommitStaged(workspace, token) when an explicit staging pause is wanted. StageChanges builds and saves the filesystem root itself. Do not pre-run UpdatePreparedFilesystem and register an arbitrary root as a stage.
5. Stage success alone does not advance the Branch or clear G. Known Committed/UpToDate completion acknowledges only G and preserves G+1/open-reader references. Retain request/generation association and per-file roots; the API does not return a per-inode completion stream.
6. AddLayer is a separate explicit publication. It advances the stack head, never the Branch base. A later publication cycle needs a Branch forked from the published Layer or future explicit rebase support.

Failure handling preserves code, unknown flag, cleanup, conflict context and StageObservation separately. Unobserved is not absent; AcknowledgedUnknown can accompany a known Busy refusal. A Retained stage on a stale-token error may be a different current stage: bind it to G only if incarnation/token/generation/context match. No refreshed-token rebase, automatic replay or guessed discard. Reusing a consumed CommitStaged token is StageChanged, not replay success.

Same-live-service connections can inspect or explicitly commit a known exact stage. Current observations are not receipts for a lost original request. Read-only catalog reopen exists; writable process restart/new reservations fail with ContinuityUnavailable. Unknown catalog outcomes can quarantine reads as well as writes.

Dependencies now supplied: Branch root descriptor, exact stage/Commit results, conditional Layer publication, checked non-recycled ReserveInodes, typed history failure context and endpoint-independent authenticated caller evidence. Remaining: live new-inode/mkdir/symlink attachment, general metadata construction, POSIX/rename-error gaps, actual G/G+1 implementation and mounted qualification. Bootstrap's 128 entries and ReserveInodes do not implement live creation.

Refreshed limits: MAX_FILE=4 GiB, service admission 2/Q0, protocol operation maximum 600000 ms; replay remains 8 MiB/256 edits, prepared updates 128 changed names/128 inode changes/128 directories, request metadata 32 KiB, history results 128 records/16 KiB with 160-byte authenticated cursors. These current maxima do not enlarge Pair 1's proposed 8 MiB allocation envelope, 10-second callback policy, or benchmark budgets. No durability upgrade.

File-plan changes concentrate in workspace/state.rs, snapshot.rs, lower.rs, save.rs, budget.rs, plus a focused caller-side lifecycle.rs; FUSE stays thin. Linux-first, future macFUSE/Windows, immutable /workspace-id, one save in flight and one construction producer remain.

The maintained Pair 1 design and a new dated integration checkpoint were updated in the task's isolated worktree; earlier checkpoints remain unchanged. Only source/design/link/whitespace review ran. The reported 605 tests and host/Docker history routes belong to Pair 2's existing evidence and do not close H04/H06/H08/H14 or qualify FUSE. This review changed no issue state. Final audit found #179 already closed at 2026-09-20 23:33:35 UTC, before this update; #180/#181/#190/#205/#207/#210 were open. That external closure does not establish FUSE implementation or qualification.

Sources: shared history contract, service composition, history architecture, open qualification.