RedBear-OS/local/docs/RELIBC-COMPLETENESS-AND-ENHANCEMENT-PLAN.md

Red Bear OS relibc Assessment and Improvement Plan

Purpose

This document is the canonical Red Bear assessment of relibc quality, completeness, and robustness.

It is intentionally stricter than older relibc notes. This pass is grounded in what is visible in:

• the upstream-owned working tree under recipes/core/relibc/source/,
• the active relibc recipe patch list in recipes/core/relibc/recipe.toml,
• the durable Red Bear patch carriers under local/patches/relibc/,
• and the tests added by the active patch chain.

It does not flatten those evidence types into one generic claim of "implemented".

Evidence model

Use these labels consistently when describing relibc in this repository:

• plain-source-visible: present in the current upstream-owned recipes/core/relibc/source/ tree without relying on recipe patch replay
• recipe-applied: added only when the active relibc recipe replays Red Bear patch carriers
• test-present: test coverage exists in the source tree or the active patch chain
• documented downstream build evidence: another in-repo document records downstream build success, but that success was not re-executed as part of this documentation pass
• runtime-unrevalidated in this pass: do not describe as runtime-trusted here unless this review actually reran it

This distinction matters because the largest relibc documentation problem in the repo was overclaiming plain-source convergence when the active build still depends on a substantial recipe-applied patch chain.

Ownership boundary

• recipes/core/relibc/source/ is an upstream-owned working tree and may be replaced on refresh.
• recipes/core/relibc/recipe.toml defines the currently active relibc build surface.
• local/patches/relibc/ is the durable Red Bear compatibility carrier set.
• local/docs/ is the durable explanation of what Red Bear currently depends on and why.

For relibc, the honest maintenance target is:

fresh upstream relibc sources can be refetched, the active Red Bear relibc patch chain can be replayed, and the same intended build surface can be reconstructed.

Current implementation assessment

1. Plain source and active build are materially different

The current upstream-owned header tree still contains clear incompleteness markers in recipes/core/relibc/source/src/header/mod.rs, including:

• iconv.h
• mqueue.h
• spawn.h
• sys/msg.h
• threads.h
• wordexp.h

The live source tree also still shows relibc areas that are not yet plain-source-complete:

• recipes/core/relibc/source/src/header/semaphore/mod.rs still contains todo!("named semaphores")
• recipes/core/relibc/source/src/header/ifaddrs/mod.rs still returns ENOSYS
• recipes/core/relibc/source/src/header/mod.rs still keeps sys/ipc.h, sys/sem.h, and sys/shm.h behind TODO comments

That means older wording such as "now source-visible in the current tree" was too strong for much of the current relibc surface.

2. The active relibc build relies on a broad patch chain

The active recipe in recipes/core/relibc/recipe.toml currently replays more than redox.patch. The tracked patch list still includes, among others:

• redox.patch
• P0-strtold-cpp-linkage-and-compat.patch
• P3-eventfd.patch
• P3-signalfd.patch
• P3-signalfd-header.patch
• P3-timerfd.patch
• P3-waitid.patch
• P3-semaphore-fixes.patch
• P3-socket-cred.patch
• P3-elf64-types.patch
• P3-open-memstream.patch
• P3-ifaddrs-net_if.patch
• P3-fd-event-tests.patch

So the active Red Bear relibc story is still recipe-applied compatibility plus partial upstream source, not a nearly converged plain-source state.

3. What the active patch chain actually provides

Observed directly from the current patch set:

• P3-eventfd.patch: adds sys/eventfd.h support through /scheme/event/eventfd/...
• P3-signalfd.patch: adds signalfd / signalfd4 support through /scheme/event plus signal-mask handling
• P3-timerfd.patch: adds sys/timerfd.h support through /scheme/time/{clockid}
• P3-waitid.patch: adds a bounded waitid() implementation plus a focused test
• P3-semaphore-fixes.patch: adds named semaphore support on top of shm_open() / mmap() and fixes unnamed semaphore error behavior
• P3-open-memstream.patch: adds open_memstream() plus a focused stdio test
• P3-ifaddrs-net_if.patch: adds a bounded ifaddrs / net_if surface that currently synthesizes only loopback and eth0
• P3-fd-event-tests.patch: adds focused eventfd, signalfd, and timerfd tests

This is meaningful progress, but it is still a patch-carried compatibility layer, not a finished libc surface.

4. Fresh bounded-wave verification in this pass

This documentation pass also executed a fresh bounded relibc verification cycle against the active recipe surface:

• ./target/release/repo unfetch relibc
• ./target/release/repo fetch relibc
• ./target/release/repo cook relibc
• targeted relibc-tests-bins executions for:
  • sys_eventfd/eventfd
  • sys_signalfd/signalfd
  • sys_timerfd/timerfd
  • waitid
  • semaphore/named
  • semaphore/unnamed
  • stdio/open_memstream
  • ifaddrs/getifaddrs

These are bounded relibc-target proofs, not broad desktop-session runtime proof. They do, however, move the active concrete-wave surface from documented intent to directly revalidated recipe behavior.

Quality assessment

Strong points

1. The patch carriers are explicit and reviewable. The relibc recipe points at named patch files instead of hiding Red Bear behavior in an untracked working tree.

2. Several high-value desktop-facing APIs exist in the active build. eventfd, signalfd, timerfd, waitid, and named semaphore support are all represented in the active patch chain instead of remaining vague TODO items.

3. Focused tests now exist for the active concrete-wave surface and were rerun in this pass. The current patch chain now covers eventfd, signalfd, timerfd, waitid, named and unnamed semaphores, open_memstream, and the bounded ifaddrs view.

