amos 913d3c367f Add the usable task catalog and admit batch 6 tasks
All 161 task packages, including the 21 batch 6 C++17 tasks that passed
gates 1/2, are now in Git. rollout.catalog builds docs/task-catalog.{json,md}
from the task packages, a fresh trace5 calibration (128/128 PASS), every
verified controller receipt on the current task digest, documented holds
and digest-bound difficulty reviews. 123 tasks are usable (6 HARD),
5 are on hold and 33 still need a subprocess-only grader.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18 17:43:15 +08:00

54 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 服务实例转义、编译与流式发布合同 v1
这是明确有界的服务配置软件模型。基础的字节转义和说明符语义由Bos n3素材重构;流式feed/finish/reset、公开编译程序与下面的容量及状态规则是本工程新增合同,不是原素材已有功能。不声称实现完整systemd命名规范。
01. 所有string/string_view长度均按字节,允许内含NUL,不使用C字符串终止约定。有效UTF-8表示Unicode scalar的最短编码:允许U+0000、BOM和非字符;拒绝孤立续字节、过长编码、surrogate U+D800..DFFF、U+10FFFF以上及不完整尾部。不作Unicode正规化或大小写折叠。
02. valid_utf8对任意长度输入按01返回bool,空输入true,不受其它API的长度上限约束。所有输入只读,函数不读取locale、文件或进程环境。
03. Error仅none=0/invalid=1。escape/unescape/render/expand失败时output变为空string;parse_unit失败时output变为默认ServiceName(五string空、instantiated=false);compile_template失败时Program.pieces为空。错误不能保留预置旧值或部分输出;成功完整替换。所有返回的值由调用方独立拥有。
## 整体字节转换
04. escape输入0..4096字节且须为01完整UTF-8。保留集合SAFE恰为ASCII字母、ASCII数字、下划线、冒号、点。输入的第一个字节若为点则必须转义,之后的点保留;空输入输出空。位置按整个输入计算,不按字符或分块重新开始。
05. escape对每个不保留的UTF-8字节分别输出四个ASCII字节“反斜杠、小写x、两位小写十六进制”。斜杠、连字符、反斜杠、百分号、NUL和所有非ASCII字节均按此规则。不将一个Unicode scalar合成一个hex数,不输出大写hex。
06. unescape输入0..16384字节。逐项只接受裸SAFE字节或恰四字节的反斜杠xHH,x必须小写,HH允许大小写。裸非SAFE字节(含裸NUL、高位字节、@、空格和百分号)、未知/截断转义均invalid。允许开头裸点作为合法非规范输入。
07. unescape把每个hex项解成一个原字节,与裸SAFE字节拼接;最终必须符合01完整UTF-8。结果保留NUL/BOM/大小写及全部字符,空输入得到空;不删除前导点、不把斜杠或连字符改成其它字符。API上限分别按04/06独立适用。
## 服务名的两个视图
08. parse_unit接受1..4096字节,必须以字节全等的小写.service结尾;恰去掉最后这8字节。剩余stem只能是PREFIX或PREFIX@INSTANCE,原字符串中裸@至多一个;PREFIX非空,有@时INSTANCE也非空。没有其它后缀、隐藏长度或文件名限制。
09. 先按原始stem中的裸@分隔,再分别按06/07验证和解码组件。编码项反斜杠x40产生的数据@不是分隔符;不可先解码再切分。PREFIX/INSTANCE保留原来的hex大小写、裸前导点和全部编码拼写,不能先规范化。
10. 成功ServiceName.unit为原始完整服务名,prefix/instance为09的未解码组件,decoded_prefix/decoded_instance为各自解码结果。无实例时instantiated=false且两个instance字段都空;有实例时true。解码组件可含NUL、斜杠、@、百分号等合法UTF-8数据;这些不是额外服务名分隔规则。
11. 例如原字节串`x\x40y@z.service`(其中只有一个反斜杠)只有一个裸@,prefix解码为x@y;.hidden.service合法且保留裸点;a.service.service的prefix为a.service。空模板或不用实例的模板也不能绕过整个unit校验。
## 公开模板程序
12. compile_template输入0..4096字节且须为01完整UTF-8,允许NUL。普通字符逐字节保留。唯一说明符为%%、%n、%p、%i、%I;未知说明符(包括%P)或最后单个%均invalid。整个模板验证完才发布Program。
13. Program是Piece序列。PieceKind整数值固定literal=0、entire_unit=1、prefix=2、instance=3、decoded_instance=4、percent=5。compile_template把%n/%p/%i/%I/%%分别编译为1/2/3/4/5,非literal的text为空;连续普通字节合为一个非空literal。空模板产生空序列;不能把%%编译后的百分号再次解释。
14. render也接受调用者直接构造的Program:pieces可为0..4096项;kind必须0..5;非literal的text必须空;literal的text可空、可含字面百分号/NUL,但每项必须是完整01 UTF-8,全部literal的总字节数至多4096。允许相邻literal,不要求来自compile_template或规范合并。必须完整验证所有项。
15. render先按14完整验证Program并按08-10完整验证unit。替换值:1为原始unit;2为未解码prefix;3为未解码instance;4为解码instance;5为一个百分号。literal只复制text。无实例时3/4产生空string。不得用decoded_prefix代替%p,或用编码instance代替%I。
16. 替换内容永远是数据,不递归编译或展开其中的百分号;直接构造literal中的百分号也只是数据。例如实例编码为反斜杠x25n时,模板%I输出字面%n,而不是再次替换为服务名。
17. render的capacity允许0..65536,按结果字节数计算,恰等成功;超出范围或最终结果超过capacity均invalid且按03清空。capacity=0仅允许空结果。字符串增长必须避免size_t回绕,不能截断、部分返回或按Unicode字符数计算。
18. expand(text,unit,capacity,output)语义等于先compile_template再render;所有入口都独立校验,不要求调用方预处理。空Program、空模板、空结果、capacity=0都仍需校验全部其它输入。各次调用不共享服务名、程序或输出缓存。
## 流式转换的状态与提交点
19. Stream默认构造为mode=escape、phase=open、capacity=16384、input_bytes=utf8_pending=escape_pending=0、result为空。两个Stream完全独立。view是当前状态的独立值快照,不推进解析,不发布暂存输出。
20. reset只接受Mode escape=0或unescape=1,capacity为0..16384。参数非法返回invalid且整个旧状态(包括成功result)不变;合法返回none,切到指定mode/capacity并回到open,其余19的字段清零/空。reset可取消进行中、错误或已完成的转换,不产生结果。
21. open状态feed按顺序解析完整chunk,允许任意分块;escape按04/05处理输入UTF-8字节,unescape按06解hex后再检验07的UTF-8。UTF-8 scalar和反斜杠xHH都允许跨chunk,不因一次feed结束而认定尾部截断。成功feed返回none,仍为open,result始终空。
22. 成功feed后的input_bytes为本次reset之后成功接受的原始chunk总字节数,包含尚未完整的前缀;escape总输入上限4096、unescape总输入上限16384,恰等允许。空chunk在open时成功且全部状态不变;不得因空feed完成待定前缀或发布结果。
23. utf8_pending是尚未完整的一个UTF-8 scalar已收到的字节数,范围0..3;unescape中按hex已解出的原字节计算。escape_pending只用于unescape,为未完成hex项已经收到的原始字符数:反斜杠为1、反斜杠x为2、反斜杠xH为3;否则0,escape模式恒0。两种pending可同时非零,例如已解出多字节UTF-8首字节后又收到下个hex项的前缀。
24. 发现不可能成为合法编码的字节/转义,或22的总原始输入上限会被超过时,该feed返回invalid并进入phase=invalid;input_bytes和两个pending清零,result为空,所有暂存字节丢弃,mode/capacity保持。无须继续解释同一chunk的后续字节。错误不泄漏本次或以前feed暂存的输出。
25. capacity只在finish检查,不在feed提前检查。即使目前已暂存的转换结果大于capacity,语法仍可能完整或不完整,feed仍按21-24返回open/none;view.result为空。输入上限与输出capacity是两个独立约束,不把容量不足伪装成错误输入字节。
26. finish在open时才对完整输入执行最终检查:两个pending都须为0,转换结果长度须<=capacity;任一不满足按24转invalid并清空。否则返回none,phase变finished,result一次发布完整转换结果,保留input_bytes,两个pending为0。恰capacity及空输入都可成功。
27. finished状态再次finish返回none且全部状态保持;invalid状态finish返回invalid且保持。finished或invalid状态任何feed(包括空chunk)返回invalid且全部状态保持;不能隐式开启下一条转换。只有成功reset才回到open。
28. 在输入与容量合法且最终完整时,任意分块后finish与整体escape/unescape得到相同结果;比较时整体API使用04/06固定上限,Stream额外受reset给定capacity限制。未finish、invalid、finished三个阶段必须可由view区分,不能用空result代替阶段判断。
29. view字段恰为header的mode、phase、capacity、input_bytes、utf8_pending、escape_pending、result;不公开内部缓冲或指针。保存的view在后续feed/finish/reset后不变;修改view副本不能改Stream。构造、reset、view不打印日志或访问外部服务。
## 错误、构建和观察
30. 调用方保证输出对象不与任何输入对象或string_view源缓冲重叠。所有API输入不可修改,包括Program各Piece与两份string_view源数据。输出string/Program/ServiceName/view各自独立;后续成功、失败、另一实例或另一服务名的调用不能改写旧输出。除20/24/26/27列出的状态效果,错误无其它状态变化;有效API调用正常返回,不能用崩溃或异常代替Error。
31. 工程仅用现有g++ -std=c++17 -O2 -Wall -Wextra -pedantic和标准库。make生成unit-observe;允许重组四候选内部算法/表示,但保留unit_specifiers.h公开API。无需真实systemd、设备、文件、locale安装、网络或额外依赖。
32. 评分在干净目录重建四候选与同一公开header/观察器。构建限30秒,单次观察程序20秒,整体验收120秒;输入确定,不能依赖紧时限、调度或真实时钟区分正确性。
33. docs/console.md是只读观察器的行协议。观察器只调用公开API、保存/打印原始值与完整输入前后不变布尔值,不含期望、断言或私有用例。有效wire命令(含业务invalid)每条输出一条JSON且正常EOF exit0;wire格式错误exit2。stdout仅协议,stderr允许任意诊断,UTF-8允许。
34. 评分覆盖其它合法服务拼写、Unicode scalar/NUL、大小写hex、前导点、容量恰等/不足、非规范合法程序、交错实例和中间view;所有正确行为仍只来自本合同。可替换私有数据结构,不要求某种UTF-8库、编译算法或存储方式。