Skip to content

Commit 1c98763

Browse files
authored
2026.11.12.1: system facts as data, one arrangement per provider entry, a base package's single reading, runners as provider statements (#924)
mcpp 2026.11.12.1 (design record: .agents/docs/2026-11-12-ecosystem-architecture-optimization-design.md). - A provider entry states one arrangement: `glibc-sysroot` serves aarch64-linux-gnu on linux-x86_64 from the base package xim:aarch64-linux-gnu-sysroot (revision 3); the request aarch64-linux is answered as before on every host. - The link model is rendered, not inferred again; a base package has one reading; a dynamic artifact this machine does not load names the row's loader and carries no RUNPATH of this machine. - System facts are data: [[platform.system]], provider `system-headers`, `tier` and `runner`, platform `runner.built-as`, row `loader` and `execution`; the engine's sources name fewer systems (ratchet in CI). - A provider's runner is the lowest tier of the runner statement; its `requires` are installed on the first run. - A program of another system with no runner is built, not run (exit 2), before anything is started. - `[target.<sel>.abi] longjmp`. - MSVC ABI with clang: the C line states the C library model and the C standard as two words. - mcpplibs.mwrap.xz 5.8.3.1: `mcpp pack --compress xz` no longer faults on Windows. - The openkal targets' platform is openkal-platform 0.27.1. - Tests: a script that does not apply exits 77 and is a skip (mtest 0.6.2); the coverage check has `owed`. Six scripts that ran on no runner run again (13, 28, 31, 650, 653, 657). Pull request: #924 (its body holds the self-review).
1 parent 346b3f7 commit 1c98763

203 files changed

Lines changed: 3677 additions & 672 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/docs/2026-11-12-ecosystem-architecture-optimization-design.md‎

