# local/patches/ — patch archive structure

**Last updated:** 2026-07-12 (Round 7)
**Status:** Build system at 100% patch preservation. 121 active
patches + 159 archived = 280 total cataloged patches.

## Layout

```
local/patches/
├── README.md                                  # this file
├── <comp>/                                    # ACTIVE patches (121)
│   ├── <fork>/                                # base, kernel, relibc, ...
│   │   ├── P3-*.patch                         # applied by cookbook
│   │   └── redox.patch                         # legacy all-in-one (gitignored)
│   ├── <fork>/absorbed/                       # historical snapshots
│   │   └── P3-*.patch                         # PATCHES BEFORE they were committed
│   │                                          # to fork via mega-absorption. Recoverable.
│   └── <fork>/.gitignore'd                    # cargo metadata etc
├── legacy-superseded-2026-07-12/              # Round 2-6 archive (97)
│   ├── README + SUPERSEDED.md                 # per-component audit log
│   ├── base/, kernel/, relibc/, redoxfs/, userutils/
│   └── P3-*.patch                             # classified-SUPERSEDED
└── legacy-absorbed-2026-07-12/               # Round 2-3 archive (62)
    ├── README + SUPERSEDED.md                 # per-component audit log
    ├── base/, kernel/, relibc/, userutils/
    └── P3-*.patch                             # classified-INTEGRATED
```

## What's an "absorbed" patch?

A patch is moved to `legacy-absorbed-2026-07-12/` when Round 2-3's
supersession classifier determined that **the same fix is already
committed to the fork's HEAD** under a different commit subject. The
.patch file is preserved as historical documentation but is no longer
applied during build. This is **operator-supersession** under AGENTS.md
"Upstream-first rule for fast-moving components".

The patch's content IS in the fork. Re-applying would either:
- Be a no-op (`patch -N` for already-applied) — safe
- Cause a real conflict (if fork content has since evolved past the
  patch's intent) — operator decision needed

## What's a "superseded" patch?

A patch is moved to `legacy-superseded-2026-07-12/` when its content
is no longer needed at all — either:
- Upstream Redox's newer tag already provides equivalent functionality
  (canonical "upstream preferred" path)
- The fork's file structure has been rebased past the patch's
  expectations (file-restructured)
- The operator cleaned up the corresponding code as part of a
  refactor (operator-superseded)

The patch's content is NOT in the fork. Re-applying would create
unintended work. Recovery: rebase fork onto newer upstream or accept
the operator's refactor.

## How to recover a patch

```bash
# Move patch back to active location
cp local/patches/legacy-superseded-2026-07-12/<comp>/<patch>.patch \
   local/patches/<comp>/

# Optionally try applying it (will probably be a no-op for INTEGRATED,
# may fail for SUPERSEDED)
cd local/sources/<comp>
git apply --check -N -p1 < ../../local/patches/<comp>/<patch>.patch
```

## Tooling

The patch audit tool runs as part of `pre-push-checks.sh`:

```bash
./local/scripts/pre-push-checks.sh
```

The 5 checks are: sync-versions, verify-fork-versions,
verify-patch-content, verify-collision-detection, and the collision
selftest. All must pass for the pre-push hook to allow a `git push`.

For a full operator-decision guide on what to do with new orphans,
see `local/docs/PATCH-PRESERVATION-AUDIT-2026-07-12.md` (the "Out-of-
scope" section tracks the current Round 5+6 forward work).

## Round 7 snapshot

| Directory | Count | Source |
|-----------|-------|--------|
| `*/` (active) | 121 | operator's working fork state |
| `legacy-superseded-2026-07-12/` | 97 | Round 2-6 SUPERSEDED audits |
| `legacy-absorbed-2026-07-12/` | 62 | Round 2-3 INTEGRATED audits |
| `legacy-recipe-patches/` | 0 | (deleted in Round 1.2; not a separate dir anymore) |
| **Total cataloged** | **280** | |

## Notes

- Each legacy/ directory has its own SUPERSEDED.md audit log with
  per-component tables of what was archived, when, and why.
- The `absorbed/` subdir under each active component (`base/absorbed/`,
  `relibc/absorbed/`) was removed in Round 3.0; its content was
  consolidated into `legacy-absorbed-2026-07-12/<comp>/`. The `absorbed/`
  under each component's recipe was Round 2's experimental split.
- New orphans detected by `verify-patch-content.sh` are NOT
  automatically archived — that's an operator decision. See
  `local/scripts/verify-patch-content.sh --help` (no current
  options; future work: add a `--auto-archive` mode).