# CoreShift-Core
CoreShift-Core is the low-level Linux/Android primitives crate at the bottom of
the CoreShift stack.
```text
Policy / product behavior
↓
Engine coordination
↓
Core syscall and filesystem primitives ← this crate
```
Core exposes explicit wrappers for process spawning, file descriptor handling,
procfs parsing, signals, reactor primitives, inotify, Unix sockets, and
filesystem preload helpers. It does not choose Android policy, foreground app
behavior, package discovery, daemon protocols, or preload rules.
## Modules
| `spawn` | Explicit process spawning (`PosixSpawn` / `Fork` / `Vfork` / `Clone3` / `Clone3Pidfd`), pty spawn, process groups, bounded output, blocking + managed async lifecycle |
| `process` | Raw process primitives: `fork`, `setsid`, `setpgid`, `setuid/gid`, `set_pdeathsig` (fires on parent-**thread** exit), `close_fds_from`, `redirect_*` devnull/fd helpers |
| `io` | Explicit drain helpers: `DrainState`, `ChunkSink`/`SinkResult` streaming, stdin write, bounded output, resume/backpressure |
| `reactor` | `epoll`-based fd readiness (`Reactor`: add/add_priority/add_with_flags/del, signalfd + inotify integration, wait) |
| `fd` | Owned descriptor wrapper: `Fd`, `Token`, `Event`, `eventfd`, `timerfd` |
| `fs` | Filesystem probes, readahead, `fadvise`, `mmap_madvise`, symlink-safe read/write |
| `proc` | procfs helpers: `/proc/<pid>/cmdline`, `/proc/<pid>/status`, stat, uid/path ownership |
| `signal` | Signal masking, `signalfd`, `install_shutdown_flag`, `register_handler`, `SignalRuntime` |
| `socket` | Abstract + pathname Unix domain socket bind/connect/accept, `PeerCred` |
| `inotify` | Watch setup and event decode (`InotifyEvent`, packaged watch masks) |
| `uevent` | kobject uevent socket (`open`, `recv`, `drain_battery`) — primitive only; no in-tree consumer yet |
| `drm` | `DrmCard::open` + `wait_vblank` — primitive only; no in-tree consumer yet |
| `transport` | Command/watcher transport seam (`TransportEvent`, `ReplySink`, `WatcherSink`) |
| `log` | Backend-agnostic logging facade (`Logger`, `LogBackend`, `LogLevel`, 12 macros) |
| `error` | `CoreError` and `errno` constants |
| `binder` | NDK binder client: `ActivityManager`, `DisplayManager`, `FpsListener`, `TaskStackListener`, `RawBinderService`, `Handoff`, serving primitives (Android only) |
| `android` | `property` (get/set/find/read/serial/wait + `AndroidPropertyStore` trait) and `dex` (ZIP + DEX parser resolving `TRANSACTION_*` codes) |
## Binder observer
`ActivityManager::open_with_observer()` registers the calling process as an
`IProcessObserver` with ActivityManager and returns an `eventfd` that fires on
`onForegroundActivitiesChanged`. Transaction codes are resolved by parsing
`TRANSACTION_*` fields directly from `framework.jar` DEX at startup — no
subprocess required.
See [docs/BINDER_OBSERVER.md](docs/BINDER_OBSERVER.md) for full details.
## Documentation
- [Architecture](docs/ARCHITECTURE.md)
- [Binder Observer](docs/BINDER_OBSERVER.md)
- [Binder Serving](docs/BINDER_SERVE.md)
- [I/O Subsystem](docs/IO_SUBSYSTEM.md)
- [Unix Sockets](docs/SOCKET.md)
- [Procfs and Process Identity](docs/PROCFS.md)
- [Fd: Owned Descriptors](docs/FD.md)
- [Inotify](docs/INOTIFY.md)
- [Transport Seam](docs/TRANSPORT.md)
- [Uevent and DRM](docs/UEVENT_DRM.md)
- [Logging](docs/LOGGING.md)
- [Signal Handling](docs/SIGNAL_HANDLING.md)
- [Preload primitives](docs/PRELOAD_PRIMITIVES.md)
- [Testing](docs/TESTING.md)
## License
Mozilla Public License 2.0. See [LICENSE](LICENSE).