Lines changed: 912 additions & 0 deletions
Large diffs are not rendered by default.
Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
subject: architecture
3+
status: superseded
4+
superseded_by: 2026-11-12-ecosystem-architecture-optimization-design.md
5+
---
6+
7+
# The three-plane platform architecture: mcpp × openkal × xim
8+
9+
Date: 2026-11-12
10+
Status: superseded by
11+
[the ecosystem architecture optimization design](2026-11-12-ecosystem-architecture-optimization-design.md),
12+
which extends sections 1, 2, 4 and 5 into four planes. Section 3 was written
13+
before the round it describes was checked: its items 2 and 3 did not land in
14+
the form stated there. A base package is read as a sysroot and the artifact
15+
names the row's loader (not a loader "folded sysroot-relative" beside the
16+
payload's own `-B/-L`), and an artifact of another system is not started at all
17+
(not run as a child whose death is classified). The record of what was
18+
implemented, with the check that holds each item, is section 15 of the
19+
superseding design.
20+
21+
## 1. The statement
22+
23+
A platform enters this ecosystem as **data**, never as engine code. Three
24+
data planes carry everything a target needs, and one normalisation layer
25+
decides whether what was built is right:
26+
27+
| Plane | Carries | Where it lives | Invariant |
28+
|---|---|---|---|
29+
| ① row | serves/hosts/toolchain/sysroot/linkage/abi of a target identity | the toolchain model's table, or a platform package's own rows | target differences are data; the engine holds no per-target branch |
30+
| ② payload | the toolchain bytes, and the base package that is the target's C library | the index (xim), installed by the fetcher through the revision channel | a build host needs mcpp itself and nothing else; where a row names a base package the host's link model yields entirely |
31+
| ③ runner | how an artifact of another system starts (a declared prefix, an emulator, a loader) | row/platform data; resolved by the runner lookup | build never depends on a runner; running consumes the declaration |
32+
| verification | one script, one expected output, normalised (CRLF, colour, codeset, console noise) | the shared harness | the harness knows no target; every executor family answers through it |
33+
34+
Two red lines hold throughout, and the gates hold them mechanically:
35+
default behaviour is unchanged by any of it (the regressions stay green), and
36+
no host name enters the engine — host differences are statements rows make.
37+
38+
## 2. The layering the planes serve
39+
40+
```mermaid
41+
flowchart TB
42+
subgraph consumer["a program of any system"]
43+
A["import the C++ modules / C sources"]
44+
end
45+
subgraph libc["one C library, ported once"]
46+
M["libc above the kernel ABI (spec)</br>static where the row says static"]
47+
end
48+
subgraph kal["the kernel-ABI specification"]
49+
K["openkal: the interface, its conformance suite</br>and one implementation per system family"]
50+
end
51+
R1["row ① + payload ②"] --> A
52+
M --> A
53+
K --> M
54+
KF["firmware implementations</br>(UEFI boot services, RISC-V SBI)"] --> K
55+
KP["kernel implementations</br>(the reference kernel's own interface,</br>a BSD kernel's, a Windows kernel's)"] --> K
56+
KX["a POSIX-library implementation</br>(for systems whose own libc is the interface)"] --> K
57+
R3["runner ③"] -. runs the artifact on.-> consumer
58+
```
59+
60+
The specification's own rules make the layering safe: an implementation may
61+
declare an interface absent (the conformance suite decides which absences are
62+
legal), a C library above the interface never sits above an implementation
63+
that would call back into it (layer-cycle refuses that graph at resolution),
64+
and a program states which ABI it speaks by depending on one.
65+
66+
## 3. What the merged round established
67+
68+
Measured, not aspirational (each item landed with its gate green):
69+
70+
1. **Rows as the only place targets differ.** Eighteen identities build from
71+
one engine with zero per-target code; the identity that was missing
72+
arrived as one table row plus one base package.
73+
2. **Base packages.** Where a row names one, the payload is the target's C
74+
library: the driver gets `--sysroot`, the payload's own `-B/-L`, a
75+
loader folded sysroot-relative, and the compiler's runtime directory —
76+
and the host's link words, runtime directories and closure rules yield
77+
entirely. A cross needs nothing from the machine it stands on.
78+
3. **Foreign-kernel execution.** An artifact of another system, of this
79+
machine's architecture, runs as a child: its death by signal is named,
80+
its status returned unchanged, and the runner declaration follows it.
81+
4. **ABI members as data.** `abi longjmp` states how a jump crosses the
82+
WebAssembly boundary; the probe renders the flag on both sides, and a
83+
row that is not the member's subject is refused rather than ignored.
84+
5. **Corrective revisions.** A resource whose bytes must change without a
85+
version change is re-published under the same key with a raised
86+
revision; the updater channel enforces that a raise is total — every
87+
platform, one sha per url, shapes compared.
88+
6. **One file, several systems.** A pack can hold the programs of several
89+
systems: a PE leads with a POSIX script in its DOS header, and every
90+
POSIX system's program rides behind it.
91+
7. **Layer vocabulary.** `kernel-abi` is a layer the rows, the payloads and
92+
the requirement side all speak (`layers.kernel-abi`, `requires`), an
93+
implementation written above a C library never sits beneath one it would
94+
call back into — the resolution refuses that graph before anything is
95+
compiled — and a payload's kernel-abi is the target's system, so a
96+
requirement stated on it holds across every route to the row.
97+
98+
## 4. What the next systems consume
99+
100+
The same planes, with no engine work:
101+
102+
| Scenario | What it uses | What is left to build |
103+
|---|---|---|
104+
| A POSIX-family kernel with its own libc | the POSIX-library implementation of the ABI (already above every such libc), rows, a cross toolchain payload | the toolchain payload; a disk-image asset; an emulator runner |
105+
| Firmware (UEFI, SBI) | the existing firmware implementations; an ordinary PE row and three link flags state a UEFI application — measured, no new target kind; a runner's exit status is the program's (the contract already carries firmware: the harness states the status) | an OVMF/emulator runner entry |
106+
| A system's official media, booted | the disk-image asset class (`<system>-disk-image`): official media assembled into a bootable image, serial console, a marker protocol that separates the program's output from the machine's noise, exit codes carried through | the generic emulator harness (overlay isolation, expect/send primitives, the marker protocol); the naming and attribution conventions |
107+
| Freestanding and bare-metal targets | the freestanding rows; a C-only, no-module path | the conformance hook-ups |
108+
| Any corrective republish | the revision channel | nothing |
109+
110+
The one boundary this architecture states out loud: the **semantic plane** —
111+
a process model, a terminal — is the program's own. The infrastructure
112+
answers that a target can be built, started and judged; it does not port the
113+
program.
114+
115+
## 5. Naming (index side)
116+
117+
- Generic assets and toolchains carry no prefix; a tool whose contract is a
118+
build-system session carries that system's prefix.
119+
- A bootable-image asset is named `<system>-disk-image` — the thing, not a
120+
mechanism, not a format; the asset's file names carry the format.
121+
- Official media is attributed to its publisher in the recipe; repacked
122+
bytes are provenance-recorded, double-mirrored, sha-identical.
123+
124+
These are conventions of the index, not engine vocabulary; the engine knows
125+
none of the names.

