ms2k/lazaret
SHA256
Watch
0
Code Releases 3 Activity

Define ignored workspace routing semantics and budgets

Browse source
This commit is contained in:
ms2k 2026-07-15 01:10:28 +09:00
commit c54372ea87
1 changed files with 905 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

89
docs/specification.md
View file

@ -655,6 +655,95 @@ environments, generated executables, caches, and other ignored artifacts from
later being executed by host tools. Trusted host configuration may disable this
behavior when fully bidirectional ignored paths are required.
#### Ignored Workspace State routing contract
The production router is a dedicated rootless host FUSE filesystem. It presents
one workspace tree and chooses exactly one backing for each pathname operation:
the canonical Agent Workspace for tracked and ordinary non-ignored paths, or the
Domain's Ignored Workspace State for ignored untracked paths. The `.git` entry is
host-backed, subject to the Git Sentry mounts below. Classification uses Git's
effective byte-path rules, including repository and nested `.gitignore` files,
negation and precedence, the applicable common-directory `info/exclude`, the
configured global excludes file, tracked-index state, linked worktrees, nested
repositories, and `core.ignoreCase`. Non-UTF-8 path components are supported as
opaque bytes; NUL and `/` retain their ordinary pathname meaning and cannot be
components.
Each pathname operation uses one immutable classification snapshot. Publication
of a changed index or ignore input serializes against new pathname operations and
either installs one complete new snapshot or leaves the prior snapshot active.
There is no partially updated matcher. Existing file descriptions, mappings,
locks, and directory streams remain pinned to the backing object and snapshot
under which they were opened. A subsequent lookup or open uses the current
snapshot. Writes, flushes, locks, and mapping writeback through an old handle
affect only its original backing object; a transition never rebinds a handle or
copies its content to the other backing.
Directory lookup and enumeration expose only the entry selected by the current
snapshot. An ignored host entry is hidden even when no isolated entry exists. A
stale isolated entry is retained but hidden while its pathname is host-backed.
On a non-ignored-to-ignored transition, subsequent lookups expose the retained
isolated entry or absence and hide the host entry. On an
ignored-to-non-ignored transition, subsequent lookups expose the host entry or
absence and retain the isolated entry hidden. Neither transition imports,
exports, merges, deletes, or otherwise copies content between backings.
A same-backing `rename` or hard link has the backing filesystem's atomicity and
error behavior. If the source and destination route to different backings,
`rename`, `RENAME_NOREPLACE`, `RENAME_EXCHANGE`, and hard link return `EXDEV`
before either backing is changed. `RENAME_WHITEOUT` returns `EOPNOTSUPP` without
mutation. Lazaret never reports a copy-and-unlink sequence as a successful
rename or a copied file as a hard link. Applications may react to `EXDEV` with
their own visible copy and unlink operations.
An index publication that would make an isolated object tracked is accepted only
when a type-compatible host worktree object already exists independently. The
router then selects that host object and retains the isolated object hidden; it
does not compare, merge, or copy isolated bytes. A guest index-lock rename that
would instead create a tracked path with only an isolated object returns `EBUSY`
before replacing the index. If an unmediated host index change creates that
state, pathname access to the inconsistent path fails with `EIO` until the host
index/worktree tuple is made consistent or reverted. The isolated object remains
recoverable Domain state. Consequently, ordinary add and commit are
supported for host-backed paths, while force-adding an isolated-only path is an
explicitly unsupported Git operation rather than implicit host copy-back or
silent disappearance.
The v1 operation contract supports lookup, bytewise directory enumeration,
regular-file and directory creation, open, read, write, truncate, allocation,
sync, unlink, and same-backing rename and hard link. It supports symbolic links
without following a backing symlink during routing, nanosecond timestamps,
`user.*` extended attributes, POSIX ACLs where the backing filesystem supports
them, sparse-file hole/data queries and hole punching, same-backing copy range,
shared and private mappings, BSD `flock`, POSIX record locks, FIFOs, and Unix
domain sockets. Cross-backing copy range returns `EXDEV`. Character and block
device creation returns `EPERM`. Backing filesystems may return their native
documented unsupported error for an optional feature, but the router may not
turn a partial operation into success or fall through to the other backing.
The supported Git contract covers status, diff, ordinary add and reset, commit,
checkout and restore, branch and reference updates, merge, rebase, stash,
worktree-local index locking, linked worktrees, and nested repositories. These
operations retain Git's ordinary conflict and concurrent-writer behavior. Git
Sentry still makes host `.git/config` read-only and replaces default
`.git/hooks` with sandbox-local transient storage. Force-adding an isolated-only
path, cross-policy atomic rename, and device-node creation are refused as defined
above and are not compatibility promises.
The committed `lazaret-ignored-workspace-contract-v1` corpus is the executable
acceptance inventory for these semantics. It covers ignore precedence and live
changes, non-UTF-8 and case-folded matching, linked worktrees and nested
repositories, every operation class above, open-handle transitions, concurrent
host and sandbox mutation, router loss, and absence of silent loss or copy-back.
The same corpus defines the benchmark protocol. Qualification runs direct-host
and routed placements on the recorded reference environment, uses identical
fresh fixture materialization for each sample, and reports both the routed
absolute median and the paired routed/direct median ratio. Metadata, Git, offline
package installation, and offline build workloads must meet both limits. The
reference environment, preparation states, sampling order, variance tolerance,
normalization, and numeric budgets are part of the corpus and may not be relaxed
by a production implementation.
Ignored-path isolation is defense in depth and does not replace the mandatory Git
Sentry protections below.