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.13	Latest version compatible with redox-scheme 0.11.0 ecosystem
redox-scheme	=0.11.0	Latest version still compatible with redox_syscall 0.7.x (used by redoxfs master)
redox_syscall	=0.7.5	Latest 0.7.x; matches redoxfs master pinning

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
• NO upstream consumer has migrated to redox_syscall 0.8.x yet

So the latest mutually-compatible ecosystem is redox-scheme 0.11.0 (still on redox_syscall 0.7.x). When upstream redoxfs bumps to redox_syscall 0.8.x and redox-scheme 0.11.1, this table should be updated to:

Crate	New Version
libredox	=0.1.17
redox-scheme	=0.11.1
redox_syscall	=0.8.1

Until then, use the 0.11.0 track to keep redoxfs working.

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.17"
redox-scheme = "=0.11.1"
redox_syscall = "=0.8.1"

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.17"
redox-scheme = "=0.11.1"
redox_syscall = "=0.8.1"

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