# Red Bear OS: Ecosystem Adaption Policy

**Rule (per user directive):** Red Bear OS internal projects MUST always update,
adapt, and go inline with Redox ecosystem changes. Red Bear adapts to Redox,
not the other way around.

## How Ecosystem Pinning Works

The Redox crate ecosystem has version coupling: `libredox`, `redox-scheme`,
`redox_syscall` MUST be on a consistent version set across all crates in a
build. Mixing old and new versions causes `call_ro`/`call_wo` and
`syscall::Error` vs `libredox::error::Error` type errors.

### Canonical Versions (as of build session 2026-06-26)

| Crate | Version | Why this version |
|-------|---------|------------------|
| `libredox` | `=0.1.18` | Current upstream version in fork-upstream-map.toml |
| `redox-scheme` | `=0.11.2` | Current upstream version in fork-upstream-map.toml |
| `redox_syscall` | `=0.9.0` | Current upstream version in fork-upstream-map.toml |

**Note on version selection rationale (per "latest versions only" rule):**
Redox ecosystem is mid-migration (2026-05-27 → 2026-06-01 transition). The
transition broke compatibility for upstream consumers. Per research:

- `redox-scheme 0.11.1` (2026-05-27) bumped `redox_syscall ^0.7.3 → ^0.8.0`
  AND `libredox ^0.1.12 → ^0.1.17`
- `redoxfs master` (2026-06-24) still uses `redox-scheme 0.11.0` (NOT 0.11.1)
  with `redox_syscall 0.7.5` and `libredox 0.1.13`
- `redox_installer master` (2026-05-27) still uses `redox_syscall 0.7`
  and `redoxfs 0.9`
- Red Bear syscall fork is currently aligned with upstream `0.9.0` (the first jump past `0.7.x`)

So the current **mutually-aligned** ecosystem is `redox-scheme 0.11.2` on `redox_syscall 0.9.0`. When upstream `redoxfs` and the rest of the fork map move together, keep this table aligned to the values in `local/fork-upstream-map.toml`:

| Crate | New Version |
|-------|-------------|
| `libredox` | `=0.1.18` |
| `redox-scheme` | `=0.11.2` |
| `redox_syscall` | `=0.9.0` |

Use the current map values to keep the ecosystem aligned.

## How to Pin Ecosystem Versions in a Red Bear Recipe

### For Red Bear local recipes (in `local/recipes/`):

**Single-package files** (no `[workspace]`):

```toml
[dependencies]
# These are pinned to latest ecosystem versions.
libredox = "=0.1.18"
redox-scheme = "=0.11.2"
redox_syscall = "=0.9.0"
```

**Workspace roots** (`[workspace]` section):

```toml
[workspace.dependencies]
# Red Bear OS must adapt to upstream Redox ecosystem changes.
# These pins force unified versions across the workspace.
libredox = "=0.1.18"
redox-scheme = "=0.11.2"
redox_syscall = "=0.9.0"
```

Then in member crates:
```toml
[dependencies]
libredox = { workspace = true }
redox-scheme = { workspace = true }
redox_syscall = { workspace = true }
```

### For upstream Redox recipes (kernel, base, relibc, etc.):

Upstream recipes cannot be modified directly. Use the patch system in
`local/patches/<component>/` to bump the ecosystem pins in their
`Cargo.lock` (and Cargo.toml where needed).

Reference patch: `local/patches/base/P9-redox-scheme-latest-deps.patch`.

## Anti-Patterns (Do Not Do)

### ❌ `[patch.crates-io]` with `version = "..."` syntax

```toml
[patch.crates-io]
libredox = { version = "0.1.17" }  # WRONG!
```

This is INVALID. Cargo treats `version = "X.Y.Z"` as a patch pointing to the
same source (crates.io), which conflicts with itself. You get the error:

```
error: patch for `libredox` points to the same source, but patches must
       point to different sources
```

Use `[workspace.dependencies]` with `=X.Y.Z` for version-only enforcement
instead.

### ❌ `[patch.crates-io]` with `git = ...` for ecosystem crates

```toml
[patch.crates-io]
redox-scheme = { git = "https://..." }  # WRONG!
```

Use crates.io directly. Only `ring` (a Redox fork that doesn't exist on
crates.io) should use `git = ...`.

### ❌ Loose version specifiers

```toml
[dependencies]
libredox = "0.1"     # WRONG! Allows any 0.1.x
redox-scheme = "^0.11"  # WRONG! Allows any 0.11.x
```

Use `=X.Y.Z` to force EXACT versions. This is critical for ecosystem consistency.

## Maintenance Scripts

Three helper scripts in `/tmp/` (during build session, can be moved to
`local/scripts/`):

- `apply_ecosystem_pins.py` — Adds `[patch.crates-io]` (initial step, now superseded)
- `fix_workspace_pins.py` — Detects and fixes `[patch.crates-io]` version-only bugs
- `fix_all_pins_v2.py` — Comprehensive fix: moves version-only patches to
  `[workspace.dependencies]`, updates existing entries to `=X.Y.Z`, removes
  empty `[patch.crates-io]` blocks
- `dedupe_deps.py` — Removes duplicate ecosystem crate entries in
  `[dependencies]`/`[workspace.dependencies]`

## When to Re-pin

Re-check the canonical versions whenever:
- Redox releases a new `libredox`/`redox-scheme`/`redox_syscall` on crates.io
- A Redox upstream recipe bumps its ecosystem pins
- A new Red Bear local recipe is added that needs ecosystem crates
- Build fails with `call_ro`/`call_wo` or `syscall::Error` mismatch errors