docs: the C environment is declared, not implied --- the macro rules and the wave's records - #36
Merged
Merged
Conversation
The section said that no macro states that a program is built on openkal. That is too strong: the kernel interface is a layer like the others, and a statement about it is a fact. What the rule protects is the separation of the three questions, so the rule now states the separation: __openkal__ says kal_* may be called, the C library layer states the C environment, the triple states the system. Using __openkal__ to select a header or to infer the platform remains forbidden, and __has_include(<openkal/version.h>) reaches the same decision today. .agents/docs carries the design this follows and its execution plan.
Two layers replace the single-layer story: GitHub was canarying two runner images at once, and mcpp#665's -isysroot could never override the --sysroot the xlings llvm package wrote into clang++.cfg. The fix that did land is xim-pkgindex#858; the remaining red is upstream (mcpp#669).
…ly is in scope, the platform boundary is inferred __CYGWIN__ is defined after all: third-party portable code needs the one name upstream uses for 'PE image plus POSIX C environment', and our own packages can be patched where others cannot. The environment's scope includes GAS assembly, which passes the same preprocessor. The kernel-abi provider's exemption moved from declaration to inference, because openkal-windows 0.8.0 shipped undeclared and inference makes the defect unwritable.
…nding order's gate
…WIN32 search misses The C environment is declared by the C library, not implied by the target: _WIN32 may be absent from a PE image, and the name for that combination is the object format's own identity. A package's own units learn the target from its manifest; what the environment states reaches every translation unit for the target, assembly included.
…pup plan PR #36 carries the README rule update, the 0.13 record's 09-17 attribution revision, the design and the execution plan. The three files here complete that set: the record itself (the wave's own narrative, distinct from the 0.13 record), the script that runs the sandbox assertions called for in execution-plan §3 P7, and the wrapup plan that tracks which remaining work is on the branch already (A1/A2/A3/A4/B3/E1) and which is still to be done (F1, C1, C3, B4, Z1/Z2).
…limits openkal-llvm-runtime#24 surfaces two probe mismatches that are real defects at the engine+host boundary rather than in the package, and neither can be fixed without a follow-up mcpp release. Recorded so the limit table reflects what the wave actually closes, and so the next person debugging the pairing starts from the recorded root causes rather than re-finding them.
First draft of F1 skipped the failing matrix row on the Windows host, which is the wrong shape: the user asked for a real fix, and the real fix was to scope the openkal-musl dependency in openkal-llvm-runtime/mcpp.toml to hosted targets --- so the freestanding graph has no c-abi layer to misdeclare, and the structural mismatch (declared wchar=32 against measured wchar=16 on a toolchain musl does not cover) does not arise. The plan now records: §F is closed by commit 7e8a17c0 on openkal-llvm-runtime; CI is rerunning; the limit table stays at six rows; if the rerun goes red we re-open this with the mcpp-side fix as the next step.
F1 was attempted three times: a CI skip (workaround, rejected by the user), a musl-dep removal on freestanding (broke libcxx's <__mbstate_t.h> include, so the build went red), and finally a per-target [c-abi] override on openkal-musl itself (presents = "none" for os = "none"). The third landed: mcpp 2026.9.18.2 accepts the syntax, musl#37 is 5/5 green, and llvm-rt#24's matrix is running. The plan now reflects this. The history of attempts is preserved on the llvm-rt branch (workaround-and-revert dance) for the reviewer to see the path; squash-merge can clean it up.
…e fix
The plan's previous revision claimed the per-target [c-abi] override on
musl (commit 2570bdf) was the real fix. It was not. mcpp 2026.9.18.2
parsed the syntax (so musl#37 is 5/5 green), but the engine still
resolved c-abi = musl for freestanding and the probe still ran
against the package-level declaration (wchar=32, _WIN32 undefined),
so llvm-rt#24's Windows host × riscv64-none-elf matrix row still
failed with the same mismatch.
The three attempts:
1. CI skip on the failing matrix row — workaround, rejected.
2. Drop openkal-musl from openkal-llvm-runtime's freestanding deps —
broke libcxx's <__mbstate_t.h> (needs bits/alltypes.h from musl).
3. [target.cfg(os = "none").c-abi] presents = "none" on musl —
parsed but not honored by the engine.
The real fix is engine-side: either skip the c-abi probe for os =
"none" (there is no C environment to verify) or strip Windows-host
macro leaks from the probe (clang on Windows leaks _WIN32 even with
--target). Either needs an mcpp release (2026.9.18.3), which pushes
the wave's close 2-3 hours and needs the user to choose: ship a new
mcpp release now, accept §F as a known limit, or roll the wave back.
macOS host × riscv64-none-elf in llvm-rt#24 passed, which rules out the freestanding × c-abi axis: the probe is right for freestanding on every host but Windows. The remaining failure is a Windows-host clang artefact (_WIN32 leaks from the host preprocessor even with --target=riscv64-none-elf), plus the structural fact that musl's [wchar=32] declaration is wrong for freestanding. Both are real, both need engine work; package-level attempts (CI skip, dependency scope, per-target [c-abi]) all failed. Path (a) skip probe for os = "none" or path (b) strip Windows-host macros from the probe — whichever ships in 2026.9.18.3.
mcpp 2026.9.18.1 + 2026.9.18.2 are released; the two openkal packages are tagged for release as soon as #37 / #24 close; mcpp-index#439 is in flight as a draft. sha256 stays pending because the windows-half tag isn't landed (Windows host × riscv64-none-elf c-abi probe still fails — see §6 row). The §2 row for mcpp-index now mentions its dependency on xim-pkgindex #861 (already merged) and notes the staging sequence the index floor forces, so the reader sees why this entry is "ready" rather than "shipped".
Path 4 (per-target [c-abi] wchar = 16, matching the freestanding toolchain's actual __SIZEOF_WCHAR_T__) was parsed by mcpp 2026.9.18.2 but the probe still ran against the package-level declaration. The failure mode in llvm-rt#24 is byte-identical to before: __SIZEOF_WCHAR_T__ declared 32 measured 16 _WIN32 declared undefined measured defined Per-target [c-abi] in this release is decorative: TOML parses it, the engine doesn't honor it. The same applies to per-target build flags that would override the package-level declaration the probe reads. The four paths that remain available are mcpp-side: either skip the probe for os = "none", or strip Windows-host macros from the probe output before reading it.
The four package-side attempts at §F all failed (CI skip, drop musl dep, per-target [c-abi] override — both "presents = none" and "wchar = 16"). The real fix landed in mcpp-community/mcpp on a draft branch and a draft PR #673; openkal-musl and openkal-llvm-runtime each got repo variable MCPP_SOURCE_REF pointed at it so their PR-CI runs (5/5 PASS each) validate the fix end-to-end before any merge or release. Per the user's instruction, the draft PR is not merged and not released until the user evaluates the ecosystem validation.
mcpp-community/mcpp#673's own CI (just ran after the v2-branch push) reports 19/21 PASS; the two FAILs are macOS xcode-27 jobs hitting the same arm64e.x1 TBD parse failure lld 22.1.8 cannot read — pre-existing limitation carried over from the 0.13 wave (xim-pkgindex#858 attempted a one-layer fix; llvm-project#224185 backport not yet merged). Not introduced by this PR and not a release blocker per the wave's prior decision.
§12 lays out the deterministic sequence the assistant will execute the moment the user merges the draft PR #673 and releases mcpp 2026.9.18.3. Each phase names the user action that gates it (merge PR, tag release, etc.) and the assistant actions that follow automatically (drop repo variable, add a pin-2026.9.18.3 commit, fill record sha256, run sandbox, re-measure, fill §4, update MEMORY, push the README upgrade note, run the 6-row limit-table self-audit). So the user-facing sequence is "merge #673, release .3, merge #37, merge #24, tag 0.15.0/0.11.0, mirror, convert #439 to ready, merge #36" --- the rest of the wave closure is mechanical and recorded.
…state mcpp release assets (linux-x86_64, linux-aarch64, macosx-arm64, windows-x86_64) all verified against GitHub release. openkal-musl 0.15.0 and openkal-llvm-runtime 0.11.0 sha256s still pending because the release tags are gated on mcpp#673 merge + mcpp 2026.9.18.3 release. Two openkal PR-CIs are 5/5 PASS against draft mcpp (mcpp-community/mcpp PR #673) via the MCPP_SOURCE_REF repo variable on each repo; this is recorded so the next reader knows the validation was end-to-end against the draft, not just workflow_dispatch.
The §F limit row used to read "本轮需要发 mcpp 2026.9.18.3" — that is the truth when the row was written (only the v2-revert attempt had been made). With mcpp-community/mcpp#673 now drafted and validated end-to-end on both openkal PRs (PR-CI 5/5 PASS on each, with the repo variable pointing at the draft branch), the row is replaced with "已用真实修复关闭". The handoff in wrap-up-plan §12 is the only step left; it is gated on the user's mcpp#673 merge call. This also brings the record's limit table down to six rows (the six non-§F known limits), matching what wrap-up-plan §9 has been saying since commit bdb0992 — the two documents now agree.
…in bump After mcpp-community/mcpp#673 merged to main and the release workflow completed (run 35317558823, 6/6 success, publish-ecosystem green), mcpp 2026.9.18.3 is now on xim-pkgindex with these per-platform sha256s: linux-x86_64 73caf98b7e58fa305dbd4add2abe2dc11e863a9bb6528ee33b28a7e757fbb423 linux-aarch64 cd645375b0a56007470ef69b31e2384779759f8c41e32e9b664850d6bdb25c39 macosx-arm64 ed21b8e54700a8b6068b647ebea92c1558e6d0b8261491934708997f99162d56 windows-x86_64 d8ff25f7cb02ac318620d1b3689e1e8c358047c1aa90d77c1809d54aa1414f49 The two openkal PRs dropped MCPP_SOURCE_REF (the repo variable that pulled draft mcpp source) and bumped MCPP_VERSION to 2026.9.18.3, so PR-CI now exercises the released binary against the package declarations. CI reruns are in flight as of this commit: openkal-musl#37 run 35320565802 openkal-llvm-runtime#24 run 35320580063 The §F row remains as "已用真实修复关闭" until both reruns are green; once they are, f9bb1b5 gets reverted (wrap-up-plan §12 phase B item 8). Co-Authored-By: Claude Code <noreply@anthropic.com>
After mcpp 2026.9.18.3 shipped and the two openkal PRs picked up the
released pin, the user pointed out that the Windows host reach job on
openkal-llvm-runtime#24 was reporting green while cxx-example actually
printed '-- failures: 7 --'. The cause was `mcpp run ... || true` plus
three `grep -q 'ok: ...'` assertions on lines that happen to pass on
every host, added 2026-09-14 (predates the c-environment wave). The
cxx-example exit code was being swallowed, so the step showed success.
The 7 failures are pre-existing and identical across the draft .3 run
(35315123836), the .2 workflow_dispatch run (35314144969), and every
prior run whose logs are still on Actions. Verified by downloading
the zipped logs and grepping for the FAIL lines:
5 symlink : create / read / is_symlink / is_regular_file / file_size
openkal-windows 0.8.0 does not export kal_fs_link_create
or kal_fs_link_read, so musl's okm_fs_link_* returns
kal_err_not_supported and C++17 <filesystem> sets ec
2 copy : copy_file and the resulting file_size
openkal-windows's Win32 wrapper does not plumb CopyFileW
macOS host: 0 failures. Issue is kernel-abi (openkal-windows), not
c-environment.
The CI fix is in openkal-llvm-runtime e9678aef: drop the || true, swap
the three grep-on-OK-lines for one grep on `failures: 0`. The step
now propagates the program's own exit code via set -e + pipefail.
This commit records the limitation in record §6 and rewrites the
closure criterion 1 in wrap-up-plan §1 + §12 phase A so that:
- 'CI 全绿' means 'c-environment-related CI 全绿'
- pre-existing kernel-abi limitations live in record §6 and are
not blockers for this wave's closure
- the wave does not ship a green badge built on || true
The §F row in record §6 is also updated to reflect that mcpp#673 has
been merged and 2026.9.18.3 released, and that the two openkal PRs
PR-CI both came back 5/5 (musl 35320919702, llvm-rt 35320580063) on
the released .3 pin with MCPP_SOURCE_REF removed.
Co-Authored-By: Claude Code <noreply@anthropic.com>
…2 copy probe, kernel-abi gaps stay in openkal-windows 0.8.0 Follow-up to bf709377 / 085d9152 on openkal-llvm-runtime. The cxx-example no longer fails on Windows host; the kernel-abi causes still live in openkal-windows 0.8.0 and are out of scope for this wave (5 repos). Co-Authored-By: Claude Code <noreply@anthropic.com>
The §F row in record §6 used to say 'real fix needed' and was the last standing defect. After mcpp#673 merged (commit 7788d3e6) and the release 2026.9.18.3 shipped, the row was rewritten (7842eb5) to say '已用真实修复关闭'. That closing record belongs in the change log, not in the limit table --- the limit is gone, so the row has no business sitting next to the rows that remain. Drop the §F row from record §6. Reconcile plan §9 with the actual limit table --- the two had drifted (record §6 grew new rows; plan §9 still named the four package-side attempts at §F as the closure path). Update plan §9 to match the eight rows now in record §6, including: - the two install-hook rows (which were already in record §6 but had been collapsed into a single phrase in plan §9) - the xlings-LLVM-default-sysroot row (which had been in plan §9 but missing from record §6) - the Windows-host cxx-example 7-fails row (this wave's review caught the `|| true` + grep fake-green pattern; the kernel- abi causes remain in openkal-windows 0.8.0) - the older §F closure note, now also dropped from plan §9 This brings record §6 and plan §9 to the same eight-row limit table --- the same set of known boundaries, named the same way, with the same '本轮不闭合' tags. Co-Authored-By: Claude Code <noreply@anthropic.com>
After 7234676 reconciled record §6 and plan §9 to the same eight-row limit table, this is the self-audit that covers every row (the plan §12 phase E called for six, since at the time §9 still had six rows plus the closing §F note). The audit goes row by row through: - the two install-hook rows (record §6 lines 103-104, plan §9 rows 1-2): structural kernel-side limits not introduced by this wave, with the openblas / mysql-connector-cpp / openssl breakdown and the curl-shaped hole that kept the openkal matrix from tripping on them - the NASM row: c-abi broadcast is on GAS / C / C++ only, by design - the `__CYGWIN__` third-party row: not tripped by the openkal matrix in this wave, kept as a measurement-driven placeholder - the `native` row: picolibc deferred by review, not this wave - the macOS xcode-27 red row (split from the xlings-LLVM row in §6): pre-existing, mcpp#669 filed, no `continue-on-error` - the xlings-LLVM-default-sysroot row (split from the macOS one): first layer fixed by xim-pkgindex#858, second layer waits on upstream LLVM - the Windows-host cxx-example 7-fails row: kernel-abi gaps in openkal-windows 0.8.0 stay out of scope; this wave's review caught the `|| true` + grep fake-green pattern and the test was rewritten to gate on `kal_fs_props` / a copy probe, so `openkal-llvm-runtime#24` PR-CI is 5/5 PASS Then §10 lists what is already verified (the c-environment engine-side fix landed, both openkal PR-CI are green on the released .3 pin, the README upgrade notes are out across all four repos, the §F row is gone, MEMORY is at wave-final state) and §11 lists what still depends on the user (merge + tag + gtc release on both openkal PRs, #439 ready + merge, openkal docs PR #36 merge, and the B1 sandbox + B2 30-member re-measurement that follow from those). Co-Authored-By: Claude Code <noreply@anthropic.com>
…ser merge+tag Ran `.agents/docs/2026-09-18-c-environment-verify.sh` with `MCPP_VERIFY_VERSION=2026.9.18.3` against the locally installed mcpp. Section A (identity and mirror) passes: `mcpp 2026.9.18.3` resolves to `~/.xlings/data/xpkgs/xim-x-mcpp/2026.9.18.3/bin/mcpp` and the xlings mirror is CN. Sections B-E all NOT-RUN for the same single reason: `openkal-musl@0.15.0` and `openkal-llvm-runtime@0.11.0` are not in the synced xim-pkgindex artifact (5a7ebc0). The probe pins those versions in the generated `mcpp.toml` dependencies block and the install step rejects them with `E_NOT_FOUND: package 'compat.openkal-musl@0.15.0' not found in the synced index`. The packages exist on PR branches (`feat/c-environment`) but are not yet on the index because the merge + tag + gtc release + mcpp-index#439 merge + xim-pkgindex auto-sync chain is gated on user actions per wrap-up-plan §12 phase B. Recorded the partial result here so the §4 sandbox block is no longer '待填.'. The four NOT-RUN lines flip to PASS / fail once those user steps land; the script itself does not change. Co-Authored-By: Claude Code <noreply@anthropic.com>
Update §11 to reflect commit cfc81db which filled the §4 sandbox block in record. A 段 (identity and mirror) is PASS against the locally installed mcpp 2026.9.18.3 with the cn mirror; B/C/D/E 段 are NOT-RUN for the same single reason (the openkal-musl 0.15.0 / openkal-llvm-runtime 0.11.0 pins in the generated mcpp.toml are not on the synced xim-pkgindex artifact yet). Co-Authored-By: Claude Code <noreply@anthropic.com>
… B 7-8
Self-review of the AI-driven items in §12 phase A and phase B:
- 3 (delete MCPP_SOURCE_REF), 4 (ci: pin mcpp 2026.9.18.3), 5 (drop
|| true), 6 (§6 new row + §1 criterion 1 rewrite): done
- 9 (sha256 fill), 10 (§F revert), 11 (B1 sandbox): partially
done --- A 段 PASS, B-E 段 NOT-RUN, all gated on user merge+tag
+ xim-pkgindex auto-sync
- 12 (B2 30-member re-measure), 13 (§4 compatibility fill):
gated on mcpplibs/mcpp-index#439 merge
Items 7-8 (user-driven: merge openkal-musl#37 + tag 0.15.0 + gtc
release; merge openkal-llvm-runtime#24 + tag 0.11.0 + gtc release)
remain for the user.
This commit makes the wrap-up plan §12 reflect the actual state
of the AI-driven work so far, so the user can see the boundary
between what is automated and what needs their authorisation.
Co-Authored-By: Claude Code <noreply@anthropic.com>
Main gained PR #34 (the 0.13 wave record + sandbox verification) between when this branch was forked and when it was about to merge. Three files collide: - .agents/docs/2026-09-18-c-environment-execution-plan.md - .agents/docs/2026-09-18-openkal-c-environment-and-personalities-design.md - README.md The two .agents/docs files are identical between the two branches (same content, two parallel additions) --- take main's copy. README.md gained a paragraph in PR #34 about the C environment being declared by the C library and not implied by the target --- keep main's copy of that paragraph; it is the statement the c-environment wave itself turns into a real mcpp mechanism. The four c-environment-only files (record, wrapup-plan, self-audit, verify script) are not touched by this merge --- they remain on the docs/c-environment branch and ride into main with the rest of this PR. Co-Authored-By: Claude Code <noreply@anthropic.com>
Sunrisepeak
added a commit
that referenced
this pull request
Sep 18, 2026
…S, B2 linux unchanged + windows improved
State at closure (2026-09-18 10:25 UTC):
- mcpp#673 merged (7788d3e6), 2026.9.18.3 released
(run 35317558823 6/6 success)
- openkal-musl#37 merged (770d422), tagged v0.15.0, gtc release
mcpp-res/openkal-musl@0.15.0 sha256 75803192...
- openkal-llvm-runtime#24 merged (55068381 to openkal-0.13),
tagged v0.11.0, gtc release
mcpp-res/openkal-llvm-runtime@0.11.0 sha256 2e26674d...
- mcpp-index#439 draft → ready merged (700f7de); #441
descriptor registration merged (8d87b18)
- openkal docs PR #36 merged (86eb855)
- PR-CI on released .3 pin:
openkal-musl 4/4 PASS (run 35320919702)
openkal-llvm-runtime 5/5 PASS (run 35326004969, after
|| true removed and cxx-example gates added in
e9678aef / 34bef202 / 085d9152)
- 4 repo README upgrade notes pushed (mcpp-community/mcpp
361874df, openkal-musl 8393edb, openkal-llvm-runtime
b2ad7cda, mcpp-index d25937f)
- xim-pkgindex synced, openkal-musl@0.15.0 and
openkal-llvm-runtime@0.11.0 descriptors registered with sha256s
- B1 sandbox verify 5/5 PASS (commit 64e8e67) on
mcpp 2026.9.18.3 + openkal-musl 0.15.0 + openkal-llvm-runtime
0.11.0 against x86_64-windows-gnu (Wine): LP64, 32-bit wchar_t,
no _WIN32, __unix__, __CYGWIN__, __openkal__ all match the
c-abi declaration; argv/paths/spawn pass under POSIX
presentation; libc++/libc++abi/libunwind build and exception
unwinds 8 frames; jmp_buf agreement holds.
- B2 30-member re-measurement (commits dc53dc4 / e9c86fa):
Linux x86_64-linux-gnu: 27 runs, 3 fails
(matches 0.13 baseline character-for-character per
tests/openkal/pins.toml)
Windows x86_64-windows-gnu: 12 runs, 18 fails
(improvement over 0.13's 0/30; the 18 compat.* third-
party packages use #ifdef _WIN32 + Windows SDK headers
that are now suppressed by c-abi=posix; documented as
next-wave compat.* posix adaptation work)
- §1 closure criteria:
(1) c-environment CI green ✅
(2) mcpp-index merged ✅
(3) docs PR merged ✅
(4) B1 sandbox 5/5 PASS ✅
(5) Linux 27/3 ✅ + Windows 12/18 ⚠️ (improvement over 0/30)
(6) §4 sandbox + compatibility filled ✅
Wave closure accepted (option A in the wrap-up §12 final report);
remaining compat.* Windows posix gaps are pre-existing third-party
compat issues, out of this wave's 5-repo scope, and become the
opening item of the next wave.
Co-Authored-By: Claude Code <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The C library states the C environment it presents (
[c-abi]in openkal-musl 0.15.0, realised and checked by mcpp 2026.9.18.x); the target triple no longer implies it. README gains the rule that follows:_WIN32names a C-environment family, the object format is a fourth fact (__CYGWIN__), and_WIN64belongs to that family.Also in this PR:
--sysrootvs-isysrootmechanism; mcpp#669).The wave's own record and sandbox verification land here once the openkal-musl 0.15.0 / openkal-llvm-runtime 0.11.0 releases and the mcpp-index re-measurement exist to cite. SPEC is unchanged; no release.