agentleFS
Ephemeral-AI-LabEphemeral-AI-Lab/layerfs/core/AGENTS.md

layerfs / core

AGENTS.md2.1k starsChanged 8 days agoMITView on GitHub

Status: Current general guide. Read repository instructions first. This file adds implementation boundaries for both current workstreams under core/; it does not repeat the product mental model or campaign-specific benchmark procedures. - Implement cluster one and cluster two in core/. The v0.1.6 reference under root crates/ and the archived core/reference-tests were retired by R9c (2026-10-10) and are absent at HEAD; recover them at local tag reference-v0.1.6-final (d296981ac, crates tree 498dd1917812). Neither was a dependency, source include or fallback; do not…

We split this AGENTS.md into the rules it gives an agent

23 rules. About 0 are common, 18 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈18

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read repository instructions first.

    line 5
  2. Distinctive:

    Add members only with real product boundaries and implementation.

    line 140
  3. Distinctive:

    Keep unrelated work intact.

    line 152
  4. Very specific:

    Commit runs/readers/base pins are journaled owner maps.

    line 170
  5. Distinctive:

    Keep implementation description separate from target proposal and research.

    line 190
  6. Distinctive:

    Commit consumes the Workspace's published frontier through the shared Content, Storage and Persistence pipeline regardless of launch route.

    line 240
  7. Distinctive:

    Commit and a fresh mount. Use ordinary public filesystem access in these proofs.

    line 250
  8. Distinctive:

    Use the actual Store-derived construction policy and bounded capacities on both routes.

    line 283
  9. Very specific:

    Keep completion boundaries explicit: Save::finish() completes object storage.

    line 311
  10. Distinctive:

    Before changing a performance-sensitive path or diagnosing a performance finding, read the optimization guide.

    line 322
  11. Distinctive:

    Test-only dependencies belong in dev-dependencies.

    line 359
  12. Distinctive:

    Prefer deterministic public behavior and external observations.

    line 362
  13. Distinctive:

    All new replacement/application-adapter production files have at most 999 physical lines, including comments/blanks.

    line 369
  14. Very specific:

    Every product lib.rs/mod.rs has at most 200 physical lines.

    line 375
  15. Distinctive:

    Do not minify, expand macros or add includes to evade size/ownership rules.

    line 384
  16. Distinctive:

    No third-party patch, fork, vendor, registry edit or replacement dependency, except the owner's fuser 0.18.0 signed-timestamp correction …

    line 449
  17. Distinctive:

    Use existing capabilities and locked builds.

    line 451
  18. Distinctive:

    Run commands from the repository root with the actual core manifest.

    line 457
  19. Distinctive:

    Every test invocation obeys the repository's 2-minute test ceiling: run it under an explicit timeout of at most 120 s, per package when the …

    line 469
  20. Distinctive:

    No other dependency change or general unsafe exception is authorized.

    line 534
  21. Very specific:

    Keep the dependency version exactly0.18.0.

    line 539
  22. Distinctive:

    Before a native fuser build, run the focused provenance check:

    line 559
  23. Distinctive:

    No other Persistence module may contain unsafe Rust.

    line 581

≈ “Common” is an estimate: at least 1 in 5 of the 36,368 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Agent rules for core

Status: Current general guide.

Read repository instructions first. This file adds implementation boundaries for both current workstreams under core/; it does not repeat the product mental model or campaign-specific benchmark procedures.

