编译运行接口规范 0.1.0
本包让应用在宿主的隔离编译环境里，把一个多文件豫言项目编译成 WasmGC 程序，并在编译进行中逐个取回阶段提示与编译器输出。它是“云端编译服务”的核心：请求的校验、限额、响应形状与流式回报都由应用用豫言决定；宿主只做“运行豫言编译器”这一件事——内存文件系统、标准库资料、编译器 Wasm 与 Binaryen 组装。编译产物是文件式 WasmGC 程序，可直接交给[隔离运行接口](../隔离运行/规范.汉语.md)运行：本包的 读取编译产物Base64 给出的正是它的程序参数。这是云工专用能力：宿主用外壳在进程里固定的编译资料运行编译器，应用须在许可里授权一个 COMPILE 绑定名。
运行模型
拉取式，一次运行的生命周期是：启动编译运行 得到运行号 → 循环 读取编译运行事件 阻塞取下一个事件，直到取到终止事件 → 按需 读取编译产物 或 读取编译产物Base64 → 结束编译运行 释放。运行号是宿主生成的、不可猜测的字符串；应用不能自造。运行号只在启动它的事件内有效：另一个事件里拿到的运行号（哪怕字符串相同）一律使调用抛出可捕获的豫言异常，不会误操作别的事件的运行（同 网页事件流 的流柄规则；也因为 Worker 一类宿主不允许一个事件的异步工作在别的事件里继续）。所以一次编译的启动、事件读取、产物读取与结束必须发生在同一个事件里。事件按发生顺序取出，宿主可以边编译边产出，也可以编译结束后一次产出，接口都不承诺产出时机（应用不得依赖“先见到过程事件、后编译结束”的时序）。
函数
启动编译运行 编译器名 请求，返回运行号。
| 参数 | 含义 |
| --- | --- |
| 编译器名 | 应用许可里 COMPILE 列表授权的绑定名，1 至 128 字节，不含控制字符；未授权或绑定不存在使本次事件失败 |
| 请求 | JSON 文字，至多 2097152 字节：{"files":{"路径":"文字",…},"entry":"路径"}，其他字段忽略 |
请求规则：files 是路径到文字的对象，含 1 至 256 个文件，值都是字符串，全部内容合计至多 262144 个 UTF-8 字节；每个路径至多 256 个 UTF-16 码元，不含反斜线与 U+0000 至 U+001F 的控制字符，不以 / 起首，且以 / 分段后每段非空、不是 . 或 ..。entry 缺省或为 null 时取 入口。豫，必须是合规路径且在 files 里。违反任何一条，或尚未终止的运行已有 8 个（宿主忙），都抛出可捕获的豫言异常（消息中文，说明原因），不产生运行；绑定未授权则使本事件失败。成功时立即返回，编译在宿主里进行。
读取编译运行事件 编译器名 运行号 等待毫秒，返回（状态，事件 JSON 文字）。
- 阻塞等待这次运行的下一个事件。等待毫秒须在 1 至 60000，越界抛异常。
- 状态
0：得到一个事件，文字是它的 JSON（每个事件是一个 JSON 对象，见下节）。 - 状态
1：等待毫秒到期而没有新事件，运行仍在进行，事件文字为空串。应用可据此写心跳、检查自己的期限或继续等待。 - 状态
2：运行已终止且全部事件已取尽（终止事件已经在前面某次以状态 0 交付过），或者读取者在等待期间运行被结束编译运行结束；事件文字为空串。 - 同一运行同一时刻至多一个等待者；运行号无效（空、过长、含控制字符）、不属于当前事件、未知或已结束，抛出可捕获的豫言异常。
读取编译产物 编译器名 运行号，返回字节串：编译成功（终止事件是带 artifact 的 finished）的 WasmGC 程序原始字节，至多 8388608 字节，可含零字节。运行尚未终止、编译失败、宿主故障或运行已结束，抛出可捕获的豫言异常。读取编译产物Base64 返回同一份产物的 Base64 文字（标准字母表，带 = 填充，无换行），前提与失败相同。两个函数在 结束编译运行 之前可重复调用，结果相同。
结束编译运行 编译器名 运行号 结束运行并释放宿主资源（事件队列、产物字节），返回单位值。幂等：运行号未知或已结束不报错。尚未开始编译的运行不再编译；已经在编译的运行无法被打断，宿主丢弃它的后续结果。结束后再用该运行号读取事件或产物抛出可捕获的豫言异常；正在等待事件的读取者立即得到状态 2。运行号不属于当前事件同样抛出异常（幂等只对本事件里已结束或未知的运行号）。应用应当在任何路径（含出错）上都结束自己启动的运行，否则运行留在宿主里直到 5 分钟的存活期满被宿主回收；事件异常退出遗留的运行既不会永久占用并发额度（并发额度只算尚未终止的运行），也不会无限堆积（见限额）。
事件
事件文字是一个 JSON 对象，type 区分种类。宿主可以增加新的过程事件种类，应用遇到不认识的种类须忽略而不是报错。
| type | 字段 | 含义 |
| --- | --- | --- |
| stage | label：中文阶段提示；可带 phase（compile） | 编译进行到的阶段，依据实际执行的步骤发出。至少有“正在加载标准库与项目文件”与“正在执行豫言编译器”，其后编译器组装 Wasm 时还有“正在组装 Wasm（N 字符）” |
| output | phase（compile）、stream（stdout 或 stderr）、text | 编译器写出的一段输出，原样、不截断、不拆行合并 |
| diagnostic | text | 编译器异常终止时的诊断（最近读取的文件与错误栈），只在失败时出现 |
| finished | result：{"ok":爻,"stdout":文字,"stderr":文字,"exitCode":整数,"error"?:文字}；artifact（仅成功）：{"format":"wasmgc","bytes":整数,"sha256":64 位小写十六进制} | 终止事件：编译器已运行完毕。ok 为真当且仅当退出码为 0；stdout 与 stderr 是全部输出，等于依序拼接全部同名 output 事件的 text。编译失败（语法错误、类型错误、输出超限、超时）是 finished 且 ok 为假，没有 artifact，error 与 stderr 说明原因 |
| failed | error：中文原因 | 终止事件：宿主故障，编译器没有给出结果（标准库资源不可用、文件系统超限、产物超过 8 MiB 等） |
每次运行恰有一个终止事件，它总是最后一个事件。artifact.sha256 是产物字节的 SHA-256；bytes 是字节数。
编译环境
- 标准环境：每次运行都在全新的内存文件系统里进行，预置宿主固定版本的标准库资料；包上下文由宿主固定：包
豫言/标准库，以及所有者访客、名云项目、依赖标准库的项目包。项目文件放在项目包目录（宿主内部路径/用户程序/）下，entry相对它；项目若含云项目。包。豫则采用它，否则宿主放一个空描述。编译目标固定为 WasmGC。应用不能选择编译器版本、目标、包上下文或标准库。 - 无外部能力：编译过程没有网络、原生进程、环境变量与宿主文件；运行之间不遗留任何用户文件或产物，任何一次运行也读不到前次运行写入的东西。
- 限额：编译器输出（
stdout与stderr合计）至多 2097152 字节，超过则编译失败；一次编译的墙钟期限由宿主定（云工宿主是 90 秒，在编译器调用宿主原语时检查）；产物至多 8388608 字节；事件文字合计至多 16777216 字节（超出的过程事件被宿主丢弃，终止事件不丢）。同一宿主进程里尚未终止（排队或编译中）的运行至多 8 个，超过则启动编译运行抛异常；已终止而等待读取的运行另留至多 32 个，更多时丢弃最旧的；任何运行自创建起至多存活 5 分钟。编译阶段串行进行（同一时刻只有一份编译文件系统副本），排在后面的运行先等待。 - 同一版本的编译器与标准库对同一份项目应给出相同的
ok、exitCode与产物字节；编译器日志行带墙钟时间戳，stderr的文字因此不逐字节可比。
失败分类
- 违规（可捕获的豫言异常）：请求不合规、超限、并发运行过多、编译器名不合规、等待毫秒越界、运行号无效或不属于当前事件、运行号未知或已结束、同一运行已有等待者、产物不可用。异常消息是中文，说明原因。
- 绑定未授权或不存在：使本次事件失败（宿主错误，应用不能捕获），与其他云工接口一致；这是部署配置问题，不是运行时业务情形。
- 编译失败：是返回值（
finished且ok为假），不是异常。 - 宿主故障：是
failed事件，不是异常。
一致性样例
- 入口
寻观「标准库」之书。寻观「云项目」之「问候」之书。「打印行」于「问候」。、问候。豫（定义问候为『你好，多文件』）与云项目。包。豫三个文件：事件序列以stage（正在加载标准库与项目文件）、stage（正在执行豫言编译器）起头，若干output之后恰有一个finished（ok为真、exitCode为 0）与artifact；再读事件得状态 2；读取编译产物的字节以 Wasm 魔数起头且长度等于artifact.bytes，SHA-256 等于artifact.sha256；读取编译产物Base64解码后与字节一致；stdout与stderr等于对应output的text依序拼接。 - 入口内容
此语不成立。：finished、ok为假、无artifact；读取编译产物抛出异常；stderr或error提到入口文件。 - 请求
{"files":{"../逃逸。豫":""}}、{"files":{}}、{"files":{"入口。豫":1}}、入口内容 262145 字节、文件名含反斜线或以/起首、entry不在files里：启动编译运行都抛出异常，宿主里没有产生运行。 - 先后启动两次内容不同的运行：各自的产物与事件互不串扰；第二次读不到第一次写入的任何文件（同一路径的第二个项目不会看到第一个项目的其他文件）。
- 事件流取尽后再读：状态 2；
结束编译运行之后再读事件、再读产物：抛异常；重复结束：不报错。 - 阻塞等待时另一个并发读取者：抛异常，不影响原等待者；等待毫秒为 0 或 60001：抛异常。
- 在另一个事件里使用启动事件返回的运行号（读取事件、读取产物、结束）：抛异常，原事件里的运行不受影响。
边界
本包只做编译：不运行产物（用隔离运行接口）、不解析或托管 HTTP、不保存任何状态、不提供网络、不做包解析（只有标准库和项目自己的文件）、不做编译缓存的对外承诺。宿主可以用不同的技术实现（云工用 Worker 内的 WasmGC 编译器与静态 Binaryen，别的宿主可用进程沙箱或容器），只要满足上述环境、限额与事件语义。COMPILE 是云工的许可种类名；别的宿主用各自的授权方式，接口只要求“编译器名由应用给出、由宿主核对”。