RedBear-OS/local/docs/ECOSYSTEM-ADAPTION-POLICY.md

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]):

[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):

[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:

[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

[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

[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

[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