Scope and ownership

  • Implement cluster one and cluster two in core/. The v0.1.6 reference under root crates/ and the archived core/reference-tests were retired by R9c (2026-10-10) and are absent at HEAD; recover them at local tag reference-v0.1.6-final (d296981ac, crates tree 498dd1917812). Neither was a dependency, source include or fallback; do not restore them.
  • Active cluster-one members are content, storage, history, persistence, project Init and telemetry. The initial cluster-two SQLite engine is layerfs-overlay; its active membership does not complete Workspace/FUSE/daemon integration. core/Cargo.toml is the membership authority. Workspace now exposes immutable base binding/read, effective source-qualified lookup/stat/paged name merge, prepared actor install and atomic ordinary namespace operations, bounded writes/truncate/regrow and composed payload reads. Independent file/captured/operation custody and bounded live reclamation are implemented through S6, including indexed automatic reclamation (its physical reservation and headroom were removed by #321: no space is reserved ahead of use, and a full device rolls the write back as no space); native/runtime/integrated exits remain unfinished. See S6 audit. Its relocated predecessor layerfs-workspace-legacy was removed by R7-retire. Since #321 the daemon holds one overlay file and connection per mounted Workspace, each behind its own lock, with the calling thread running each short job; the fair SQL owner thread, its queue, credits and shared memory budget are removed. See the terminology guide and the #321 record. Daemon also exposes a direct global Store adapter with a mount-time reader per Workspace, exact quarantine and read-only bind snapshots, one immutable cache shared across Workspaces, bounded root binding and operation-owned exact failures. Concrete opening stays outside the provider-independent adapter; see the direct Store boundary. The host-mediated SDK/upstream transport is retired; see the retirement record. Workspace calls return typed values directly and count SQL/payload/allocation work under the same lock. Exact attempted failures retain their cause and backing; before-effect refusals retain their original input. Overlay/Daemon also expose bounded indexed operation records in the same database, with guarded atomic changes and automatic last-owner cleanup. Content now exposes a backed file editor over these records and Workspace supplies an explicit operation/file adapter with first-original failure custody. Run-aware localized edits reuse the frozen sparse scanner and bounded positive immutable zero evidence. Streamed directory inputs share the canonical filesystem algorithm; backed serial state supplies new-parent membership, rebuilt roots and initial counts/final row streams. On the backed route validation classifies in 64-row windows and keeps its topology evidence in indexed records; resident routes keep their resource-derived limits. Captured local inode/run points retain exact reader root/floor and bounded forward metadata progress. Captured regular-file normalization now derives authenticated base facts, coalesces final changes into indexed records and consumes them once through the retained FileView/fallible edit source. Backed reference reduction/release uses fixed rows, sealed membership passes and guarded FIFO/cursor transitions. Captured namespace normalization is the CapturedNamespace producer (captured namespace construction); the product Commit constructor calls it (product Commit). The Store half of Commit is implemented with exact original failure/unknown custody; see Store Commit. The external E01 example records original startup work, diagnostics and Stop without creating a Workspace route. It supplies diagnostic receipt consistency, not E1/E2 performance admission. Its relocated predecessor was removed by R7-retire; standalone native executable/Exec integration is unfinished. Pre-S8 direct-operation accounting now has actual registered macOS/Linux engine and Store-half Commit runs, independent family/count validation, and supported phase observations. Numerical latency/residency and exact continuous peaks remain unqualified; see the accounting scope. SDK creates/imports the initial Store, publishes the first Branch and consumes seal, returning a closed file plus explicit provider/locator/profile metadata. It retains no Store handle or data service. Native install now streams the sealed file once, opens it in the daemon and returns both actual SQLite versions; see F5 handoff. Authenticated mount binding, Store-half Commit, status, terminal close, fork and history now compose the direct ports; see native control. The prior client/runtime, daemon upstream, Bridge logical data framing and excluded API-core are retired. Historical receipts keep their original topology and verdicts. R7-retire (2026-10-10) removed all seven excluded directories as retirement: layerfs-server, layerfs-fuse-legacy, layerfs-sandbox-legacy, layerfs-sdk-legacy, layerfs-daemon-legacy, layerfs-bridge-legacy and layerfs-workspace-legacy. core/crates now holds only the 13 active members; the boundary guard refuses the return of a removed directory or package name, and each source is recoverable from the commit named in the R7-retire record. Pinned read-only SDK views (303/08 O-10) are deferred, not dropped: no implementation is in the tree, and a kept feature needs a new design on the SQLite overlay. Do not restore the predecessor code to supply them. Project native import preserves opaque symlinks, complete membership and hard links, with indexed acquisition state. The accepted host WAL baseline retains its recorded speed FAIL; no new timing is implied by SDK composition. Bridge retains pinned authenticated KK channels, bounded native records and independent fences and bounded native install/control. FUSE/Exec qualification and complete kernel mount readiness remain S8. The replacement Sandbox is an active member with ordinary Engine execution, owned lifecycle and authenticated SDK/daemon startup. Optional privileged command cancellation/client provenance is outside the current owner scope. The replacement Fuse is now active with a fixed shared dispatcher, actual deferred Owner/Store ports, a read-path callback adapter with complete opcode accounting, direct mount/session ownership and connection drain. Its predecessor layerfs-fuse-legacy was removed by R7-retire; the last commit holding that source is 15e33e22c. The daemon composes Attach/Locate/Ready and reversible normal unmount; see native request service and native mount session. Ordinary native mutation is served through the existing Workspace plan and one publishing Overlay job, with no notification and no writeback cache; see native mutation and kernel coherence. A control Commit runs the captured namespace producer through the unchanged driver, and takes the Workspace's overlay lock for each of its jobs; the mounted proofs and their limits are in the R5 record. Forced unmount of one Workspace is implemented as ForceUnmount: a before-effect guard, one abort write on the connection's own control, the terminal fence, the local drain, one plain detach, then Revoke and Close; see forced teardown. It is refused where no abort control is bound, which includes the current Sandbox topology, and a stop after an effect is Retained with no way back. No daemon-wide graceful drain exists and none is planned. Source acquisitions have their own owner slots, and a failed cold read ends its own request with EIO while the mount keeps serving; the concurrency, teardown and failure-scope proofs and their limits are in the R6 record. A create that leaves fewer unconsumed inode serials than the daemon's configured low-water makes one early reservation; every deployment and harness sets 0 today, which makes none. A new Mount is refused Capacity at mount:debt while maintenance is stopped. Both, the proofs added around them and the rows still open are in the R8b record. R8b closed not qualified and R9b without removal. R8c then closed qualified on function, counts and resources at the owner-rescoped scope, with the deployed low-water at 256 (R8c record), and R9c retired the root reference (R9c record). Add members only with real product boundaries and implementation.
  • Cluster-one work starts with the handbook and CAS/CDC/delta guide. Use public contracts, source pins and limitations; preserve canonical compatibility.
  • Cluster-two work starts with the current design index and relevant primary operation/engine/FUSE contracts plus runtime integration. Required corrections are real engineering scope; research candidates are not implemented features or excuses for accumulated workload caps.
  • Closed Stage 0–6 handoffs and prior server/backend plans are historical. Consult them for a selected compatibility/reference question; do not restart their loops or inherit their retired topology. Do not revive layerfs-server.
  • Keep unrelated work intact. Migration, source moves and retirement are explicit changes, not side effects of implementing a component.

Architecture and public contracts

Overlay schema19 uses directory_entry and operation_record terminology, including owned/indexed variants, throughout SQL and the active public ports. Through schema 33 Workspaces shared physical tables partitioned by namespace; since #321 (schema 34) every mounted Workspace has its own file with the same tables, copied from a closed empty template at mount and deleted at terminal unmount. The naming change authorizes no physical table redesign; generic temporary buffers and historical receipts retain their distinct terms. See the terminology guide. The #320 product sweep (2026-10-14, schema 37) removes accounting triggers, Workspace/allocator SQL rows and generic caller-minted leases. Workspace lifecycle/frontier/dirty/base-reader counters are one journaled runtime value, restored only after known whole-job rollback; unknown outcomes retain custody. Commit runs/readers/base pins are journaled owner maps; captured generation holds use a count index. Daemon-bound routing is checked once per call; Overlay accepts no Route and stores no namespace. Cleanup debt remains SQL-backed after the memory-placement review. Resources computes row/length totals on demand and retains exact owner counts from memory. See the current runtime state.

Schema17 adds native mount/source/lookup/read associations, atomic Workspace read observations and bounded revoked-lookup retirement. Schema18 adds native file associations over the existing OpenFile owner and atomic open decisions; see native read custody. This component does not establish Ready, kernel service or full drain. Schema19 adds native directory ownership, exact name-boundary cookies, retained parent updates and bounded live cleanup; see directory custody.

docs/architecture/ describes product source, not release qualification. A source change to boundaries, canonical/physical format, algorithm or named bound updates the affected architecture/API document in the same change. Record source pins and advance them explicitly; never silently re-date evidence. Keep implementation description separate from target proposal and research.

Public content/storage/history/persistence contracts govern integrated callers. Stable capture/input, Store-derived policy, backpressure, Save completion and atomic history publication are separate obligations. Branch Commit overwrites the head and keeps its captured parent; see the owner supersession. Immutable objects do not replace authority, reference closure, mutable history or safe GC.

Engine-independent Project logic may consume SQLite-backed acquisition through an owning backend-neutral port. Concrete SQL and database ownership belong in Persistence/application composition along the permitted dependency direction. A guard refusal of Project's direct engine dependency identifies wrong placement; resolve that boundary before proceeding. It does not require replacing indexed backing with a custom sorter. The port and its SQLite provider now exist as an opt-in Store schema (acquisition backing), and Project's import runs on that port alone (backed acquisition). Do not weaken the boundary guard, give Project an engine dependency or reintroduce a second acquisition algorithm. See the S7/S9 remaining plan.

Filesystem access and execution ownership

Owner clarification 2026-10-08: these are implementation and proof requirements, not a claim that S8 or S10 is qualified. FUSE serves any permitted process that can see the mount. Request admission and Workspace mutation/capture must not require an Exec identity, registered command or LayerFS-launched parent. Apply the same permissions, filesystem semantics and ownership to external executors, interactive shells and ordinary Sandbox execution.

Sandbox setup or the external executor establishes command identity, mount visibility and protection of Store, Overlay and daemon credentials. Ordinary runtime execution owns standard I/O, exit status and caller-requested cancellation. SDK public organization is the eleven operations documented in the implemented SDK surface, with operation files under layerfs-api/src. Project offers init/fork/ branches/commits; Sandbox offers create/close; Workspace offers mount/exec/ commit/status/unmount. Shared control/recovery/diagnostic plumbing lives in base/ and the hidden internal module. Optional WorkspaceApi.exec selects the mounted directory and delegates the existing Sandbox launcher; the daemon has no exec/supervisor, launcher mode, per-Exec cgroups, command registration or custom Exec stream/status/cancellation protocol.

FUSE owns exact request/open/lookup/capture/Commit lifetimes and complete filesystem/daemon-work drain. Zero registered commands or shell exit is never evidence of released descriptors, mappings, kernel references or daemon jobs. Forced filesystem teardown does not implicitly kill caller-owned processes. Normal unmount uses a reversible kernel busy probe while ordinary service stays usable. Force refuses active namespace control producers before any effect.

Commit consumes the Workspace's published frontier through the shared Content, Storage and Persistence pipeline regardless of launch route. stdout/stderr are not filesystem state unless the command writes them to a file in the Workspace. The old proposed managed-daemon Exec selections are withdrawn prospectively; retain their original IDs, source pins, receipts and verdicts. Ordinary runtime stream/result correctness and filesystem-lifetime proofs keep their real owners.

S8 verification must include a process launched outside the Exec API, with no Exec registration, reading and mutating the mount and retaining a filesystem reference during an unmount attempt. S10 must prove that such changes survive Commit and a fresh mount. Use ordinary public filesystem access in these proofs.

Reviewed target source ownership2026-10-08: the replacement layerfs-fuse owns its complete native connection/request service, including bounded dispatch, parking/resumption, kernel handlers/replies and coherence. Daemon assembles one shared Fuse service with its existing SQL/Store services, retaining registry, overall Ready/unmount and Commit composition. Dependency is daemon -> fuse -> workspace, never Fuse -> daemon. Request dispatch/read ports, mount/Ready and per-Workspace normal drain are implemented (R2 record), as is ordinary native mutation (R3 record); as is the captured namespace producer with its bounded validation (R4 record), which the Commit driver reaches through the product constructor (product Commit). See the reviewed ownership. Moving blocking OwnerClient calls behind a port does not establish deferred service.

Shared construction and completion boundaries

Source checked at 5747f0119, guidance updated 2026-10-08. Namespace Init and daemon construction share Content, Storage and Persistence through their public ports. Their input adapters and publication lifecycles have distinct owners:

Input/operationExisting route
Native Init fileProject import calls Content construct_stream; bounded output batches feed Save::accept
New captured fileWorkspace CapturedFileEdits calls Content construct_runs over data/zero windows
Existing captured fileThe same adapter calls apply_indexed_edits_view_backed over an authenticated retained FileView and normalized final edits
Initial namespaceProject streams acquired bindings/inodes through Content directory/table builders
Captured namespaceWorkspace CapturedNamespace seals headers, typed values and fresh ranks into indexed records and calls Content update_filesystem_streamed_backed; names come from the retained captured reader
Captured symlink and metadataThe same producer calls Content emit_symlink for a fresh target and patches or builds the portable attribute tree; a stored symlink keeps its base content root
Object outputContent emits FinalizedObject; Storage SaveSink implements FinalizedConsumer by forwarding to Save::accept

Use the actual Store-derived construction policy and bounded capacities on both routes. Fresh construction and incremental edits use appropriate public entrypoints and common canonical formats; do not assume an incremental file root must equal a fresh full reconstruction, since retained chunk boundaries can differ. Overlay owns mutable payload, metadata, operation records and construction scratch under Workspace prefixes. Content owns canonical algorithms; Storage owns deduplication, encoding and packs; Persistence owns global Store writes. Keep SQLite types and paths out of Content and the daemon's provider-independent store/ adapter. Do not materialize a native tree or invoke Project Init to implement a Workspace Commit. Native Init acquisition backing remains a separate host provisioning facility.

Current source has captured-file normalization and the Store half of Commit. BoundWorkspace::commit captures once, begins a Save, invokes a caller-supplied Content constructor, finishes the Save, publishes through History and installs the known root locally. Full captured namespace assembly, including names, links, metadata and changed file roots, is CapturedNamespace. The product constructor BoundWorkspace::commit_captured runs it inside that driver: it acquires the captured reader and one operation owner, hands the driver the original cause on failure, and releases both owners only after the driver's outcome is known, keeping them with the failure when it is not (product Commit). A control Commit uses it; Service::execute still takes a caller's constructor for driver tests. See captured-file construction, the shared Save sink and Store Commit composition.

Keep completion boundaries explicit: Save::finish() completes object storage; Init then initializes history, while Commit calls commit_branch against its expected head before local base installation. SDK Init subsequently calls Handles::seal() to checkpoint, close and hand off one Store file. The macOS allocation correction runs only at this sole-owner Store seal; it is not a Content/pack format change or live-daemon maintenance. Linux daemons keep their shared Store open. The seal proof retains its exact platform and benchmark scope; it does not qualify daemon allocation or S10.

Optimization and performance debugging

Before changing a performance-sensitive path or diagnosing a performance finding, read the optimization guide. Its FUSE, SQLite and complexity rules are mandatory: reject quadratic or worse scaling, use SQLite-backed mutable indexes/state rather than custom duplicate trees/graphs, and account for request/SQL/IO/copy/residency/cleanup work. Preserve cluster one's canonical formats and public APIs; use count-driven evidence and the existing measurement policy. SQLite debugging/optimization claims require both database EXPLAIN and correlated runtime database profiling; overall wall time or a plan alone is insufficient. An unrelated/docs-only change does not require a campaign. The optimization handbook is the working procedure on top of those rules: the counters that already exist, the diagnostic groups, the scaling checks and the current candidate list.

Product source and external verification

core/crates/<package>/src/ contains production code exclusively, including included/generated implementation. Runtime SQL and other shipped implementation have the same ownership rules.

Forbidden in product source: inline tests/benches, test-only cfg/features, fixtures, mocks, fake clocks, fault injection, test/benchmark drivers, test-only public APIs, benchmark-selected algorithms and executable rustdoc test blocks. Platform cfgs, real features, production validation/invariants and actual telemetry remain legitimate. Put API documentation with the API; examples outside src.

ContentLocation
Product implementationcore/crates/<package>/src/ and required runtime source
Public-API tests and their helpers/fixturesPackage tests/
Runnable examplesPackage examples/
Package benchmarksPackage benches/
Product-wide harness/diagnosticsthe layerfs-benchmark repository; inspect the actual harness manifest/entrypoint
Development checkscore/tools/

Tests exercise the production library that normal consumers use. Do not include/recompile private source, redirect target paths into test directories, import helpers into production or expose an API only to enable a test. Test-only dependencies belong in dev-dependencies; retain component-specific restrictions, including std-only telemetry.

Prefer deterministic public behavior and external observations. Telemetry tests can use completed reports and structural ordering; do not add a product fake-clock interface or narrow sleep-based wall thresholds. Verify disabled behavior through its actual allocation/clock path. Scaffold no empty placeholder directories.

Production file size and responsibility

All new replacement/application-adapter production files have at most 999 physical lines, including comments/blanks. This includes required runtime SQL or other shipped formats outside Rust src. Extend guard coverage for new formats; moving implementation does not evade the rule. The legacy root source is retired; do not recreate a root crates/ for product work.

Every product lib.rs/mod.rs has at most 200 physical lines. These files contain attributes, declarations, imports/reexports, API docs and thin forwarding. Definitions, impls, state/constants encoding behavior, branching, loops, conversions, validation, formatting and I/O belong in focused named implementation files.

Split by responsibility before the ceiling: lookup, transactions, reconstruction, placement and ownership, not numbered files or a renamed god module. Use ordinary functions/concrete types; do not add a factory/interface per algorithm or a service locator. Keep actual process/provider boundaries independently usable. Do not minify, expand macros or add includes to evade size/ownership rules.

Physical line ceilings differ from production LOC. Follow the root per-commit LOC policy using exact parent/staged/committed trees and migration subtotals. Docs, tests, fixtures, examples and tools do not contribute to production LOC.

Failure, persistence and dependencies

  • One attempted operation; no automatic retry, busy handler, refresh/reprepare, error-driven algorithm/backend/reference substitution or guessed recovery. Readiness waits and explicit cancellation have their own state before an attempt; they do not permit replay after failed/unknown publication.
  • Preserve definite-failure atomicity, original errors and exact uncertain custody. No resend, rollback/delete or success claim based on an unfenced read.
  • Global Persistence uses Disposable/WAL/OFF only, on macOS and Linux, under the owner's active-profile rule. Durable execution is disabled indefinitely until explicit owner reauthorization; retained Durable source may compile but no test, diagnostic, measurement or application invocation may execute it. Select Disposable explicitly rather than relying on a default argument. Disposable claims process-crash survival only. Open verifies WAL and never converts an existing Store. Select profile/layout before open; Postgres stays unavailable. Owner supersession2026-10-07 keeps WAL throughout Init and Commit; no private MEMORY import or journal promotion remains. The measured host Init regression is retained as FAIL and accepted as the new baseline for that exact scope. Host seal consumes sole ownership, checkpoints, closes and verifies one file. Its macOS completion releases unused extents beyond logical EOF through the existing safe nix API, preserving the original file's bytes and identity. This narrow seal-only correction does not restore per-pack preallocation or the allocation owner, and is never invoked on a live shared daemon Store; see the seal boundary. See the foundation checkpoint.
  • Target (owner direction 2026-10-07): the same Store opened directly by every Linux daemon from a shared volume, several writer processes, no host in the data path, using only Disposable/WAL/OFF. A contended write still has one SQL attempt and exact failure/unknown custody. Owner clarification2026-10-12 requires one ongoing Commit per Workspace and allows concurrent Commits on different Workspaces. Bounded before-effect admission now queues SQL work within a Session and coordinates short Linux writer jobs on the existing local Store parent-directory inode; multiple Store files in one directory share this coarse short-transaction lane. Do not open/close a separate main/WAL/SHM descriptor for advisory ownership: closing a main-file descriptor can cancel SQLite's own process POSIX locks. This admission does not gate whole Saves or Commits or replay a failed SQL attempt. macOS has Session admission only; separate macOS writers and uncoordinated raw SQLite writers retain exact Busy refusal. Follow the integration contract and its deepest-file plan; do not extend the host-mediated SDK runtime, Bridge data codec or daemon upstream.
  • Store concurrency (owner decision 2026-10-18): one global database and one writer at a time are the design, not a limitation to engineer around. Keep the existing admission, directory lock and publication lane; shorten what runs inside the lane (only head check, merge and publish) instead of adding writers or databases. Judge speed on uncontended calls; contention must stay correct, bounded and exact. See the Store concurrency model.
  • The daemon overlay is a separate owner/profile from global persistence: one local database file per mounted Workspace, opened MEMORY/OFF/EXCLUSIVE by one connection behind that Workspace's lock. Workspaces share no overlay connection, page cache or memory budget. It is not an implemented distributed Store or a universal global-Store rule; reader-pool alternatives need their own proofs.
  • WAL/sync are permitted for a declared global Store profile. Do not add fsync/fdatasync/sync_data/sync_all on disposable Workspace backing. Memory hints do not prove bounds. Claim only actual completion/durability contracts.
  • No third-party patch, fork, vendor, registry edit or replacement dependency, except the owner's fuser 0.18.0 signed-timestamp correction below. Use existing capabilities and locked builds; report an incompatible required dependency with source evidence. Unsupported required platforms/capabilities fail explicitly, not via a silent no-op or fallback.

Checks and completion

Run commands from the repository root with the actual core manifest. For product, API, manifest or runtime-source changes, cover tests/examples, warning-denying Clippy and formatting, plus the boundary guard and its self-tests:

cargo +1.85.1 test --manifest-path core/Cargo.toml --locked --all-targets
cargo +1.85.1 clippy --manifest-path core/Cargo.toml --locked --all-targets -- -D warnings
cargo +1.85.1 fmt --manifest-path core/Cargo.toml --all -- --check
python3 -B core/tools/check_product_boundary.py
python3 -B -m unittest discover -s core/tools -p 'test_*.py'

Every test invocation obeys the repository's 2-minute test ceiling: run it under an explicit timeout of at most 120 s, per package when the whole suite cannot fit, and treat reaching the ceiling as a hang to diagnose, not a run to wait for.

Migrations and refactors follow the root delete-rather-than-nurse rule: delete a test that is tricky to adapt, keep or move only cheap tests of surviving behaviour, and re-cover any still-valid fix or contract on the new code. fs-bench-pro (in layerfs-benchmark) is frozen and left broken (owner, 2026-10-18): do not build, run, check or repair it.

For docs-only changes, check links/anchors, status/claim accuracy and whitespace; report why Rust/runtime checks are inapplicable. For tooling/harness changes run the owning scoped tests. At final implementation identity run required covering checks once; diagnose a failure from its output/source before a justified repair and rerun. Do not repeat unchanged passing checks or run an unrelated legacy sweep.

The guard checks source text, line caps and common prohibited constructs, including markers embedded in source comments/strings. It is not a Rust semantic or runtime proof. Review ordinary macros, helpers, dependency/target declarations and generated inputs; extend scanners for new shipped formats. An excluded FUSE/daemon package is not exercised by passing active-workspace tests.

CI reports after a push and never gates it (see the root rule); test lane selection is tools/ci_tests.py. When a test target is renamed, moved or measured at 5 s or more, update its SLOW list; Linux-only daemon targets go to the nightly mount lane automatically. There is no pre-push gate; tools/preflight.sh is retired. Do not disable discovery or recreate an equivalent wrapper. Report exact checks, failures and gaps. A scan or proposal alone does not establish implementation.

Build flags are part of the check

aarch64 binaries retain the repository ARMv8 AEAD build inputs: --cfg aes_armv8 --cfg polyval_armv8 --cfg chacha20_force_neon -C target-feature=+aes,+sha2. The root Cargo config is discovered from the working directory, not by a manifest path into core. Builds outside the repository or with explicit RUSTFLAGS must repeat that profile. Record flags/config in build identities; preserve the transport's required-profile refusal when integrating it. Documentation builds do not prove the binary profile.

Measurement work additionally follows the agent measurement workflow and owning core harness guide. Frozen identities, cache states and budgets are evidence contracts, not product runtime limits.

Fuser provenance and authorized-patch checks

Additional owner authorization 2026-10-14: "you are allowed to modify fuser with patch". The receive-buffer decision records the scope. Receive loops read into the max_write + 4096 bytes negotiated at INIT instead of fuser's 16 MiB + 4 KiB maximum. The delta is in read_buf.rs, session.rs and session/lifecycle.rs, applied after the lifecycle patch. receive-buffer.patch and receive-buffer-provenance.json pin it, and the focused check verifies it. The earlier records stay unchanged.

Additional owner authorization2026-10-08: the scoped receive-loop lifecycle extension may extend the pinned fuser0.18.0 package beyond time.rs to establish loop entry/exit, retained startup/join ownership and the proposed explicit lifecycle API. This narrowly supersedes the timestamp-only file restriction below. Preserve the original timestamp provenance unchanged; record and verify the lifecycle delta separately. No other dependency change or general unsafe exception is authorized. Permission does not establish implementation or native Ready/drain qualification.

Latest owner direction2026-10-06: "use fuser 0.18.0 from crates io and apply patch". This supersedes the earlier registry-only/no-patch ruling for this one correction. Keep the dependency version exactly0.18.0; use the checked-in copy of its official crates.io archive with only src/time.rs changed by the recorded upstream timestamp fix and regression tests. Both owning workspace roots use the exact path/version [patch.crates-io] entry. Do not edit shared Cargo registry packages, adopt a Git dependency, or extend this exception to unrelated source/dependency changes.

The original archive checksum, all85 published file hashes, exact diff and patched time.rs hash are pinned in patches/fuser-0.18.0/provenance.json and checked by the focused guard. A patched Cargo.lock entry has no registry checksum; the explicit provenance record authenticates its modified bytes. See the authorized patch record. Native qualification and the complete S8 contract remain separate requirements.

Subsequent owner direction2026-10-06: "docker verification is enough". Existing native Docker proofs are accepted for verifying this fuser correction. Retain Linux's fractional signed-minimum endpoint outcome as a platform limitation; do not require QEMU or a custom-kernel campaign to verify the dependency fix. This acceptance does not complete S8's product implementation or turn that individual native FAIL into PASS. Continue the remaining S7–S9 work using Docker.

Before a native fuser build, run the focused provenance check:

python3 -B core/tools/check_fuser_integrity.py

For an installed registry source, also supply its archive, package directory and checksum taken from its original registry lock or the pinned base-archive record with --archive, --package-directory and --locked-checksum. This reads and verifies package files without modifying them. Run scoped self-tests when changing the check. It is not an aggregate pre-push/CI wrapper or a timestamp-capability proof. Current evidence and the historically rejected unmodified Git candidate are in the fuser verification record.

Authorized Persistence seal file control

Owner authorization 2026-10-07: "Approve the narrowly audited seal wrapper". The system macOS SQLite enables persistent WAL and otherwise leaves empty sidecars after checked close. Persistence uses deny(unsafe_code) with one allowed module, src/backend/sqlite/file_control.rs, compiled on macOS only. It sets and reads back SQLITE_FCNTL_PERSIST_WAL under sole seal ownership. No other Persistence module may contain unsafe Rust; the guard and its tests enforce the exact path. This does not authorize third-party patches, dependency changes, manual sidecar deletion or other FFI. See the decision and diagnostic.

Download now (ZIP)

Trending

Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Aug 30: 0 new projectsWeek of Sep 6: 0 new projectsWeek of Sep 13: 0 new projectsWeek of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projects
Aug 2026Sep 2026Oct 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 0 in all, so this is a hint, not a trend.

Who's talking about Ephemeral-AI-Lab/layerfs

The biggest 5 of 8 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 8

Talked about on GitHub and Bluesky (8 times).

On GitHub · 6

1 more on GitHub
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 28,693 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository3 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.