Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

EigenOS link break: the freestanding allowlist is a ONE-SIDED contract — pthread_once/pthread_self are declared HAL roots that EigenOS never implemented

Closed
  • Is something wrong?
#1,181 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
c
Domain
build-system, operating-systems

Research direction

Start with EigenOS/src/hal.c and the pthread roots in tools/freestanding_allowlist.txt, then inspect trace.c:1392/1400 and builtins.c:2299/2315 to understand the existing callers and guards. Add the two missing HAL roots, implement the reverse allowlist-versus-nm check, and correct the allowlist comment. Done means the freestanding link succeeds, the safety behavior remains enabled, and the check fails when a declared HAL root is absent.

Written by the indexing model from the issue text.

Description

area:embed blocks-release found-by:cold-read kind:gate-defect

EigenOS fails to link the runtime: undefined pthread_once and pthread_self.

The obvious reading is "builtins.c and trace.c call pthread unconditionally, so add EIGENSCRIPT_FREESTANDING guards". Measured, that is the wrong fix — and it would trade away a loud-failure guard.

What is actually true

tools/freestanding_allowlist.txt deliberately lists both symbols as HAL roots that EigenOS is expected to provide:

# --- scheduler roots (pthread over spawn/yield/park) ---
pthread_create
pthread_join
pthread_once          <-- line 44
...
# Thread IDENTITY, not scheduling: #1142's replay tape records which OS
# thread opened it (g_replay_owner_tid) so a take from any other thread
# fails loud instead of silently mixing taped and live values. EigenOS's
# cooperative scheduler already owns the pthread roots above; the identity
# pair is the same HAL story — a task handle the kernel can compare.
pthread_self          <-- line 66

So make freestanding-check is green correctly. The runtime is using only declared roots. The gate is not blind.

The break is that EigenOS does not provide two of them. EigenOS/src/hal.c implements 14:

pthread_create pthread_join pthread_mutex_init/lock/unlock/destroy pthread_cond_init/wait/timedwait/signal/broadcast/destroy pthread_condattr_init/destroy/setclock

and is missing exactly pthread_once and pthread_self — which is exactly the pair that fails to link.

(Instrument calibrated before reading absence as fact: the same grep finds eigs_embed in 3 files and malloc in 9, and finds pthread_create/pthread_mutex_lock in 1 file each.)

Why guarding them out is the wrong direction

  • trace.c:1392/1400 is #1142's replay-owner check: a tape take from a thread other than the one that opened it fails loud instead of silently mixing taped and live values. Compiling that out on EigenOS removes the loud failure and leaves the silent-wrong behaviour it was built to prevent — the exact trade the fail-soft→loud reform (#971) forbids.
  • builtins.c:2299/2315 is one-time PRNG seeding. Note the inner function already carries #if EIGENSCRIPT_FREESTANDING for getpid(), so freestanding was considered there and the pthread_once wrapper around it was missed — the half-converted shape (outer guard left behind while the inner one was done).

Both are a few lines on a cooperative scheduler: pthread_self() returns the current task handle; pthread_once(once, fn) is a flag plus a call. That matches what the allowlist already promises, and keeps the safety guard.

The finding underneath, which is the durable one

The allowlist is a one-sided contract. The gate checks "the runtime uses only allowlisted roots" and nothing checks "EigenOS provides every allowlisted root." So a root can be ADDED to the contract without its counterparty ever being told.

That is what happened: #1142 added pthread_self and wrote, as its rationale, that "EigenOS's cooperative scheduler already owns the pthread roots above." Measured today, it owns 14 of 16 — and not those two. The sentence was reasoned, not checked.

The missing direction is cheap and mechanical: compare the allowlist against nm of EigenOS's HAL objects and fail on any allowlisted root the HAL does not define. That check would have gone red the moment #1142 landed, in the repo that made the promise, instead of surfacing as a link error in the consumer weeks later. It is the same both-directions rule the gate already applies to its own undefined-symbol set — just extended across the repo boundary.

Suggested shape

  1. Add pthread_once and pthread_self to EigenOS/src/hal.c (restores the link, keeps #1142's guard).
  2. Add the reverse check so the contract cannot gain an unimplemented clause again.
  3. Fix the allowlist comment, which currently asserts something false about the counterparty.
Dominant language
C
Stars
3
Forks
7
Avg merge
4h 7m
Merged PRs (30d)
112

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from InauguralSystems/EigenScript

All issues in InauguralSystems/EigenScript

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.