From 9698efe138739beeee40878fe83e2344371918a0 Mon Sep 17 00:00:00 2001
From: Admin Pupkin <adminpupkin@gmail.com>
Date: Sat, 30 May 2026 08:16:51 +0300
Subject: [PATCH] docs: add safe-to-pull-from-upstream list to FULL FORK
 PRINCIPLE

Document which Redox components are safe to pull from upstream
vs which we must fork. Clear distinction between:

Safe to pull (Redox ABI/system internals):
- redox_syscall, redox-scheme, libredox (crates)
- pkgar, pkgar-core, pkgar-keys, redox-pkg (package format)
- ion, dash, coreutils, extrautils, netutils, strace (utilities)
- orbital, orbdata, orbterm, orbutils (legacy display)
- contain, profiled, netdb, pkgutils, findutils (daemons)
- redoxer (build tool)

Must fork (we add features):
- Kernel, relibc, base, bootloader, installer (core OS)
- Mesa, libdrm, qtbase (graphics stack)
- redox-driver-sys, linux-kpi, redox-drm (GPU drivers)

Rule of thumb: if it defines the Redox ABI, pull from upstream.
If we add features to it, fork it.
---
 AGENTS.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 6cde48835e..c9b42e972e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -41,6 +41,67 @@ This means:
 - If a Cargo dependency breaks, we fork the dependency crate to `local/sources/` and pin our Cargo.toml to our fork.
 - The Linux kernel in `local/reference/` is read-only reference — never a dependency.
 
+### Safe to Pull from Upstream (Redox System Internals)
+
+These are Redox-specific libraries, tools, and protocols that form the stable ABI
+between the kernel and userspace. We do NOT modify these — we pull them from upstream
+with pinned revisions. Forking them would create divergence from the Redox ABI and
+cause silent breakage.
+
+**Crates (pulled via Cargo, NOT via recipe git URLs):**
+
+| Crate | Why safe | Notes |
+|---|---|---|
+| `redox_syscall` | Syscall numbers, types, flags — must match kernel ABI | Maintained by Redox; we never modify syscall numbers |
+| `redox-scheme` | Scheme protocol (`SchemeSync`, `SchemeAsync` traits) | Stable protocol; our daemons implement it |
+| `libredox` | High-level syscall wrappers (`call_ro`, `call_wo`) | Thin wrapper; if it breaks we fork it |
+| `pkgar` / `pkgar-core` / `pkgar-keys` | Package format (archive, signing, manifest) | Stable ABI; used by installer and repo tool |
+| `redox-pkg` | Package dependency resolution | Used by cookbook; we don't modify |
+| `redox_installer` | Filesystem image creation | **We forked this** — ext4 + GRUB support |
+| `redoxer` | Cross-compilation wrapper | Build tool; we use it as-is |
+
+**Recipes (gitlab URLs — safe to pull from upstream):**
+
+| Recipe | Why safe | Notes |
+|---|---|---|
+| `core/pkgar` | Package format tools | Matches `pkgar` crate ABI |
+| `core/ion` | Shell | We don't modify shells |
+| `core/dash` | POSIX shell | Redox port, we don't modify |
+| `core/coreutils` | Core utilities | From uutils; we don't modify |
+| `core/extrautils` | Extra utilities | Redox-specific; we don't modify |
+| `core/findutils` | File search | We don't modify |
+| `core/netdb` | Network database | Redox-specific |
+| `core/netutils` | Network utilities | Redox-specific |
+| `core/pkgutils` | Package utilities | Redox-specific |
+| `core/profiled` | Profiler daemon | Redox-specific |
+| `core/strace` | Syscall tracer | Redox-specific |
+| `core/contain` | Container runtime | Redox-specific |
+| `gui/orbital` | Legacy display server | We use Wayland; not modified |
+| `gui/orbdata` | Legacy display data | Not modified |
+| `gui/orbterm` | Legacy terminal | Not modified |
+| `gui/orbutils` | Legacy display utils | Not modified |
+| `dev/redoxer` | Cross-compilation wrapper | Build tool |
+| `kernel/kernel` | Sub-recipe | Main kernel is OUR fork in `local/sources/kernel/` |
+
+**Rule of thumb:** If it defines the Redox ABI (syscall numbers, scheme protocol,
+package format), we pull from upstream. If we add features to it, we fork it.
+
+### What We MUST Fork (things we modify)
+
+| Component | Our fork | Why forked |
+|---|---|---|
+| Kernel | `local/sources/kernel/` | ACPI, x2APIC, MSI/MSI-X, scheduling, branding |
+| relibc | `local/sources/relibc/` | eventfd, signalfd, timerfd, waitid, SysV IPC |
+| Base (drivers) | `local/sources/base/` | acpid, pcid, inputd, ps2d, xhcid migrations |
+| Bootloader | `local/sources/bootloader/` | UEFI alloc fix, branding, GPT offset |
+| Installer | `local/sources/installer/` | ext4 + GRUB bootloader integration |
+| Mesa | `local/recipes/libs/mesa/` | virgl disk cache, GBM dumb prime export |
+| libdrm | `local/recipes/libs/libdrm/` | ioctl bridge, PCI info, device enumeration |
+| QtBase | `local/recipes/qt/qtbase/` | futex redox support, wayland guards |
+| redox-driver-sys | `local/recipes/drivers/redox-driver-sys/` | Hardware quirks system |
+| linux-kpi | `local/recipes/drivers/linux-kpi/` | GPU + Wi-Fi compatibility headers |
+| redox-drm | `local/recipes/gpu/redox-drm/` | Intel + AMD display drivers |
+
 ## BUILD SYSTEM DURABILITY — THE CARDINAL RULE
 
 **SOURCE LIVES IN `local/sources/<component>/`. EDIT THERE. `recipes/*/source/` IS A SYMLINK