> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POSIX and filesystem semantics

> POSIX compliance by access path — NFS, FUSE, atomic writes, and concurrency.

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                |

## What works on NFS and FUSE

| 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  |

## Concurrency and durability

<AccordionGroup>
  <Accordion title="Optimistic locking">
    `If-Match` / ETag on REST writes. Returns `409` on conflict.
  </Accordion>

  <Accordion title="Serialized writes">
    One mutex across all protocols. Concurrent writers are safely queued.
  </Accordion>

  <Accordion title="Single-instance guard">
    `flock` on `.kiwi/server.lock`. Released automatically on process exit (including SIGKILL).
  </Accordion>

  <Accordion title="Git lock recovery">
    A background watcher cleans stale `index.lock` every 10 seconds (60-second threshold). Also cleaned at startup.
  </Accordion>

  <Accordion title="Line-ending integrity">
    `core.autocrlf=false` and `* -text` in `.gitattributes`. ETags always match raw bytes.
  </Accordion>
</AccordionGroup>

## Intentionally limited

<Warning>
  * 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.
</Warning>

## Symlinks

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

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/readlink?path=link.md'
```

## Related documentation

<CardGroup cols={2}>
  <Card title="Alternate protocols" icon="network-wired" href="/guides/alternate-protocols">
    NFS, S3, WebDAV, FUSE setup.
  </Card>

  <Card title="Files as truth" icon="file" href="/concepts/files-as-truth">
    Storage philosophy.
  </Card>
</CardGroup>