‎.agents/docs/README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,16 @@ superseded_by: 2026-09-07-....md # when status is superseded
1818
---
1919
```
2020

21-
358 records.
21+
360 records.
2222

2323
## By subject
2424

2525
Records that declare one. Everything else is listed by date below.
2626

27+
### architecture
28+
29+
- [The three-plane platform architecture: mcpp × openkal × xim](2026-11-12-three-plane-platform-architecture-design.md) — superseded by [2026-11-12-ecosystem-architecture-optimization-design.md](2026-11-12-ecosystem-architecture-optimization-design.md)
30+
2731
### build
2832

2933
- [大型工作区的构建空间与复用(mcpp#874)](2026-10-31-workspace-space-and-reuse-design.md) — active
@@ -79,6 +83,7 @@ Records that declare one. Everything else is listed by date below.
7983

8084
### ecosystem
8185

86+
- [生态架构优化方案:四个平面的收敛、已合入项的纠正与新系统的准入(mcpp × openkal × xlings)](2026-11-12-ecosystem-architecture-optimization-design.md) — active
8287
- [测试与依赖解析补充方案:mcpp、mcpp test、mtest、mcpp-ide](2026-11-10-test-and-resolution-supplement-design.md) — active
8388
- [生态顶层方案:#885 收尾之后的工作流、原则与依赖](2026-11-08-ecosystem-top-level-design.md) — active
8489
- [#885 收尾补充方案:目标角色、平台事实、系统接口与版本书写](2026-11-08-ecosystem-885-supplement-design.md) — active
@@ -188,6 +193,8 @@ Records that declare one. Everything else is listed by date below.
188193

189194
### 2026-11
190195

196+
- [The three-plane platform architecture: mcpp × openkal × xim](2026-11-12-three-plane-platform-architecture-design.md) — superseded by [2026-11-12-ecosystem-architecture-optimization-design.md](2026-11-12-ecosystem-architecture-optimization-design.md)
197+
- [生态架构优化方案:四个平面的收敛、已合入项的纠正与新系统的准入(mcpp × openkal × xlings)](2026-11-12-ecosystem-architecture-optimization-design.md) — active
191198
- [测试与依赖解析补充方案:mcpp、mcpp test、mtest、mcpp-ide](2026-11-10-test-and-resolution-supplement-design.md) — active
192199
- [生态方案:跨平台通用基础设施(mcpp + openkal + xim),以一个 C89 工程为验证](2026-11-10-cross-platform-ecosystem-design.md) — active
193200
- [目标与提供者:统一的目标模型(结合 mcpp#911)](2026-11-09-target-model-design.md) — active

‎.github/tools/check_e2e_coverage.py‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,16 @@
2929
and neither does a longer name that contains it;
3030
excused tests/e2e/coverage-exceptions.tsv lists it with the reason no hosted
3131
runner can run it;
32+
owed tests/e2e/coverage-debt.tsv lists it: it skips itself on every
33+
host that starts it (a script leaves with 77 after a `SKIP:` line
34+
when it can hold nothing on a machine, and the run reports it as a
35+
skip). The list is a debt, and it only shrinks: each entry names
36+
what a host lacks, and is removed when a host gains it;
3237
uncovered none of these. The check fails.
3338
34-
An exception for a test that ran, or for a test that does not exist, also fails
35-
the check, so that the list cannot outlive the reason it records.
39+
An exception or a debt entry for a test that ran, or for a test that does not
40+
exist, also fails the check, so that neither list can outlive the reason it
41+
records.
3642
3743
Some claims need a test to pass on particular hosts, not on some host: docs/21
3844
calls a target row `verified` when CI builds and runs its artefact, and the
@@ -133,6 +139,7 @@ def main() -> int:
133139
workflows = workflow_tokens([p.read_text(encoding="utf-8")
134140
for p in sorted((root / ".github" / "workflows").glob("*.yml"))])
135141
exceptions = read_exceptions(root / "tests" / "e2e" / "coverage-exceptions.tsv")
142+
debt = read_exceptions(root / "tests" / "e2e" / "coverage-debt.tsv")
136143
required = read_host_requirements(root / "tests" / "e2e" / "host-requirements.tsv")
137144

138145
ran: dict[str, set[str]] = defaultdict(set)
@@ -165,17 +172,25 @@ def main() -> int:
165172
counts["ran"] += 1
166173
if test in exceptions:
167174
stale.append(f"{test} is excused but ran on {', '.join(sorted(ran[test]))}")
175+
if test in debt:
176+
stale.append(f"{test} is listed as owed but ran on {', '.join(sorted(ran[test]))}: "
177+
f"remove it from coverage-debt.tsv")
168178
elif test in unaffected:
169179
counts["unaffected"] += 1
170180
elif named_by_a_workflow(test, workflows):
171181
counts["job"] += 1
172182
elif test in exceptions:
173183
counts["excused"] += 1
184+
elif test in debt:
185+
counts["owed"] += 1
174186
else:
175187
uncovered.append(f"{test}: {'; '.join(sorted(skipped[test])) or 'in no report'}")
176188
for test in exceptions:
177189
if test not in tests:
178190
stale.append(f"{test} is excused but does not exist")
191+
for test in debt:
192+
if test not in tests:
193+
stale.append(f"{test} is listed as owed but does not exist")
179194
unmet = []
180195
for test, hosts in sorted(required.items()):
181196
if test not in tests:
@@ -188,7 +203,7 @@ def main() -> int:
188203

189204
print(f"{len(tests)} tests: {counts['ran']} ran on a shard, {counts['unaffected']} unaffected by "
190205
f"the change, {counts['job']} run by a dedicated job, {counts['excused']} excused, "
191-
f"{len(uncovered)} uncovered")
206+
f"{counts['owed']} owed, {len(uncovered)} uncovered")
192207
for (host, shard), ms in sorted(shard_ms.items()):
193208
print(f" {host} shard {shard}: {ms / 60000:.1f} min of tests")
194209
for line in uncovered:
Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
#!/usr/bin/env python3
2+
"""check_system_names.py -- the engine's sources name no more systems than the baseline.
3+
4+
WHY THIS EXISTS
5+
6+
AGENTS.md section 2 states that the engine names no operating system: target
7+
rows, providers and systems are data (modules/toolchain-model/data/builtin.toml,
8+
SPEC-016), and code that is specific to one host lives in modules/platform/.
9+
A review cannot hold that sentence: a branch on `"freebsd"` reads as an
10+
ordinary line, and several entered the tree beside the tables that were meant
11+
to replace them (design 2026-11-12, cause R1). This check counts instead.
12+
13+
WHAT IS COUNTED
14+
15+
Each word of the vocabulary below, in the engine's sources -- `src/` and
16+
`modules/*/src/`, without `modules/platform/` and without tests and data --
17+
in the two forms a branch on a system takes: the word as a string literal
18+
(`"freebsd"`), and the host predicates of mcpplibs.os (`is_linux`,
19+
`is_windows`, `is_macos`). Comments are not counted.
20+
21+
THE RATCHET
22+
23+
`system-names.baseline` records one number per word. More occurrences than the
24+
baseline fail: the new line states a system fact, which belongs in a row, in
25+
the system table or in a provider. Fewer occurrences fail as well, with the
26+
line to write: the baseline follows the code down, so the count never returns.
27+
28+
check_system_names.py compare with the baseline
29+
check_system_names.py --update rewrite the baseline to the counts found
30+
check_system_names.py --list W print every counted line of word W
31+
"""
32+
33+
import pathlib
34+
import re
35+
import sys
36+
37+
ROOT = pathlib.Path(__file__).resolve().parents[2]
38+
BASELINE = pathlib.Path(__file__).with_name("system-names.baseline")
39+
40+
LITERALS = ["linux", "macos", "windows", "freebsd", "android", "emscripten", "ios",
41+
"darwin", "netbsd", "openbsd", "haiku", "dos", "uefi"]
42+
PREDICATES = ["is_linux", "is_windows", "is_macos"]
43+
44+
SOURCE_SUFFIXES = {".cppm", ".cpp", ".mcpp"}
45+
46+
47+
def sources():
48+
for base in (ROOT / "src", ROOT / "modules"):
49+
for path in sorted(base.rglob("*")):
50+
if path.suffix not in SOURCE_SUFFIXES or not path.is_file():
51+
continue
52+
rel = path.relative_to(ROOT).as_posix()
53+
if rel.startswith("modules/platform/"):
54+
continue
55+
parts = rel.split("/")
56+
if "tests" in parts or "target" in parts or "data" in parts:
57+
continue
58+
yield rel, path
59+
60+
61+
def code_of(line, state):
62+
"""The line without its comments. `state["block"]` carries a /* */ across lines."""
63+
out = []
64+
i = 0
65+
in_string = False
66+
while i < len(line):
67+
if state["block"]:
68+
end = line.find("*/", i)
69+
if end < 0:
70+
return "".join(out)
71+
state["block"] = False
72+
i = end + 2
73+
continue
74+
ch = line[i]
75+
if in_string:
76+
out.append(ch)
77+
if ch == "\\" and i + 1 < len(line):
78+
out.append(line[i + 1])
79+
i += 2
80+
continue
81+
if ch == '"':
82+
in_string = False
83+
i += 1
84+
continue
85+
if ch == '"':
86+
in_string = True
87+
out.append(ch)
88+
i += 1
89+
continue
90+
if line.startswith("//", i):
91+
break
92+
if line.startswith("/*", i):
93+
state["block"] = True
94+
i += 2
95+
continue
96+
out.append(ch)
97+
i += 1
98+
return "".join(out)
99+
100+
101+
def count():
102+
patterns = {w: re.compile(r'"%s"' % re.escape(w)) for w in LITERALS}
103+
patterns.update({w: re.compile(r"\b%s\b" % w) for w in PREDICATES})
104+
counts = {w: 0 for w in patterns}
105+
lines = {w: [] for w in patterns}
106+
for rel, path in sources():
107+
state = {"block": False}
108+
for n, raw in enumerate(path.read_text(encoding="utf-8", errors="replace").splitlines(), 1):
109+
code = code_of(raw, state)
110+
if not code.strip():
111+
continue
112+
for word, pat in patterns.items():
113+
hits = len(pat.findall(code))
114+
if hits:
115+
counts[word] += hits
116+
lines[word].append(f"{rel}:{n}: {raw.strip()}")
117+
return counts, lines
118+
119+
120+
def read_baseline():
121+
base = {}
122+
if not BASELINE.is_file():
123+
return base
124+
for line in BASELINE.read_text().splitlines():
125+
line = line.split("#", 1)[0].strip()
126+
if not line:
127+
continue
128+
word, number = line.split()
129+
base[word] = int(number)
130+
return base
131+
132+
133+
def write_baseline(counts):
134+
text = ("# One number per word: its occurrences in the engine's sources\n"
135+
"# (.github/tools/check_system_names.py). The numbers only fall.\n")
136+
for word in LITERALS + PREDICATES:
137+
text += f"{word} {counts[word]}\n"
138+
BASELINE.write_text(text)
139+
140+
141+
def main(argv):
142+
counts, lines = count()
143+
if len(argv) == 2 and argv[0] == "--list":
144+
print("\n".join(lines.get(argv[1], [])))
145+
return 0
146+
if argv == ["--update"]:
147+
write_baseline(counts)
148+
print(f"wrote {BASELINE.relative_to(ROOT)}")
149+
return 0
150+
base = read_baseline()
151+
more, fewer = [], []
152+
for word in LITERALS + PREDICATES:
153+
was, now = base.get(word, 0), counts[word]
154+
if now > was:
155+
more.append(f" {word}: {now} occurrences, the baseline is {was}")
156+
elif now < was:
157+
fewer.append(f" {word}: {now} occurrences, the baseline is {was}")
158+
if more:
159+
print("the engine's sources name a system more often than the baseline:")
160+
print("\n".join(more))
161+
print("A fact of a system is data: a key of its row, of the system table or of a provider\n"
162+
"(modules/toolchain-model/data/builtin.toml, SPEC-016), read where it was branched on.\n"
163+
"Code specific to one host lives in modules/platform/.\n"
164+
"`check_system_names.py --list <word>` prints the counted lines.")
165+
if fewer:
166+
print("the engine's sources name a system less often than the baseline; record it:")
167+
print("\n".join(fewer))
168+
print(" python3 .github/tools/check_system_names.py --update")
169+
return 1 if more or fewer else 0
170+
171+
172+
if __name__ == "__main__":
173+
sys.exit(main(sys.argv[1:]))

0 commit comments

Comments
 (0)