4. The build integration point is simple and durable. The active surface is controlled centrally from recipes/core/relibc/recipe.toml and durable carriers under local/patches/relibc/.

Weak points

1. The repo has drifted between plain-source truth and documentation truth. Several canonical docs previously described patch-carried functionality as if it already existed in the plain upstream-owned source tree.

2. The active API surface is broader than its semantic maturity. The patch chain exposes interfaces, but several of them are bounded compatibility layers rather than broad Unix-complete implementations.

3. Patch-chain size is still a maintainability risk. The active recipe still depends on a substantial set of P3 carriers. That is workable, but it is not yet the convergence story older docs implied.

Completeness assessment

Plain-source-visible gaps

Still absent or TODO in the live source tree:

• mqueue.h
• sys/msg.h
• named semaphores in semaphore.h
• ifaddrs plain-source implementation
• plain-source sys/ipc.h, sys/sem.h, and sys/shm.h

Recipe-applied but bounded surfaces

The active build surface includes several features that should be described as bounded, not fully complete:

• timerfd: the patch exposes TFD_TIMER_CANCEL_ON_SET, but timerfd_settime() only accepts TFD_TIMER_ABSTIME
• ifaddrs / net_if: current patch-provided interface enumeration is a fixed loopback + eth0 model, not live system discovery
• open_memstream: now active in the recipe-applied surface, but still validated here only through focused relibc tests rather than broad downstream usage proof
• named semaphores: implemented through shm_open() / mmap() as a practical compatibility path, but not yet a broad semantics-proofed story

Still-missing areas

The clearest remaining gaps are still real gaps, not just "needs more runtime proof":

• POSIX message queues
• SysV message queues
• broader thread / spawn / iconv / wordexp completeness

The broader SysV shm/sem carriers still exist under local/patches/relibc/, but they are not part of the active bounded concrete wave implemented in this pass.

Robustness assessment

Robustness is the weakest part of the current relibc story.

The repo now has a meaningful active patch-applied compatibility surface, but several pieces are still narrow enough that the safest language is:

• useful for bounded downstream compatibility,
• not yet broad semantics-proof,
• and not yet safely describable as a plain-source upstream relibc completion story.

Concretely:

• fd-event APIs depend on scheme paths such as /scheme/event and /scheme/time
• ifaddrs currently reports a synthetic interface view rather than live network state
• named semaphores remain a bounded shm-backed path rather than a broader semantics-proofed story

Recommended support language

Use this language in project docs unless stronger evidence is gathered:

• Good: "The active relibc recipe patch chain provides bounded eventfd / signalfd / timerfd compatibility for current Red Bear consumers."
• Good: "Named semaphores and ifaddrs currently exist through recipe-applied Red Bear compatibility patches, not as plain-source upstream relibc convergence."
• Avoid: "These surfaces are now source-visible in the current relibc tree."
• Avoid: "relibc is complete for desktop consumers."

Improvement plan

Phase R0 — Keep the evidence model honest

Goals:

• keep plain-source, recipe-applied, and runtime-proof language distinct
• keep canonical relibc docs aligned with recipes/core/relibc/recipe.toml
• stop describing patch-carried functionality as already upstream-visible unless it really is

Exit criteria:

• relibc docs match the active recipe patch list
• repo-level summaries use bounded/evidence-qualified language

Phase R1 — Make the active patch chain the explicit build contract

Goals:

• treat the current relibc recipe patch list as the build contract for Red Bear relibc behavior
• review that list regularly against upstream relibc changes
• retire carriers only when the recipe no longer needs them

Exit criteria:

• every relibc carrier still replayed by the recipe is documented as active
• every historical-but-not-active carrier is clearly marked historical

Phase R2 — Strengthen proof for the patch-applied surface

Goals:

• keep focused tests for waitid, semaphores, and other patch-applied APIs
• expand consumer-facing checks for the APIs Red Bear actually depends on
• avoid treating build success alone as semantics proof

Exit criteria:

• each active compatibility surface names its current proof level and missing proof

Phase R3 — Harden bounded compatibility layers

Highest-value targets:

• fd-event semantics that current desktop consumers rely on
• named semaphore behavior beyond the current narrow shm-backed path
• ifaddrs / net_if behavior beyond the synthetic loopback + eth0 model

Exit criteria:

• docs no longer need to caveat these areas as merely synthetic or narrowly bounded unless that boundedness is intentional and accepted

Phase R4 — Decide the real SysV IPC contract

The current bounded SysV shm/sem layer is better than raw absence, but it is not a broad final design.

Decision needed:

• either keep a clearly documented bounded compatibility contract,
• or implement a broader system-backed contract and test it accordingly.

Exit criteria:

• the repo stops implying broad SysV completeness where only a narrow compatibility slice exists

Phase R5 — Triage the still-missing surfaces

Priority candidates:

• message queues,
• thread/spawn completeness,
• other TODO headers that block real consumers rather than theoretical completeness checklists.

Exit criteria:

• each remaining TODO surface is either implemented, explicitly deferred, or removed from misleading summary language

Phase R6 — Converge with upstream where possible

Goals:

• shrink the relibc patch chain whenever upstream absorbs equivalent behavior
• avoid carrying Red Bear-local relibc deltas longer than necessary

Exit criteria:

• the active recipe patch chain is smaller for evidence-based reasons, not for documentation optics

Bottom line

relibc in the current Red Bear repo is neither a greenfield libc nor a nearly converged upstream story.

It is a partially upstream, materially patch-applied compatibility surface that already covers important desktop-facing APIs, but still has real completeness gaps, bounded semantics, and a larger patch-chain dependency than older docs admitted.