jerboa-inotify

Linux inotify filesystem event monitoring for Jerboa.

Status: experimental and Linux-only. Treat this repository as a native FFI filesystem component until the release gates in SECURITY.md and docs/ffi-boundary.md are complete.

Requirements

• Linux with inotify support
• Jerboa jerbuild
• C compiler

Build And Test

make test-linux
make audit
make security
make platform-evidence
make sbom
make reproducibility-report
make release-evidence

On non-Linux hosts, make test transpiles the Jerboa source and skips runtime tests. CI runs the real kernel tests on Ubuntu.

Dynamic builds must set JERBOA_INOTIFY_LIB to the absolute path of the trusted directory containing jerboa_inotify_shim.so. The loader rejects relative paths, current-working-directory searches, bare library names, and a final shim path that is a symbolic link. Statically linked hosts are detected from the registered native entry points and do not need this variable.

If jerbuild is not installed, the Makefile bootstraps the pinned Jerboa release into .jerboa/bin.

make release-evidence records test output, platform evidence, native linkage when Linux is available, SBOM manifests, and reproducibility output under dist/release-evidence/. On non-Linux hosts it is expected to report partial evidence because inotify runtime checks require the Linux kernel.

Production Linux support is blocked until make platform-evidence records Linux runtime/linkage proof and overflow/backpressure proof through JERBOA_INOTIFY_TARGET_LINUX_PROOF_FILE and JERBOA_INOTIFY_TARGET_OVERFLOW_PROOF_FILE, or a Linux release host runs the full evidence target directly. Production release hosts should set the matching JERBOA_INOTIFY_REQUIRE_TARGET_*_PROOF=1 variables when proof files are required. Proof files must not contain private paths, hostnames, secrets, raw production watch output, or raw command output.

Usage

(import (jerboa-inotify))

(define fd (inotify-init))
(define wd (inotify-add-watch fd "/path/to/watch"
             (bitwise-ior IN_CREATE IN_DELETE IN_MODIFY)))

(when (inotify-poll fd 5000)
  (for-each
    (lambda (ev)
      (printf "wd=~a mask=~a name=~a~%"
        (inotify-event-wd ev)
        (inotify-event-mask ev)
        (inotify-event-name ev)))
    (inotify-read-events fd)))

(inotify-rm-watch fd wd)
(inotify-close fd)

Consumers must handle IN_Q_OVERFLOW by rescanning watched state. Inotify does not recursively watch directory trees. Production callers should follow docs/overflow-handling.md for cache invalidation, backpressure, and path-log redaction.

API

Function	Description
(inotify-init)	Create inotify instance, returns fd
(inotify-close fd)	Close inotify fd
(inotify-add-watch fd path mask)	Add watch, returns wd
(inotify-rm-watch fd wd)	Remove watch
(inotify-poll fd timeout-ms)	Poll for events
(inotify-read-events fd)	Read pending events

Event Record

Accessor	Description
(inotify-event-wd ev)	Watch descriptor
(inotify-event-mask ev)	Event mask
(inotify-event-cookie ev)	Cookie for rename tracking
(inotify-event-name ev)	Filename or #f

Security

See SECURITY.md, docs/ffi-boundary.md, docs/overflow-handling.md, and docs/release-evidence.md.