fix: 更新 Galay 至 5.0.2 (#285)

* feat: 收录 Galay 5.0.0 原生模块包

新增 gzj-creator.galay Form-A 描述符，使用 GitHub GLOBAL 归档源并固定 SHA256。\n加入 Unix 工作区示例，验证 galay.utils 与 galay.kernel 默认模块的 Base64、字符串、Buffer 和 Host 接口。\n同步更新中英文 README、descriptor catalog、工作区成员和设计文档；GitCode CN 镜像暂按无权限回退规则跳过。\n本次不打 release tag。

* fix: 更新 Galay 至 5.0.1

* docs: 记录 Galay 5.0.1 CI 结果

* fix: 同步 Galay 5.0.2 Clang 模块修复

* docs: 记录 Galay 5.0.2 全平台验证结果

---------

Co-authored-by: gong <gzj17607270093@163.com>

Author: gzj-creator

.agents/docs/2026-08-29-add-galay-plan.md

@@ -0,0 +1,128 @@
+# Add Galay 5.0.2 (`gzj-creator.galay`)
+
+Date: 2026-08-30
+Upstream: <https://github.com/gzj-creator/galay>
+Tag: `v5.0.2` (`d58976711790e47d5b0ad272e068d516192a1a1e`)
+Status: upstream has published the Clang 22 module fix as v5.0.2. The index
+follows that immutable archive; local GCC/LLVM module and consumer checks,
+archive reproducibility, and the mcpp 2026.8.27.2 package tests pass. The
+post-sync PR validation is green in validate run 33291129061 and site-check
+run 33291129055.
+
+## 1. Shape and identity
+
+Galay is source type (b), a library already developed for mcpp. Its v5.0.2
+release carries a complete `mcpp.toml`, so the index entry is Form A and does
+not duplicate its build recipe.
+
+- Package identity: `namespace = "gzj-creator"`, `name = "galay"`. The
+  namespace names the upstream owner; the package name remains one atomic
+  segment.
+- The upstream manifest builds the default `galay.utils` and `galay.kernel`
+  named modules plus their C++ implementations. SSL, HTTP, WebSocket, HTTP/2,
+  database, RPC, MCP, and tracing sources remain opt-in features in that
+  manifest, with the corresponding feature dependencies preserved.
+- The release manifest declares `platforms = ["linux", "macos"]`. The index
+  therefore publishes `linux` and `macosx` entries only; Windows is omitted
+  until the upstream manifest gains a Windows-compatible build.
+- License and description are taken from the upstream manifest: Apache-2.0,
+  C++23 coroutine networking and protocol framework.
+
+## 2. Source and hash
+
+Both platform entries use the immutable GitHub tag archive:
+
+    https://github.com/gzj-creator/galay/archive/refs/tags/v5.0.2.tar.gz
+
+The archive is 5,231,630 bytes. `sha256sum` was run twice on the complete
+archive and returned:
+
+    93a93fabcfeb1b0ae160f3082ed472571532ce208c112bf2697f94267b27332a
+
+`tar -tzf` succeeds and confirms the root `mcpp.toml`, the tracked include
+layout, and the fifteen named C++23 module interfaces are present.
+
+The v5.0.1 upstream patch remains intact: the generated module preludes only
+include `intrin.h` for `_MSC_VER` and `emmintrin.h` on x86. This addresses the
+earlier v5.0.0 Linux LLVM/macOS intrinsic-header failure without changing the
+new release's guards.
+
+The v5.0.2 fix addresses the separate Linux LLVM failure found in CI run
+33269750913, job 99146034674, with mcpp 2026.8.27.2 and LLVM 22.1.8. In
+v5.0.1, `async_aio.h` closed `namespace galay::async` and then defined the
+`AioCommitAwaitable::await_suspend` function template with a globally
+qualified-id. Because `galay_kernel.cppm` includes that header inside
+`export extern "C++"`, Clang 22 rejected the definition as not being at
+namespace scope and produced cascading `this`, `handle`, `m_waker`,
+`m_controller`, and `m_result` errors. v5.0.2 puts the definition back inside
+the `namespace galay::async` block. The declaration, template visibility,
+ABI, and Linux `USE_EPOLL` implementation remain unchanged.
+
+## 3. CN mirror
+
+`gtc` is not installed in this environment and no GitCode write credential is
+available. Following `docs/cn-mirror.md`, the descriptor uses the plain GLOBAL
+URL rather than inventing a mirror table. CN consumers fall back to GitHub;
+the `mcpp-res/galay` mirror can be added later without changing the package
+identity or version.
+
+## 4. Workspace member
+
+`tests/examples/galay` is a Unix-gated public-package consumer. Its member
+manifest has exactly one project index redirect:
+
+    [indices]
+    gzj-creator = { path = "../../.." }
+
+The test imports `galay.utils` and `galay.kernel`, checks Base64 and string
+helpers, links the out-of-line `kernel::Buffer` implementation, and validates
+IPv4 `kernel::Host` construction. Windows compiles a no-op `main()` because
+the upstream package has no Windows platform entry.
+
+The first RED run failed as expected before the descriptor existed:
+
+    error: dependency 'gzj-creator.galay': no package found for exact selector
+
+After adding the descriptor, the first executable run caught an incorrect
+assumption about `Buffer::clear()` retaining its length; the assertion was
+changed to require the documented empty state. The corrected test then passed.
+
+## 5. Validation
+
+- `mcpp xpkg parse pkgs/g/gzj-creator.galay.lua` passed with the Form-A result
+  and Linux/macOS version lists.
+- `mcpp test -p galay` with the v5.0.2 descriptor passed on the local default
+  GCC toolchain: `test result ok. 1 passed; 0 failed`.
+- The CI-pinned mcpp 2026.8.27.2 Linux default and LLVM 22.1.8 tests pass:
+  `test result ok. 1 passed; 0 failed` for each toolchain.
+- CI run 33269372157 passed on Linux default, macOS default, Windows default,
+  lint, mirror reachability, graphics side-effect, and build checks.
+- The upstream Clang 22 regression test (`kernel.alignsrc`) and the complete
+  CMake/Ninja Linux module surface pass with both GCC and LLVM 22.1.8,
+  including `USE_EPOLL` and `galay.kernel`.
+- A module consumer importing both `galay.utils` and `galay.kernel` compiles,
+  instantiates `co_await AsyncAio::commit()`, and runs successfully under LLVM
+  22.1.8; this confirms the template definition remains visible and member
+  accesses bind to the awaitable instance.
+- The previous CI failure was reproduced from run 33269750913/job 99146034674
+  before the upstream patch and is resolved by v5.0.2; the v5.0.1 intrinsic
+  guards remain covered by the prelude regression test.
+- PR #285 post-sync validate run 33291129061 passed Linux default GCC, Linux
+  LLVM 22.1.8, macOS default, Windows default, lint, mirror-cn-reachable,
+  graphics side-effect, member selection, and timing jobs. Site-check run
+  33291129055 also passed.
+- The build compiled 26 Galay units, including both default module interfaces,
+  the kernel implementation units, and the transitive libaio package.
+- All six descriptor lint checks passed, and all 134 package descriptors passed
+  `mcpp xpkg parse` with the CI-pinned binary.
+- Optional Galay features are intentionally not enabled by this minimal
+  member. They remain upstream-owned feature/dependency decisions and need
+  dedicated protocol/database environments before being advertised as tested.
+
+## 6. Follow-up
+
+When upstream publishes Windows support or a maintainer creates the
+`mcpp-res/galay` release asset, add the platform/mirror entry with the same
+archive bytes. The v5.0.2 release remains Linux/macOS in its own manifest, so
+the Windows example continues to compile a no-op test until a Windows package
+entry exists.

CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+维护说明：未发版的变更记录在 `## [Unreleased]` 下；准备发版时，按
+`vX.Y.Z` 标题格式将累计条目整理到对应版本节，并按改动性质归入
+`Added`、`Changed`、`Fixed`、`Docs` 或 `Chore`。每条记录只保留用户和维护者
+需要知道的主线变化，不逐行复制提交差异。
+
+## [Unreleased]
+
+### Added
+
+- 收录 `gzj-creator.galay` 5.0.2 原生 Form-A 模块包，覆盖 `galay.utils` 与
+  `galay.kernel` 默认模块，并加入 Unix 示例工程和索引文档。
+
+### Fixed
+
+- 跟进 Galay 5.0.1 对 C++23 module prelude 的跨平台 intrinsic 头文件守卫修复，
+  避免 Clang 在 Linux/macOS 上错误转发 `intrin.h`。
+- 跟进 Galay 5.0.2 将 `AioCommitAwaitable::await_suspend` 的类外模板定义放回
+  `galay::async` 命名空间，修复 Clang 22 导出 `galay.kernel` 时的模块语义错误，
+  同时保留 Linux `USE_EPOLL` AIO 后端行为。
+
+### Docs
+
+- 记录 Galay 5.0.2 归档的双下载 SHA256 校验，以及 PR #285 的全平台 CI 验证结果。

README.md

@@ -39,7 +39,7 @@ A few descriptors worth opening first, one per common shape:
 
 | Shape | Example | What it shows |
 |------|------|------|
-| Native module library (Form A) | [`mcpplibs.tinyhttps`](pkgs/t/tinyhttps.lua) | Upstream carries its own `mcpp.toml`, so the descriptor is metadata plus a download address |
+| Native module library (Form A) | [`mcpplibs.tinyhttps`](pkgs/t/tinyhttps.lua) · [`gzj-creator.galay`](pkgs/g/gzj-creator.galay.lua) | Upstream carries its own `mcpp.toml`; Galay also demonstrates a multi-module package with feature-scoped protocol layers |
 | C-source compat | [`compat.cjson`](pkgs/c/compat.cjson.lua) | One `.c` compiled into a lib; the optional extension sits behind a `features` gate |
 | Header-only | [`compat.gtl`](pkgs/c/compat.gtl.lua) | Nothing to compile — `include_dirs` and an anchor TU |
 | Whole-source build + generated config | [`compat.c-ares`](pkgs/c/compat.c-ares.lua) | The config header configure would have produced is snapshotted into `generated_files` |

README.zh-CN.md

@@ -36,7 +36,7 @@ mcpp self config --mirror CN   # 切换至国内镜像,默认使用 GLOBAL 上
 
 | 形态 | 示例 | 看点 |
 |------|------|------|
-| 原生模块库(Form A) | [`mcpplibs.tinyhttps`](pkgs/t/tinyhttps.lua) | 上游自带 `mcpp.toml`,描述符只有元数据与下载地址 |
+| 原生模块库(Form A) | [`mcpplibs.tinyhttps`](pkgs/t/tinyhttps.lua) · [`gzj-creator.galay`](pkgs/g/gzj-creator.galay.lua) | 上游自带 `mcpp.toml`;Galay 还展示了多模块包与按 feature 开启协议层 |
 | C 源码 compat | [`compat.cjson`](pkgs/c/compat.cjson.lua) | 单个 `.c` 编成库;可选扩展由 `features` 门控 |
 | header-only | [`compat.gtl`](pkgs/c/compat.gtl.lua) | 没有可编译内容 —— `include_dirs` 加一个 anchor TU |
 | 全源码直编 + 生成 config | [`compat.c-ares`](pkgs/c/compat.c-ares.lua) | 把 configure 本该生成的 config 头快照进 `generated_files` |

docs/descriptor-examples.md

@@ -13,6 +13,7 @@ in the [root README](../README.md#reference-examples).
 | Shape | Examples |
 |------|------|
 | Native module library (Form A) | [`mcpplibs.xpkg`](../pkgs/x/xpkg.lua) · [`mcpplibs.tinyhttps`](../pkgs/t/tinyhttps.lua) · [`tensorvia-cpu`](../pkgs/t/tensorvia-cpu.lua) · [`ffmpeg`](../pkgs/f/ffmpeg.lua) (module layer; sources compiled directly through `compat.ffmpeg`) · [`opencv`](../pkgs/o/opencv.opencv.lua) (single repository: the module layer and the full OpenCV 5 source build both live in the package, and only this descriptor stays on the index side) · [`mcpplibs.grpc`](../pkgs/g/grpc.lua) (gRPC 1.83.0 — the one library here that CANNOT be a compat descriptor: upstream publishes no self-contained source artifact, its tag archive carrying abseil/protobuf/re2/boringssl/zlib as empty submodule placeholders, so [grpc-m](https://github.com/mcpplibs/grpc-m)'s release tarball IS that artifact. It vendors only gRPC's own source and takes the five dependencies from this index, so a consumer that also uses protobuf links one copy rather than two) |
+| Native multi-module library with feature-scoped sources | [`gzj-creator.galay`](../pkgs/g/gzj-creator.galay.lua) (Galay 5.0.2 — the upstream Form-A manifest exposes `galay.utils` and `galay.kernel` by default, while SSL, HTTP, database, RPC, MCP, and tracing modules stay behind named features and their corresponding dependencies. The index keeps the upstream manifest intact and tests the default module surface on Unix.) |
 | C-source compat (with `features`) | [`compat.cjson`](../pkgs/c/compat.cjson.lua) · [`compat.zlib`](../pkgs/c/compat.zlib.lua) · [`compat.hiredis`](../pkgs/c/compat.hiredis.lua) (the classic 1.2.0 — a 7-TU C build whose flat tarball headers get `hiredis/`-prefixed wrapper headers via `generated_files`, so consumers write `#include <hiredis/hiredis.h>` exactly like upstream's install layout) · [`compat.sqlite3`](../pkgs/c/compat.sqlite3.lua) (plain C-source, no features: the single `sqlite3.c` amalgamation; 3.45.3, the final maintenance release of the most widely deployed 3.45.x line) · [`compat.libuv`](../pkgs/c/compat.libuv.lua) (libuv 1.48.0 — the per-OS source sets transcribed from upstream's CMakeLists, because a `src/unix/*.c` glob would compile every OS's backend at once; linux/macos get explicit unix subsets, windows globs `src/win/*.c`) | · [`compat.xxhash`](../pkgs/c/compat.xxhash.lua) (one TU, one header, no features at all — the interesting decision is what is NOT compiled: `xxh_x86dispatch.c` selects an AVX2/AVX512 path at RUNTIME and needs per-file `-mavx2` plus `XXH_X86DISPATCH` at every call site, so the package ships the flagless SSE2 baseline instead. Nor is the header-only `XXH_INLINE_ALL` mode chosen: it re-emits the implementation in every TU that hashes anything, which is the right trade only when there is exactly one such TU — something a package cannot know)
 | C-source compat where the library IS a kernel ABI | [`compat.libaio`](../pkgs/c/compat.libaio.lua) (libaio 0.3.113 — twelve syscall-wrapper TUs, and the only `xpm` section is `linux`, because there is no port to declare: `struct iocb` is the kernel's and every TU is `syscall(__NR_io_*, …)`. Consumers gate it with `[target.'cfg(linux)'.dependencies]`, the mirror image of compat.wil. Three things it teaches. **One public header out of a source dir**: upstream installs exactly one, `libaio.h`, but the tarball keeps it in `src/` beside the private headers — one of which is named `syscall.h` and would SHADOW glibc's for every consumer TU — so `include_dirs` names a `generated_files` forwarder and nothing else; the package's own sources reach the real header through it while their quote-form `#include "syscall.h"` still resolves next to the including `.c`, so no `-I` into `src/` is needed at all. **A `c_standard` that is a trap**: `-std=c11` sets `__STRICT_ANSI__`, which hides `syscall()` and `sigset_t`, and the public header then fails to parse at `io_pgetevents`; declaring `c_standard = "gnu11"` LOOKS like the fix but mcpp 2026.8.27.2 accepts the string and still emits `-std=c11` (visible in the emitted `compile_commands.json`), so `-D_GNU_SOURCE` in `cflags` is the spelling that takes effect. **Symbol versioning in a static package**: `io_getevents` and `io_cancel` have no ordinary definitions upstream — the functions are `io_getevents_0_4` etc. publishing short names through `.symver … @@LIBAIO_0.4` — which resolves for an executable under both ld.bfd and lld, but not when a consumer builds a `.so` straight out of these objects; that needs upstream's `src/libaio.map`, exactly as upstream's own `libaio.a` does) |
 | C++-source compat, one depending on the other | [`compat.abseil`](../pkgs/c/compat.abseil.lua) (151 TUs; a wildcard over `absl/**` trimmed by upstream's test/benchmark naming conventions) · [`compat.protobuf`](../pkgs/c/compat.protobuf.lua) (the libprotobuf runtime, 79 TUs transcribed from upstream's own `src/file_lists.cmake`; declares `compat.abseil` as a dependency because protobuf's public headers include `absl/…`, and its `gzip` feature defines `HAVE_ZLIB` and pulls `compat.zlib`, while `upb` adds protobuf's 64-TU C runtime out of the same tarball. It also exposes **`protoc`** as a `kind = "bin"` target, so a consumer writing `tools = ["protoc"]` gets the compiler built for its own machine out of the same package it links — making a generator/runtime version mismatch inexpressible) · [`compat.re2`](../pkgs/c/compat.re2.lua) (22 TUs, upstream's own `RE2_SOURCES`) · [`compat.redis-plus-plus`](../pkgs/c/compat.redis-plus-plus.lua) (redis++ 1.3.13 — the sync client, 17 TUs + `patterns/redlock.cpp`, depends on `compat.hiredis`; the one header CMake would generate, `hiredis_features.h`, is snapshotted via `generated_files`, and the async/TLS TUs are left out so the base build stays a two-package pair. An `async` feature adds the libuv-backed `AsyncRedis` interface (the 9 async TUs + `compat.libuv`; `event_loop.cpp` runs `uv_run` on a background thread, and `<hiredis/adapters/libuv.h>` arrives through compat.hiredis' wrapper headers). Two versions, one on each side of the source-structure watershed, share this ONE source list: 1.3.13 (modern 17-TU layout) and 1.3.3 (pre-`redis_uri.cpp`/`redlock` 15-TU layout) — the union works because 1.3.3's TUs are a strict subset, so exactly two globs match nothing there (a warning, not an error; same trick as compat.catch2)) | · [`compat.sqlitecpp`](../pkgs/c/compat.sqlitecpp.lua) (the RAII C++ wrapper over SQLite. Upstream vendors sqlite3 as a GIT SUBMODULE, so a source tarball simply does not contain it and the library cannot link — the dependency edge on `compat.sqlite3` replaces the submodule, and does it better: two consumers of SQLite in one link now share ONE amalgamation instead of each embedding a private copy with its own compile-time options. Its two CMake knobs are deliberately not set — `SQLITECPP_USE_ASSERT_ON_ERRORS` changes the error model from throwing to aborting, and `SQLITE_ENABLE_COLUMN_METADATA` has to agree with how SQLite ITSELF was built; both are the consumer's call, and the headers already guard them with `#ifdef`)