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