POSIX and filesystem semantics - KiwiFS — Markdown filesystem for agents and teams

KiwiFS stores real files on disk. POSIX behavior depends on how you access them.

Compliance by access path

Access path	POSIX level	Notes
Direct filesystem	Full	Real files, atomic writes, mmap works
NFS mount	Near-full	Symlinks, open-unlink, stable handles
FUSE mount	Near-full	Remote client; no kernel mmap
WebDAV	Partial	MOVE/COPY/MKCOL; buffered writes
REST / S3 / MCP	N/A	HTTP or tool semantics

Semantic	NFS	FUSE
Atomic writes (tmp → fsync → rename)	Yes	Yes
`rename(2)`	Yes	Yes
Symlinks	Yes	Yes
Open-then-delete (POSIX unlink)	Yes	—
`fsync`	Yes	Yes
Directory rename	Yes	Yes
`readdir` hides `.git`, `.kiwi`	Yes	Yes
64 MB max file size (`EFBIG`)	Yes	Yes

Optimistic locking

If-Match / ETag on REST writes. Returns 409 on conflict.

Serialized writes

One mutex across all protocols. Concurrent writers are safely queued.

Single-instance guard

flock on .kiwi/server.lock. Released automatically on process exit (including SIGKILL).

Git lock recovery

A background watcher cleans stale index.lock every 10 seconds (60-second threshold). Also cleaned at startup.

Line-ending integrity

core.autocrlf=false and * -text in .gitattributes. ETags always match raw bytes.

FUSE does not support kernel mmap (HTTP-backed I/O).
WebDAV is not a full POSIX layer.
Two KiwiFS servers must not share one knowledge root — the lock prevents split-brain.

Symlinks work on NFS (real os.Symlink) and FUSE/REST (Content-Type: application/x-symlink). Targets escaping the knowledge root are rejected.

curl 'http://localhost:3333/api/kiwi/readlink?path=link.md'

NFS, S3, WebDAV, FUSE setup.

Storage philosophy.

Last modified on May 23, 2026