feat(pack): ship a library as interface + prebuilt binaries (#433)

A closed-source library, an offline site, or a build farm that already
compiled this once had no route through mcpp: `mcpp publish` sends source,
`mcpp pack` bundles a program's run-time closure, and neither is "a library
someone else links". Collecting the artifacts by hand was the answer.

    mcpp pack mathkit                              # a static library package
    mcpp pack mathkit --target x86_64-linux-gnu \
                      --target aarch64-linux-gnu   # one package, two legs

WHAT IT PRODUCES IS AN ORDINARY PACKAGE. A normal `mcpp.toml`, read through
the route mcpp already had for payloads that carry their own manifest. Zero
new manifest sections and zero new keys: what to pack is `[targets.<n>].kind`
(so there is no --lib and no --artifact), which interface to publish is `[lib]`
plus the module graph, which headers are public is `[build].include_dirs`, and
each leg's ABI tag and digest ride on `[[runtime.artifacts]]`, whose fields
were already documented as optional evidence. An older mcpp still BUILDS
against these packages; it just does not run the two gates below.

Two interface modes coexist — `include/` (text, `#include`, never compiled)
and `interface/` (module units the consumer compiles). Measured: one package
consumed three ways (header only, module only, both) x static and shared = six
combinations, all green.

WHICH .cppm TRAVEL IS COMPUTED, not declared. It is the module closure of the
lib root, and the two ways of getting it wrong are asymmetric: too few fails
loudly in the consumer's compile, too many silently publishes a closed-source
implementation partition's SOURCE. `.m.o` is not the rule — an implementation
partition produces one too. The same closure decides which archive members to
drop, and getting THAT wrong was measured as well: dropping every `.m.o` also
drops the partition's real code and every target fails to link. Both lists are
printed, because "what is not travelling" is half of what a publisher needs.

TWO GATES ON THE CONSUMER SIDE, both for failures that are otherwise silent.
The interface still matches its binaries: swap two `int` members of a shipped
struct — the Itanium ABI does not mangle field order — and before this the
consumer compiled, linked, ran, and printed transposed data with no diagnostic
from any tool. And the binaries were built for this toolchain, with the
refusal listing the tags the package does have, because "not found" sends
people looking for a package already on their disk.

Also fixes two defects this work found, each with its own regression test:

  * `[target.'<triple>'.build]` never matched a native build. `matches()`
    short-circuited on the raw --target string while `context_for()` fell back
    to the host for `cfg(...)`, so two spellings of one statement disagreed —
    green in CI, silently inert on a developer's machine. The resolved triple
    now lives in `cfgpred::Ctx`; there is no second answerer.

  * `sources = []` was byte-identical to omitting the key, so no author could
    say "compile nothing". A header-only package needs that, and without it
    any leftover file under `src/` is compiled into the consumer's build.

Docs: docs/12-binary-distribution.md (+ zh), examples 05-lib-dist and
06-lib-consume. Design: .agents/docs/2026-08-17-library-distribution-design.md.

Tests: 23 unit assertions across two new suites; e2e 242-248.

Author: speak-agent

.agents/docs/2026-08-17-distribution-architecture-analysis-and-design.md

@@ -5,8 +5,74 @@
 
 ## [Unreleased]
 
+### 新增
+
+- **`mcpp pack <target>` 可以把一个库打成「接口 + 预编译二进制」的包(#433)。**
+
+  闭源库、离线环境、以及「构建农场已经编过一遍了」这三种场景,过去都只能自己
+  写脚本收集产物。现在:
+
+  ```bash
+  mcpp pack mathkit                              # 静态库包
+  mcpp pack mathkit --target x86_64-linux-gnu \
+                    --target aarch64-linux-gnu   # 一个包,两条腿
+  ```
+
+  **产出的是一个普通的 mcpp 包** —— 一份正常的 `mcpp.toml`,走 mcpp 早就有的
+  「载荷自带 manifest」通路。**新增 manifest 段 0 个、键 0 个**:打什么由
+  `[targets.<n>].kind` 决定(所以没有 `--lib`、没有 `--artifact`),发布哪些接口
+  由 `[lib]` 约定 + 模块图决定,公开头是 `[build].include_dirs` 全量,
+  每条腿的 ABI tag 与 digest 记在既有的 `[[runtime.artifacts]]` 上。
+  一个**老版本 mcpp 照样能构建**这种包 —— 它只是不执行下面那两道闸门。
+
+  一个包可以同时带**两种接口**:`include/`(文本,`#include`,不编译)与
+  `interface/`(模块,消费者编译它)。实测同一个包被「只 #include」/「只 import」/
+  「两者都用」三种方式消费,静态与动态两种形态,六格全过。
+
+  发布哪些 `.cppm` 是**算出来的** —— lib root 的模块闭包,不是「所有 `.m.o`」。
+  实现分区(`module M:secret;`)照样产 `.m.o`,按扩展名挑会**泄露闭源源码**;
+  同一个闭包反过来决定归档里要删哪些对象,按 `.m.o` 删则会删掉真代码、
+  三个平台全部链接失败。两条清单都会打印出来。
+
+  详见 `docs/12-binary-distribution.md`、`examples/05-lib-dist`、`examples/06-lib-consume`。
+
+- **消费预编译包时的两道闸门。** 都是不检查就会静默出错的:
+
+  **接口与二进制是否仍然配对。** 这条闸门存在是因为另一种结果被实测过:把随包
+  接口里一个结构体的两个 `int` 成员互换 —— Itanium ABI 不 mangle 字段顺序 ——
+  消费者**编译过、链接过、运行过、打印出交换后的错数据**,任何工具都没有一句诊断。
+
+  **二进制是否为这套工具链所编。** 失配时诊断会**列出包里确实有哪些 tag** ——
+  一句「找不到」会让人去找一个就在自己硬盘上的包。
+
+  另外,在解开的分发包目录里直接 `mcpp build` 会被拒绝:那儿的 `interface/`
+  是声明,定义在旁边的归档里,构建会产出一个几乎空的库然后报告成功。
+
 ### 修复
 
+- **`[target.'<三元组>'.build]` 在没有 `--target` 时从不命中。**
+
+  同一个语句的两种拼写互相矛盾:`cfg(linux)` 在原生构建上命中,
+  `[target.'x86_64-linux-gnu'.build]` 不命中。根因是 `matches()` 拿着原始的
+  `--target` 字符串(原生构建下是空的)短路返回 false,而同一文件的
+  `context_for()` 对 `cfg(...)` **回落到宿主三元组** —— 一个决定两处推导。
+  `manifest/types.cppm` 的注释从写下起承诺的就是回落那一种。
+
+  **形状是最坏的那种**:CI 传 `--target` 是绿的,开发者本机的 `mcpp build`
+  静默丢掉那一段,失败在链接期出现、点的是符号而不是谓词。
+
+  修法是**删掉第二个答题者**:解析后的三元组进 `cfgpred::Ctx`,`matches()`
+  只有一个来源。
+
+- **`sources = []` 与不写 `sources` 逐字节等价。**
+
+  解析器在向量为空时一律填默认 glob,于是作者**没有任何写法**能表达
+  「什么都不要编」。二进制分发需要这个:一个纯头文件的包不编译任何东西,
+  而 `src/` 下任何遗留文件都会被扫进消费者的构建,并可能与预编译库里的符号
+  重复定义。改成记录**键是否出现**(`BuildConfig::sourcesDeclared`),
+  与 `XlingsConfig::subosDeclared` 同一个模式。
+
+
 - **卸载后的清扫会波及**别的版本**,而那可能正在被另一个进程解压。**
 
   `sweep_parked_payloads` 原来把整个 family 目录扫一遍,把**任何**没有文件的

.agents/docs/2026-08-17-library-distribution-design.md

@@ -1,4 +1,12 @@
-# 02 — Packaging for Release
+# 02 — Packaging an Application for Release
+
+> This page is about bundling a **program**. To ship a *library* as interface +
+> prebuilt binaries, see [12 - Distributing a Prebuilt Library](12-binary-distribution.md).
+>
+> Which one `mcpp pack` does is decided by the target's `kind`, not by a flag:
+> `mcpp pack <name>` packs `[targets.<name>]`, and a `bin` becomes a bundle
+> while a `lib`/`shared` becomes a library package. With no name, mcpp picks
+> the only packable target.
 
 > A default dynamically linked binary produced by `mcpp build` has a loader and
 > RUNPATH tied to the build sandbox. It is a development artifact, not a

CHANGELOG.md

@@ -153,6 +153,12 @@ the package/feature boundary, not on an individual target.
 
 ### 2.3 `[build]` — Build Configuration
 
+> **`sources = []` is not the same as omitting `sources`.** An absent key
+> selects the default glob; an explicitly empty list means *compile nothing*,
+> which is what a header-only distribution package needs to say. Until
+> mcpp 2026.8.17.2 the two were byte-identical, so there was no spelling for
+> "nothing" and any file left under `src/` was swept in.
+
 ```toml
 [build]
 sources      = ["src/**/*.cppm", "src/**/*.cpp"]  # Source globs (default: src/**/*.{cppm,cpp,cc,c,S,s,asm})
@@ -1598,6 +1604,17 @@ do`.
 - Package-level knobs all converge into features; for sugar keys (such as `backend=`)
   to enter the core syntax, they must satisfy: ① domain-neutral (a cross-ecosystem
   general pattern) ② 1:1 desugaring with zero new parsing semantics.
+- **A key that duplicates an answer another section already gives is not admitted.**
+  Two places to state one fact is two places that can disagree, and the failure
+  is silent — whichever reader loses the race is simply wrong. Library packaging
+  ([12](12-binary-distribution.md)) is the worked example: it added **zero**
+  manifest keys, because what to pack is `[targets.<n>].kind`, which interface
+  to publish is `[lib]` plus the module graph, which headers are public is
+  `[build].include_dirs`, and the per-artifact evidence is `[[runtime.artifacts]]`.
+- A field that describes what a *generated* package IS (rather than what a build
+  should DO) belongs on `[[runtime.artifacts]]` — see §2.11. `provenance`
+  beginning with `mcpp-pack` is what marks a directory as one, and mcpp refuses
+  to `build` inside it.
 - See `.agents/docs/2026-06-04-manifest-schema-ownership.md` for the full field-ownership
   table and the finalized decisions.
 

docs/02-pack-and-release.md

@@ -0,0 +1,263 @@
+# 12 - Distributing a Prebuilt Library
+
+**English** | [简体中文](zh/12-binary-distribution.md)
+
+> Ship a library as **interface + prebuilt binaries** instead of as source.
+> This is the closed-source case, and the offline case, and the "our build farm
+> already compiled this once" case.
+>
+> [02 - Packaging & Release](02-pack-and-release.md) is the sibling: bundling an
+> *application*. [10 - Publishing a Library](10-publishing-a-library.md) is the
+> source route.
+
+## The whole idea in one paragraph
+
+`mcpp pack <target>` builds a library target and writes a directory that is an
+**ordinary mcpp package** — a normal `mcpp.toml`, the interface a consumer must
+compile, and the binaries it then links. Consumers use it exactly like any
+other dependency. There is no new manifest section, no new archive format, and
+no new resolution path.
+
+```bash
+mcpp pack mathkit                              # a static library package
+mcpp pack mathkit-shared                       # a dynamic one (Linux/ELF today)
+mcpp pack mathkit --target x86_64-linux-gnu \
+                  --target aarch64-linux-gnu   # one package, two legs
+```
+
+## What decides what gets packed
+
+`[targets.<name>].kind`, and nothing else:
+
+| `kind` | `mcpp pack <name>` produces | `--mode` |
+|---|---|---|
+| `bin` | an application bundle (see [02](02-pack-and-release.md)) | the four depths |
+| `lib` | a **static library package** | — |
+| `shared` | a **dynamic library package** | — |
+
+There is no `--lib` flag and no `--artifact static\|shared`. `kind` is already
+where mcpp records what an artifact is; a flag would be a second place to say
+it, and two places can disagree. A project that publishes both forms declares
+both targets — which it must do for `mcpp build` to produce both anyway:
+
+```toml
+[targets.mathkit]
+kind = "lib"
+
+[targets.mathkit-shared]
+kind   = "shared"
+soname = "libmathkit.so.1"
+```
+
+Run `mcpp pack` with no name and mcpp picks the only packable target, or tells
+you which ones it found.
+
+## The two interface modes
+
+A package can carry both, and a consumer may use either or both.
+
+```
+mathkit-0.1.0-x86_64-linux-gnu-gcc16-libstdcxx16-c++23/
+├── mcpp.toml
+├── include/          ← TEXT interface: #include, never compiled
+├── interface/        ← MODULE interface: the consumer compiles it
+└── lib/<triple>/     ← the artifacts
+```
+
+| | `include/` | `interface/` |
+|---|---|---|
+| whose input is it | the preprocessor's | the **compiler's** |
+| does the consumer compile it | no | **yes**, to get a BMI |
+| what it constrains | the libc ABI | compiler, C++ stdlib, C++ level |
+| can you trim it | **no** — see below | **no**, it is computed |
+
+`lib/` is keyed by **triple**, not by OS. MinGW and MSVC are both Windows and
+produce `libfoo.a` and `foo.lib` respectively.
+
+### Why neither set can be trimmed
+
+A **source** distribution of the same package puts every one of its
+`include_dirs` on its consumers' include path. If a binary package shipped a
+subset, the same library would have a different public surface depending on how
+it was delivered. "Which headers are public" is already answered by the layout:
+`include/` is public, `src/` is not. A private header under `include/` is a
+project-layout mistake, not a packaging option.
+
+## Which `.cppm` files travel
+
+The **module closure of the lib root** — `src/<package-tail>.cppm` by
+convention, or `[lib].path`. Whatever that unit's purview imports, transitively,
+is published; everything else is not.
+
+```
+src/mathkit.cppm    export module mathkit;  export import :api;   → published
+src/api.cppm        export module mathkit:api;                    → published
+src/secret.cppm     module mathkit:secret;         ← implementation partition
+src/impl.cpp        module mathkit;                                → withheld
+```
+
+`mcpp pack` prints both lists:
+
+```
+   Interface mathkit.cppm, api.cppm
+    Withheld capi.c, impl.cpp, secret.cppm
+```
+
+**Read the second one** if you are shipping closed source.
+
+> **`.m.o` is not the rule.** An implementation partition produces a BMI and an
+> object exactly like an interface unit does. Selecting sources by "does it
+> produce a BMI" would publish `secret.cppm`.
+
+If the published interface *does* import an implementation partition, a
+consumer cannot compile it without that source — so `mcpp pack` stops:
+
+```
+error: the published interface imports mathkit:secret , which no unit in this
+       build provides.
+```
+
+Restructure so the interface does not reach it, or make it an `export module`
+partition and accept that its source is published.
+
+## The compatibility tag
+
+Every artifact records the toolchain it was built for:
+
+```
+x86_64-linux-gnu-gcc16-libstdcxx16-c++23      # a C++ module interface
+x86_64-linux-gnu                              # an extern "C" interface only
+```
+
+`<arch>-<os>-<env>` then, when the interface is C++, `<compiler><major>`,
+`<stdlib><major>`, `c++<level>`.
+
+**A shorter tag is a real statement, not a missing one.** A library whose whole
+interface is `extern "C"` constrains the libc ABI and not the C++ one, so it
+publishes a triple and stops — and links into any compiler. Unnamed dimensions
+are don't-care, so one tag per triple instead of one per triple per compiler.
+Nothing to configure: the shape is the statement.
+
+The `c++` level is compared as a **floor**, not for equality: building at a
+higher level is fine, lower is not.
+
+## What a consumer's build checks
+
+Two things, both of which fail silently without a check:
+
+**The interface still matches its binaries.**
+
+```
+error: acme.mathkit@0.1.0: 'interface' does not match what was packaged.
+  recorded fnv1a:25b2cf2a79d71c40
+  found    fnv1a:fe404d5be85118ff
+```
+
+This exists because the alternative was measured. Swap two `int` members of a
+struct in a shipped interface — the Itanium ABI does not mangle field order —
+and the consumer compiles, links, runs, and prints transposed data, with no
+diagnostic from any tool. A digest cannot stop a publisher from shipping a
+mismatched pair (only producing both in one command does that), but it does
+catch the pair coming apart afterwards.
+
+**The binaries were built for this toolchain.**
+
+```
+error: acme.mathkit@0.1.0: no prebuilt artifact matches this toolchain.
+  your toolchain : x86_64-linux-gnu-gcc16-libstdcxx16-c++23
+  published tags :
+                   x86_64-linux-gnu-gcc15-libstdcxx15-c++23
+  closest is x86_64-linux-gnu-gcc15-libstdcxx15-c++23, and it differs on:
+    compiler  needs gcc15, this build has gcc16
+    stdlib    needs libstdcxx15, this build has libstdcxx16
+```
+
+The tags it *does* have are part of the message: "not found" would send you
+looking for a package already on your disk.
+
+## Consuming one
+
+Three spellings, one code path:
+
+```toml
+# a directory (what you hand a colleague)
+mathkit = { path = "vendor/mathkit-0.1.0-x86_64-linux-gnu-gcc16-libstdcxx16-c++23" }
+
+# a private git repo
+mathkit = { git = "ssh://git@internal/mathkit-dist.git", tag = "v0.1.0" }
+
+# an index entry — identical in shape to a source package's
+mathkit = "0.1.0"
+```
+
+Nothing about the consumer's manifest says "this one is prebuilt".
+
+### Building *inside* a package is refused
+
+```
+error: … is a distribution package produced by `mcpp pack`, not a source tree.
+```
+
+Its `interface/` holds declarations whose definitions are in the archive beside
+them. Building there compiles the declarations, produces a near-empty library
+and reports success.
+
+## One package, several targets
+
+`--target` is repeatable. The generated manifest gets one conditional block per
+leg, and the consumer's build picks its own:
+
+```toml
+[target.'cfg(all(arch = "x86_64", os = "linux", env = "gnu"))'.build]
+ldflags = ["-Llib/x86_64-linux-gnu", "-lmathkit"]
+
+[target.'cfg(all(arch = "x86_64", os = "linux", env = "musl"))'.build]
+ldflags = ["-Llib/x86_64-linux-musl", "-lmathkit"]
+```
+
+Because selection happens in the **consumer's** build, where the resolved
+target is known, a fat package cross-compiles correctly with no index-side or
+installer-side support at all.
+
+> The blocks are `cfg(...)` and never a bare `[target.'<triple>']` key. Before
+> mcpp 2026.8.17.2 the bare form was inert without an explicit `--target`, so a
+> package using it would work in CI and silently drop its flags on a
+> developer's machine. mcpp generates the spelling that means the same thing on
+> every client.
+
+## Dependencies
+
+A static archive does **not** carry its dependencies' code, so the package
+records them and the consumer resolves them:
+
+```toml
+[dependencies]
+"compat.zlib" = "1.3.2"
+```
+
+`path` and `git` dependencies are dropped: they address the publisher's disk,
+and republishing one hands the consumer an address that means something else.
+If your library depends on one, either publish that dependency too or vendor it
+before packing.
+
+## What older mcpp does with these packages
+
+**It builds against them.** Every key in the generated manifest already
+existed, so an older client reads the package and links it. What it does not do
+is run the two checks above — it has no way to know that `provenance =
+"mcpp-pack …"` means anything.
+
+That is a degradation, not a break, and it is the right direction. But it means
+**the gate protects new clients only**, which belongs in your release notes if
+you publish to a mixed audience.
+
+## Current limits
+
+| | status |
+|---|---|
+| `kind = "lib"` (static) | ✅ every target |
+| `kind = "shared"` on Linux/ELF | ✅ |
+| `kind = "shared"` on PE / Mach-O | ❌ refused — import libraries and install-names are not modelled yet |
+| `kind = "shared"` on `*-musl` | ❌ a musl target links statically |
+| shipping prebuilt BMIs | ❌ not attempted; BMIs are compiler-build-exact |
+| bundling dependencies into the package | ❌ declare them instead (above) |

docs/05-mcpp-toml.md

@@ -14,6 +14,7 @@
 - [09 - Releasing mcpp](09-release.md)
 - [10 - Publishing a Library to mcpp-index](10-publishing-a-library.md)
 - [11 - Machine-Readable Output](11-machine-output.md)
+- [12 - Distributing a Prebuilt Library](12-binary-distribution.md)
 
 ## Specifications