@bpos/activity-contract (9.3.0)
Installation
@bpos:registry=https://gitea.akhr-ai.com/api/packages/ChaiHao/npm/npm install @bpos/activity-contract@9.3.0"@bpos/activity-contract": "9.3.0"About this package
@bpos/activity-contract —— 脚手架契约
系统给活动的只有一样东西：这份契约。 契约以内是系统；契约以外、活动包以内的一切归活动。 那就是黑盒线的准确位置。
形状全部是 zod，不是 TS 接口：每次跨界调用双向 safeParse —— 系统不信任活动交来的，
活动侧的 SDK 也校验系统答的，装不装 SDK 都拦得住。
规范在《操作系统系统设计》：§6.1（清单）· §3（操作表单）· §6.2（活动进程）· §6.4（能力面的名词表）· §6.5（事件表）· §4.2（工单那一组）· §2.8（业务数据）· §7.3（交出的两条路）· §12（令牌只对本任务节点有效）。
三样东西
| 在哪 | 是什么 | |
|---|---|---|
| 线材 | src/index.ts |
递入信封 · 事件表 · 名词表 · 交出与错误信封 |
| 清单与操作表单 | src/manifest.ts |
bpos-activity.json 的形状（manifestSchema，含 declares.tables[] 的表声明）与工单定义那三段，加机检用的几把尺子（manifestGaps / outputIssues / orderIssues / tableIssues / artifactIssues / commitIssues / chartIssues / archiveIssues），以及件上 ref 那一格的值形状（refValueSchema / refIsEmpty / refKeyOf）与主键串的编解码（encodeRefKey / decodeRefKey） |
| 不在这里的 | — | 实践的图（graphSchema 那一组）——图归实践、在系统侧编排，活动不知道有边 |
清单在这里而不在工作台契约里，是因为它是活动交付物的形状：包一搬出这个仓，
手写 bpos-activity.json 的人得拿得到那把尺子。构建时 manifestSchema.parse(自己的清单)，
写坏了停在人改得动的地方，不必等装包那一刻由服务端说。
引用方向只许一边：本包不引 web/api/contracts；工作台契约单向引本包的清单形状，
再原样导出（接缝只有 web/api/contracts/plugin/manifest.ts 一处）。两向各有一条用例钉着：
本包的 tests/boundary.test.ts 钉禁止的那一向，server 的 tests/boundaries.test.ts R8 钉许可的那一向。
两个方向，两条线材
| 方向 | 线材 | 形状 |
|---|---|---|
| 系统 → 活动 | POST http://127.0.0.1:<BPOS_EVENT_PORT>/events |
eventEnvelopeSchema；进程答 eventAckSchema 即确认 |
| 活动 → 系统 | POST <BPOS_CAPABILITY_BASE>/call |
capabilityCallSchema → capabilityResultSchema |
| 活动 → 系统 | POST <BPOS_CAPABILITY_BASE>/handoff |
handoffSchema → handoffOutcomeSchema |
信封（环境变量）见 ACTIVITY_ENV：taskId · nodeRunId · nodeId · token · base · eventPort。
一个任务节点一个进程：进程知道自己是哪一单的哪一步，不知道图长什么样、别的步是谁。
事件
enter · work-order-reply · work-order-saved · work-order-mail · human-say · timer ·
control · handoff-refused（现算一份在 SYSTEM_EVENTS）。
每条带 id、按本任务节点内的先后顺序投、至少送到一次——活动用自己的实例状态去重，
系统不重放（§6.2）。每种事件的来处见 SYSTEM_EVENT_SOURCE：发出去的每一个口对着一条回来的路。
名词
工单 4（create · read · write · void）· 对话 2（say · input）· 模型 1 ·
业务数据 1（table.read，只读）· 工作持久 4（state · memory 各两个）· 文件 4（get · text ·
put · info）· 定时 1 · 本步读数 1 · 留痕 1（现算一份在 CAPABILITIES）。
写业务库不在里面（7.0）：落业务库只有工单提交一个入口——活动把要落的东西摆进工单的
数据对象、在数据表单的 commit 里声明落到哪，人提交、系统在那一个事务里落定并盖章。
归档同理随落定走（件上标了 archive 的文件格），所以没有单独的归档动作。
发卡也不在里面：对话区没有卡——要人拿个主意、补几格信息，派一张一两格的执行工单； 对象的新建同样只从工单落定来，系统不替活动建对象。 审批不在里面：活动不声明审批、不知道审批、收不到裁决。 邮箱也不在里面：信箱只服务系统的事件规则；沟通工单上的信由人在件下发出、由系统按信头 收回那张单上——活动既不发信、也不收信，只读得到那条往来。
什么改动要升大版本
往 CAPABILITIES / SYSTEM_EVENTS / CAPABILITY_ERRORS 这几个封闭集里减一个值，
对已经打好的活动包是破坏性的——那些包把旧的枚举内联进了 dist/activity.mjs。加一个值
破不破，看这个值从哪一头来：系统答出去的（一种事件、一个拒绝码）加了就破——老包拒收并报
「系统答的形状不对」，而毛病在系统；活动发出来的（一个能力名词）加了不破——老包不认识它，
也永远不会收到它。破坏性的走大版本，其余走小版本。
往事件载荷里加一个字段同样不破（zod 对象默认非严格，多的字段被忽略），走小版本。
分界线不是「改没改契约」，是「老包会不会收到一个它解不出来的东西」——看的是活动包内联的那一份。
清单那一侧收窄不按这条走：清单不在活动包内联校验的那条线上（manifestSchema 是系统在装包那一刻用的尺子），
所以判据换成一条：收窄之后从前跑得起来的包会不会跑不起来。会 → 大版本；
只是把一个本来就用不成的值提前拦下来（拦点从下游挪到机检，并说得更清楚）→ 小版本。
icon 收进图标调色板走的就是后者：调色板外的值从前装得进、机检还全绿，可它建不出活动类型来（建类型 422），
从来没有一个包靠它跑起来过。
判出大小版本之后还有四样要在同一次提交里做完（漏了哪一样都不当场报错，症状都出在别处）：
改代码常量与同名的 package.json · server 与 web 同一次改到 · 外层 AI-Native/CLAUDE.md 那张
「契约版本」表递一格 · 并进 main 后 contract/publish.sh 发一次私有 npm。四样各自漏了会怎样，
写在 contract/README.md「契约升版那一次提交要做的四样」。
5.5.0：enter 载荷加 extraContext（恒有，没填是空串）——往开放的对象里加字段，按上面的判据走小版本；活动清单的 ^5.x 范围都满足。
5.6.0：能力名词加 ledger.reverse（冲销一行台账：打废弃标记、记理由与本步，数字一个不动）、table.read 多一格
retired（不给就是在用行）；清单的表声明与列声明多几样注解（表的 text / time / refs，列的 text / measure）。
名词是活动发出来的那一头、注解是清单那一侧只放宽不收窄，两样都不破老包，走小版本。
5.7.0：工单封闭集加第四种 collaborate（协同工单：人带着自己的 AI 做出一份交付物，
执行工单偏人独立完成；同一副表单、同一枚「提交」，分界在谁来干）；工单定义加一格可选的
deliverable（只协同有、且必有，指数据结构里一个 file 字段——放行时那一格非空是系统那一道
的固定规则，机检第七查拦漏写 / 错写）。清单那一侧是放宽：从前跑得起来的三种单一个字都不用改；
work-order-reply 的结果集一个值都没加（协同与执行同一枚 submitted），所以老包也收不到
任何它解不出来的东西。两条判据都指向小版本。
5.8.0：表单字段的封闭集加第九种 chart（件上一格只读的展示），字段多一格 chart
（{ kind, unit?, from? }：画法封闭五种 bar / hbar / line / pie / donut）。两条数据驱动的路：
显式值由活动写（order.create 的初值、order.write 的补丁），值是图表数据
{ labels, series: [{ name?, values }] }（每条系列与 labels 等长）；派生图写 chart.from，
值从本件那张表格此刻的行现算、数据对象里不存这一格。图表恒为只读（accessOf 对它恒答 read），
不进 rows、不作 decision / deliverable，机检第七查逐条拦（chartIssues 一处判两侧用）。
表的列类型 COLUMN_TYPES 与产出字段 CONTRACT_FIELD_TYPES 一个字都没加——图表不是列、也不是产出。
清单那一侧是放宽：从前跑得起来的八种字段一个字都不用改；活动发出来的那一头没减东西，
老包也收不到任何它解不出来的东西。两条判据都指向小版本。
6.0.0：制品从工单来 + 六格补齐。六条改动，头两条各自就够得上大版本——
- 撤制品卡（产品设计 §1.5、附录 B 31）。
chat.card的卡族去artifact（只剩decision·elicitation），card-reply.kind跟着去一个值，artifactArchivePayload去kind与cardId（只归资料；那一份收严成strictObject，老包照旧递kind: 'artifact'时当场被指名， 而不是把那一格默默丢掉、照type归出一份资料来）。两个封闭集各减一个值：卡族是活动 发出来的那一头（减一个破），card-reply.kind是系统答出去的那一头（加减都破）。 要人认一版草稿的改派验收工单，要人做出一份文件的改派协同工单。 ref值的形状进契约（收窄）。refValueSchema/refIsEmpty/refKeyOf从工作台契约 搬进这里（那一侧经plugin/manifest.ts那一处接缝再导出），checkValue多一支ref： 主键串或{ key, label? }，老写法{ 列: 值 }当场拒并指名。从前它落在default分支上， 活动经order.create/order.write写老写法一路无声——从前跑得起来的包会跑不起来。needs.tables分读写（收窄）。一条可以写成{ address, write?: true }；字符串写法恒为 只读。机检第五查核「write只许标在master.*上」（标在自己声明的表或别的域上都 fail）， 能力面对没标write的外域表拒写并指名。从前靠约定，一次手滑就能让方案侧的包改掉全域 共用的那一行——清单侧的判据同样指向大版本。- 文件格的
archive（加格）。工单定义里file字段多一格archive，指本清单declares.documents[]里一个文档类型的代号：放行成立的那个事务里按那个类型归档， 种类随类型。第七查三条（archiveIssues一处判两侧用）：代号要在本清单声明里、 协同单的deliverable那一格必须标了archive且那一类是制品、非文件格不许标。CAPABILITY_ERRORS加suspended（挂起中调能力面收它，与「这一步已收场」的node-closed分开）——系统答出去的封闭集加一个值，本身就是大版本。 measure.unitFrom（加格）：度量四选一，单位可按行取自另一列（数量列的单位随料走）。- 列
default（加格）：declares.tables[].columns[].default，与主数据那一层的列规格同一格， 落到库上是DEFAULT、落到屏上是新建弹窗的预填；形不合这一列的由机检第五查当场指名。
活动包要跟的：清单 contract 范围改 ^6.0.0；制品卡那一段改成验收单 / 协同单加一格标了
archive 的文件格；写 master.* 的登记类活动把那张表标上 write: true；ref 那几格改成
主键串或 { key, label }。
6.1.0：协同工单 = 制品卡的替代。6.0 落的是「制品从工单来」的前一半（文件格标 archive、
放行即归档），这一版补另一半——复杂制品不再由活动自己做完请人认，而是派一张协同单、
让执行人带着自己的 MCP host 做出来（产品设计 §1.4 / §1.5 / §3.5、系统设计 §3.1 / §3.4、附录 B 43 / 44）。
活动要把这一步交代清楚，所以多两格、多两条机检；加格与加机检，一个封闭集都没减——小版本：
text.prompt（加格）：给 AI 的提示词——执行人的 host 做这一步时喂给它的模型的那段话。 协同单该有（缺了机检警示，不拦激活）；别的类型写了也警示（它不上屏、不进取单答复）。text.references[]（加格）：制品参照与模版{ field, role: 'example' | 'template' }[]。field必须是数据结构里access: read的file字段（机检拦：不是文件格的话 host 拿不到可读的字节，人能改的话活动给的那一版会被当成待填的格改掉）；值由活动在order.create时给（文件库里的一份引用）。- 交付物那一格不许写
multiple（加机检）：只有一个槽，再交即覆盖（件上换一份、 host 里desk.deliver_artifact再交一次都是覆盖，旧的那份留一行工作日志、字节不删）。 多份的话「这一张单的产出是哪一份」在屏上、在 host 里、在放行那一道都答不出来。 - 交付物归到的那个文档类型，
formats要落在DELIVERABLE_FORMATS之内（加机检）：html/markdown/pdf——工作区那一列里渲得开的那三种（产品设计 §3.5「交付物的规格」、 系统设计 §13）。不写formats（不限）也拦：不限意味着 Word / Excel 也收得下。 这个常量住契约包，机检、服务端（件上传与desk.deliver_artifact同一把尺）、前端三处同源。 - 活动可在
order.create时预填交付物槽（自己起的一版草稿当起点）：checkValue对file值照旧判形状，没有新的口子。
活动包要跟的：清单 contract 范围改 ^6.1.0（^6.0.0 照样满足，不改也跑得起来）；
协同单补 text.prompt，要给参照 / 模版的补 text.references[] 并把那几格标成 access: read；
交付物那一格去掉 multiple、它归到的那个文档类型的 formats 收进三种之内。
6.2.0：引用进输入与表格列 · datetime · 主键串的编解码。第六阶段第一个活动
端到端跑通之后撞出来的几格；全是放宽，一个封闭集都没减——小版本：
- 输入 / 产出字段收
ref（CONTRACT_FIELD_TYPES加一个值）：一步的输入常常就是 「哪一条对象」。写成text的时候起单弹窗摆的是一个空输入框，人得自己把主键串背出来， 抄错一个字照样收得下——活动拿它读不到行，屏上是「这一步空跑了一趟」而没有一处说得出为什么。 值的形状与件上那一格同一份（refValueSchema）；字段上写ref指定对象表地址， 那个地址要在needs.tables里且是对象表（机检第五查拦）。 - 表格的内联列收
ref（新封闭集FORM_COLUMN_TYPES= 列类型 +ref）：一张报价行里的 「哪一颗料」就是这一格。从前只能摊成两列文本自己拼回去，拼不回去一个字也不报错。 人保存与放行按refValueSchema判（tableRowGaps一把尺）；列上那个地址归机检第七查。 - 列类型加
datetime（COLUMN_TYPES加一个值）：落库timestamptz，契约里的值是 ISO 8601 带时区的串（checkValue拒光一个YYYY-MM-DD、也拒不带时区的时刻）。date只写得出哪一天；只有它的时候，一件「几点发生的」只剩两条路——截成一天， 或塞进文本列（从此排不了序、比不了大小、数仓认不出它是时间），两条路都不报错。 台账的业务时间time指得到它（一刻本来就含着一天）；屏上按业务时区渲。 encodeRefKey/decodeRefKey（加两个函数）：主键串col=val;col=val的编解码搬进契约包。 从前它只在工作台契约里、活动够不着，于是每个要写引用格的活动自己拼一遍——值里带了;=%的那一条拼出来拆回去就不是原来那一条，而两头都不报错。工作台契约的encodeRecordKey/decodeRecordKey改成从这里单向再导出（接缝只此一处，用例钉）。
活动包要跟的：清单 contract 范围改 ^6.2.0（^6.0.0 / ^6.1.0 照样满足，不改也跑得起来）；
把“哪一条对象”那几格输入从 text 改成 ref 并补上地址；摸成几列文本的引用列合回一格 ref；
要记「哪一刻」的列从 text 改成 datetime；自己拼主键串的改调 encodeRefKey。
6.3.0：输入契约的文本字段可标 multiline。一步要收的常常是一段话——一封邮件的正文、
一段客户口述、一份要人贴进来的原文。件上那一格（declares.orders[].data.fields）早就有这一格，
输入契约（declares.input.fields[]）只有单行那一档：触发弹窗摆的是一个 <input>，人往里贴一段
带换行的正文，框里只看得见最后一行，而换行还在不在值里屏上答不出来。换一个要人贴一段正文起单的
活动都会撞到，所以它是系统的一格。
inputFieldSchema 多一格可选的 multiline（只 text 有，写在别的类型上机检当场指名，
措辞与件上那一格逐字一样——refineMultiline 一把尺两处用）；两处触发弹窗（单活动节点的、实践的）
对标了这一格的文本字段渲多行框，值仍是字符串。
放宽，走小版本：清单那一侧多一格可选属性，从前跑得起来的包一个字都不用改；活动发出来的
那几张封闭集（CAPABILITIES / SYSTEM_EVENTS / CAPABILITY_ERRORS）一个值都没动，老包收不到
任何它解不出来的东西。活动包要跟的：清单 contract 范围改 ^6.3.0（^6.x 的老范围照样满足，
不改也跑得起来）；要人贴一段正文的那几格输入补上 "multiline": true。
6.4.0：声明的表可以标人读名列 nameColumn。屏上一律印人读名、不印键（产品设计 §7.3）：
引到别的表的列、台账的挂靠列，印的是目标那一行的名字（「华芯智能」「人民币」），键降成小字。
哪一列是名只有表的定义者答得出，所以它是声明里的一格：declares.tables[].nameColumn 指本表
columns 里的一列，且是文本或枚举列（一个数字、一个日期当不了「这一行叫什么」）。
台账不必标——一笔账的身份是「哪一天、哪几个键」，没有「它叫什么」。
主数据那一层的人读名列由系统清单给（master.party 是 name、master.part 是 mpn……），
活动引用它们时什么都不用做。
放宽，走小版本：清单那一侧多一格可选属性，从前跑得起来的包一个字都不用改——对象表没标只提示
不拦（机检 warn），只是引到它的列在屏上退回印键。活动包要跟的：清单 contract 范围改 ^6.4.0
（^6.x 的老范围照样满足，不改也跑得起来）；每张对象表标上 "nameColumn": "<哪一列是名>"。
7.0.0：工单落定——落业务库只有工单提交一个入口（产品设计 §1.4 / §1.5、系统设计 §2.8 /
§3 / §4.5、附录 B 6 / 45 / 47 / 49）。一句话：业务库的写从能力面挪进了工单定义的 commit。
几条改动里任何一条单独就够得上大版本——
- 业务数据名词只剩读（封闭集减四个值）：撤
ledger.append·ledger.reverse·object.upsert·artifact.archive。活动对业务库只读；要落的东西摆进工单的数据对象、在数据 表单的commit里声明落到哪，人提交、系统在同一个事务里落账、办结、冻结、归档并盖章 （任务、节点、工单、提交人、时刻）。归档同理随落定走（文件格的archive），没有单独的归档动作。 - 对话区没有卡（封闭集再减）：撤
chat.card与两张卡的形状、撤事件card-reply。 要人拿个主意、补几格信息，派一张一两格的执行工单——它有表单、有复核、有冻结、记得到人。 对象的新建同理只从工单落定来，所以NODE_RUN_STATES也去掉了awaiting-object。 - 事件加两种（系统答出去的封闭集加值，同样破）：
work-order-saved（表单声明了recheckOnSave的单被人保存了一次，请活动复核一遍）、work-order-mail（沟通工单收到一封回信）。 work-order-reply多两格：landing（落账摘要，恒有；不写业务库的单与「重做」是{ items: [] }）与by（提交人{ id, name }）。活动交出时要带回去的需求号、客户代号从 摘要里取——回头去库里捞一遍的话，捞到的可能是别人同时落下的那一行。- 工单定义 = 数据表单四段 + 一块类型拓展（清单侧收窄）：
data·interaction·commit·text四段讲的都是数据对象，四种单共用；这一种单特有的东西写在以类型命名的 那个键下——执行guide· 验收acceptance· 协同artifact（必有）· 沟通communication（必有）。顶层的deliverable挪进artifact.slot，text里的guide/standard/criteria/matters/prompt/references与interaction.decision各归各位，text只剩brief·sections·fields。写了不属于本类型的那一块、一份定义写了两块，机检 fail。 interaction加两格：requiredWhen（带条件的必填——「结论选了退回则原因必填」）与recheckOnSave。- 两侧共用的纯函数进契约：
evalCondition·accessAt/missingOf·planCommit/summarizePlan·formatSerial·mailDraftOf/mailDraftIssues。件上、宿主、服务端三处要 同一个答案，各写一遍必然有一天不一样——而那一天，人是照着预告点的提交。 - 顺带：
table.read的orderBy收数组（至多四列）；chat.say可带一张本步派过的工单 （屏上多一枚「打开工单」）；order.read的done收成有形状的办结段（带landing），沟通单 另带mails；导出FORMAT_EXTENSIONS/formatOfFileName（档次与扩展名一把尺）。
活动包要跟的：清单 contract 范围改 ^7.0.0；每一处 cap.append / cap.upsert /
cap.reverse / cap.archive 都改成一条 commit 落账项（值先摆进件上一格只读的格，人看得见）；
发卡的那几处改派轻工单；text 里那六格与 deliverable 挪进各自的类型拓展；读 work-order-reply
的地方改从 landing 里取键。SDK 同版（@bpos/activity-sdk 7.0.0），信封多一格业务时区
（Envelope.timezone，缺席答 'UTC'，配一个 dayIn(zone, at)）。
7.1.0：落账项落得进「同域的表」 —— 机检那一句放宽到设计的口径（系统设计 §8.2、§3.8；
附录 B 27）。从前这一道要求落账项的 table 在本清单 declares.tables 里，而落定那一道
（server/src/modules/desk/landing.ts::writableAt）判的是域相同：一个活动拆成两包时，
第二包写的正是第一包建的那张表——两包在同一个域里、本来就是同一件事的两段。两句话不一样的代价是
装得上、机检全绿的包在人按下提交的那一刻被拒，而那时候人已经把一张单填完了。
写得了的从此是：同域的表（本清单声明的，或同域别的活动建的）与在 needs.tables 里标了
write: true 的主数据表；别的域的表永远只读，一个字都没放松。域从本清单声明的表推
（清单里没有子系统代号），一张表都不声明的活动因此只剩主数据那一档。
放宽，走小版本：机检少拦一种清单，从前跑得起来的包一个字都不用改，一条新 warn 也没有；
封闭集、载荷、答复形状一律没动，老包收不到任何它解不出来的东西。活动包要跟的：没有——要用这一档
（落账到同域别的活动建的表）的包，清单 contract 范围写 ^7.1.0。
8.0.0：业务库四层——对象 · 单据 · 台账 · 文档（产品设计 §1.4；系统设计 §3.8 / §6.1 / §8.2；
附录 B 53 · 54 · 56）。从前叫 ledger 的「只增不改的事实行」整体改叫 voucher（单据），
ledger 换成新语义 「按主键一行的状态」。八条改动，头两条各自就够得上大版本：
TABLE_KINDS三个值（object·voucher·ledger）：一个封闭集改了一个值的含义—— 照 7.x 写的包声明kind: 'ledger'的表在 8.0 里是另一种东西，数仓按kind = 'ledger'建事实表 会建错。这一条单独就是大版本。COMMIT_ACTIONS五个值：加post（过账：按主键找到那一行，没有就建；set置值、add/sub增减，一句里原子地做）。动作配得上种类三分：对象create/update、 单据append/reverse、台账post——7.x 的「append/reverse落到ledger上」 在 8.0 里是一条 fail。- 落账项加
add/sub（只在post项里；同一列在set/add/sub里至多一次； 目标是数值列、来源是数值），并加一条 无单据不过账：有post的表单至少有一项append或reverse。 set改成可缺：落账只写例外，没写的列按同名直落解（§3.8）——7.x 那句「至少写一格」 逼着作者把一个本来解得出来的列再抄一遍，而抄错一个字就是一条静静落错的列。- 声明多三格：单据的
source: { kind, no }（源单那两列，都是本表的文本列）、台账数值列上的nonNegative，以及挂靠attachedTo的三种情形——单体挂单头（必填）· 单头挂一张对象表（可不挂）· 台账挂一张对象表或单据表（必挂）；谁都不许挂到台账上。time与source只属于单据，nonNegative只属于台账的数值列，nameColumn对象表该写 · 单据表可写可不写 · 台账不许写 （6.4.0 那句「台账不必标」在 8.0 里成了一条 fail）。 - 引用的目标放宽到单据表：件上的
ref、输入 / 产出的ref、表格内联的ref列都指得到 对象表与单据表（挑一条对象，或挑一张源单）；台账仍不作引用与挂靠的目标——一行状态不是身份。 表上的refs注解没放宽：它的目标只有对象表，单据之间靠source连。 ref来源的column改成可缺：不带就是整把主键串（记源单号那一列用的就是它）； 它是一串字，所以只落得进文本列。- 顺带：
parseAddresses认全角的分号与逗号（中文输入法下打出来的就是它们；不认的话整串 当成一个地址，屏上那一句「这几个不成形」指着人打对了的那一串）。
破坏性，走大版本：一个封闭集换了一个值的含义、另一个封闭集加了值且动作与种类的对应收紧、
两条新 fail（台账标 nameColumn、台账写 time）——7.x 里声明了表的包装进 8.0 的系统会被机检点名。
活动包要跟的：清单 contract 范围改 ^8.0.0；把当事实行用的 kind: 'ledger' 改成 'voucher'；
台账上的 nameColumn 与 time 撤掉；要过账的表单补 post 项与 add / sub，并确保同一张单里
记了单据。SDK 同版（@bpos/activity-sdk 8.0.0）。
8.1.0:表单结构加「怎么摆」四样(系统设计 §3.2 / §3.3 / §3.5 / §3.7)。节多两格 role
(context 参考 / input 填写 / verdict 结论)与 columns(1 / 2 / 3);格多一格 span
(1 / 2 / full);列多两格 width(narrow / normal / wide)与 primary(主列:表比栏宽、降成
一行一张卡时它做标题);图多一格 top(只画前几项)。件跑在一条窄栏里,结构里不说怎么摆,
视图只能按内容猜——猜出来的就是一列长说明把旁边四列挤到一个字宽、二十四根柱糊成一团。
只加不减,走小版本:全是可选格,老包一个字不改照旧装得上;清单侧只放宽不收窄。
活动包要跟的:没有——要用这几格的包把 contract 范围写 ^8.1.0。
8.2.0:制单体验四样 + 台账不作目标(产品设计 §1.5 · §3.2;系统设计 §3.2 / §3.3 /
§3.6 / §3.7 / §4.4 / §6.1;dev/活动地基审核-ERP模型.md §七 裁定 1 · 4 · 7)。
拿一家供应链贸易公司的常规 ERP 逐环对表撞出来的五条,都是只加不减:
- 算格
calc(CALC_KINDS封闭两种product/sum,可带scale,缺省 2 上限 6)。 落账模式是声明不是脚本,件上的算格是唯一的例外:行金额 = 数量 × 单价、单据合计 = Σ 行金额这一类制单时当场要看见的算术。恒为只读——人改不了;活动经order.write替它定一个别的数即拒并指名,而原样回显系统算出来的那个数不算写(活动为了留住人加的行 必须整张表读回再写回,逼它逐格剥掉等于给每个活动都留一份税)。一只纯函数evalCalc(form, data)凡写进库的那一刻都算(派单、活动写、人保存、落定;件与预告各算各的,同一只), 所以人看到的就是将要落的。乘一层、不嵌套;合计的操作数可以是算格; 任一操作数空着算格为空(不当 0)。 - 值域
range({ min?, max? },数值格与数值列)。件上那一道从前只判必填、类型、取值集、 行数:数量填成负数、税率填成 3 一路无声地落进库,而活动只能在recheckOnSave里写一句 不是闸的意见。越界与缺口同一把尺(rangeGap一处算),pointer指得到表格里那一格。 - 引用的筛选
ref.where(REF_WHERE_OPS封闭三个eq/ne/in,条与条之间是与)。ref: master.party从前列的是全部往来单位,挑供应商时客户、货代、报关行都在里面。 件上的选择器与落定那一道都按它走(bpos:lookup的载荷多一格where)。 default真的生效:从前谁都不判它——写一个取值集之外的枚举,清单装得进、机检七行全绿, 错要等到派单那一刻由valueGaps说。8.2 起机检提前拦,而那把尺就是派单那一把 (见下面「机检那把尺怎么定」):表格字段的缺省是一组行、图表那一格是一份图表数据,照旧收得下。 表格的列也收default(「加一行」按它预填)。- 台账不作目标:
declares.input.target指到台账机检第五查拦(refs与attachedTo两处早就有这道闸)。一行状态不是身份,而起单那一刻系统只按主键核那一行在不在。
只加不减,走小版本:全是可选格与新拦的路,从前跑得起来的包一个字都不用改
——目标指到台账的包从前也起不了单(起单那一刻核的是对象 / 单据表)。封闭集只加不减,
活动发出来的那一头没动,老包收不到任何它解不出来的东西。
活动包要跟的:没有;要用这几格的包把 contract 范围写 ^8.2.0。
机检那把尺怎么定:拦的是「运行时必拒的」,提前到装包。default 这一格就是靠它守住小版本的
——另写一套判据(比如「只收标量」)会比运行时严:表格字段的缺省是一组行、图表那一格是
一份图表数据,两样在 order.create 里都收得下,8.1 里真跑得起来;拦掉它们按上面那把尺
(「从前跑得起来的包会不会跑不起来」)就是大版本。所以 defaultIssues 不另写一套,
它问的是派单那一刻同一句(checkValue / tableRowGaps):派单时收得下的机检就不拦,
派单时必拒的机检提前说。这条原则对以后每一次「把运行时的判据提前到机检」都成立。
8.3.0:地基四条(系统设计 §3.2 · §3.8;说明书 §11;activities/procurement-chain/README.md
末尾那五条撞出来的)。照一家供应链贸易公司的采购六环(询价 → 报价 → 订单 → 入库 → 发票 → 付款)
写一条真的实践链时撞出来的,都是只加不减:
- 主数据那一层的形状随契约包走(
MASTER_TABLES·masterRegistry(),一处现算)。master.*十三张表的列、主键、挂靠、引用、人读名列从前只住在 server 里,而活动包是在仓外 打的——build.ts拿机检四把尺自检时连不上任何一台实例,于是attachedTo: master.*带进来的 挂靠列一条都解不出:omit它被判「那张表没有这一列」,不omit又会在激活那一刻凭空多出一格 没摆进任何一节的字段,两句话指的都不是真原因。机检四把尺没收到登记时按契约包这一份解master.*;收到了就按收到的那一份(服务端递的那一份里本来就有这十三张,还带着管理者后来 加的列)。server 那一侧(建表、登记、开机自检)读的就是这一份,不另抄一遍。 - 补格
augment(顶层data.augment[]与表格字段的augment[],同一组格:range·calc·where·default)。取形解出来的格,名、类型、取值集、单位、人读名与说明 都从列上来——那是表声明答得出的全部;件上还有四样只属于这一张单的,从前只写得进data.fields里自己写的那一格,于是要给取形来的某一列加一道值域,只能把它omit出来再写 一格同名的,同一列的形状因此在清单里存了两份。表格那一侧更重:columns一写就整个盖掉shape,一张要算行金额的单体表格只能全写内联列。补格只加不改:改不了类型、改不了名字、 不与omit同时指同一列,补的那一格解不出来机检指名。人读名与访问档不收 ——text.fields与interaction.access/interaction.rows本来就够得着取形解出的格 (定形之后那几格就在data.fields里,按名字对),再收一份的话「哪一处赢」只有读代码才答得出来。columns写了就整个盖掉shape这一条语义一个字都没变。 serial的日期段认取形解出来的那一格。commitIssues里field/ref两种来源在 「取形还没解」时早就走 warn(判不了),只有serial.date.field是硬 fail——于是 「单号按归期分段」这条最常见的 ERP 编号规则,要么把归期那一列omit出来自己写一格, 要么放弃日期段。补成同一副。- 台账上「一格引用盖两列」解得出来(第 1 条的推论,不是另一处代码)。
refs → master.part盖着mpn+maker,件上合成一格;落账到以mpn+maker为键的台账时maker本该由同名直落第 2 条「引用」解出来,而那一条要先认得出这张表上的线——线要目标表的形状。 主数据进了契约包,仓外打包那一刻也解得出来,post项因此不必再逐格写{ ref, column }。
只加不减,走小版本:全是可选格与新解得出来的东西,从前跑得起来的包一个字都不用改
——主数据那一层的形状从前在激活那一刻本来就解得出(服务端有登记),这一版只是把同一个答案
提前到仓外;新报的那几条(补格补错了、ref 取的不是目标表的主键列)拦的都是激活那一刻本来
就会被拒的包。封闭集只加不减,活动发出来的那一头没动。
活动包要跟的:没有;要用补格的包把 contract 范围写 ^8.3.0。
8.4.0:两条,都是范例链拆绕法时剩下的(系统设计 §3.2;手册 §3.5.1 · §3.7)。都是只加不减:
- 表格字段的
shape也收omit(与顶层同形:"<表地址>"或{ table, omit? }, 同一只resolveOne、同一套点名)。顶层从 8.0 起就有omit——系统发的单号、落账给成常量的 那几列不上件;表格那一侧只收一个表地址,于是单体表上那几列系统或活动给、人不填的 (行号由落账的rowIndex给、源单种类由落账给成常量)照样解成列,只能排在rows.edit之外 当只读列摆着——件上横着几格人改不动、也看不出所以然的列,宽度还都占着。 「摆着」与「不上件」是两件事,而 8.4 之前只有前一件写得出来。 表格那一格比顶层多一道:行的身份keys不许指到不上件的列(在omit里、被一条 引用盖着当非锚列、或取形根本没解出来)——件上每一行都会被判「主键列空着」 (modules/desk/orders.ts),而那一列根本不在件上:人对着一张单,红带指着一格他看不见的列, 保存不了、提交不了,也没有一处说得出为什么。 registryOfManifests(manifests):几份清单的declares.tables折成一份TableRegistry(与masterRegistry()并成一份)。活动包是在仓外打的,8.3 之后手上有形状的是本清单与master.*;挂靠到同一子系统里别的包声明的那张表仍解不出它的主键,挂靠列因此一条都带不进来 ——采购链的procurement.payable挂在pc-invoice声明的发票单据表上,invoice_no就撞在这里, 当时只剩一条规矩:把那一列照原样写进columns,同一张表的形状在两个包里各存一份。 可一条单据流本来就是拆开的几个包(报价 · 订单 · 收货 · 发票 · 付款),而它们本来就摆在同一个 父目录下。build.ts的范本因此加一步:按BPOS_SIBLING_MANIFESTS(几份清单的路径,逗号分)或 自动扫同一父目录下兄弟包的bpos-activity.json,折成登记递给四把尺;一个兄弟都没有时不递 ——那一档与 8.3 逐字一样。同一个地址两份清单都声明时要逐字相同(键序也算),不同即当场抛 并指名是哪个地址、哪两份清单:折出一份登记时只能挑一个,静静挑一个的话两个包各自机检全绿, 装到实例上才有一个按另一份形状对不上。(这一条落地的那一刻就抓住了pc-invoice与pc-pay两份procurement.payable声明的分叉。)
只加不减,走小版本:表格的 shape 从一个地址放宽成「地址或 { table, omit? }」,
老写法一个字都不用改;registryOfManifests 是新导出的一只函数,谁都不必调它。
封闭集一个值都没动,活动发出来的那一头没动,老包收不到任何它解不出来的东西。
新报的那两条——keys 指到不上件的列、两份清单同一地址声明得不一样——按「从前跑得起来的包会不会
跑不起来」这把尺都是不破:前者的包装得上、激活得了,可件上每一行都判不过,从来没有一个包靠它
跑起来过;后者只在一起 build 时才判得到,而一起 build 这件事本身是这一版才有的。
活动包要跟的:没有;要用这两样的包把 contract 范围写 ^8.4.0,build.ts 照范本
(activities/procurement-chain/*/build.ts)加那一步。
8.4.1:纯结构重构,契约面一个字没动(系统设计 §3.9 末段的裁定「种类是基类上的拓展,只加不改」)。
四种工单各自那一块的形状与机检搬进了 src/kinds/{execute,accept,collaborate,communicate}.ts,
src/kinds/index.ts 是模块登记表;ORDER_KINDS · orderKindSchema · ORDER_KIND_LABEL ·
ORDER_KIND_NAME · ORDER_EXTENSION_OF_KIND · ORDER_EXTENSION_KEYS 从登记表现算,
导出名与值一字不变。几片共用的小零件(列名、字段级三档与「这一格是不是只读」、判据 / 事项 / 参照 / 信)
下沉到 src/atoms.ts,manifest.ts 原样再导出——从 @bpos/activity-contract 引任何名字的地方
一个字都不必改。撤掉的只有三只内部 refine 包装(refineOrderArtifact / refineOrderReferences /
refineOrderCommunication),合成登记表那一道 refineOrderKinds;仓内仓外都没有人调它们。
新导出的那几只是模块自己的手(kindModule · kindModuleOf · ORDER_KIND_MODULES ·
artifactOf / acceptanceOf / guideOf / communicationOf · decisionFieldOf · slotFieldOf ·
mailFieldsOf · viewFormExtrasOf(件上那几枚小签:槽与参照 / 模版;9.0.0 起改名 viewCellTagsOf,见下;
8.4.1 里它叫 viewFormExtrasOf、答的是「init 的 form 多出来的那一格」,视图协议换成渲染模型之后
它答的是「哪一格标什么」——形状随之改,没有活动包调它) · MAIL_ORDER_KINDS · COLLAB_DESK_KINDS)——
系统那一侧按种类分叉的地方从此只经它们,两道扫真实源码的用例(server/tests/kind-modules.test.ts ·
web/src/features/desk-task/internal/kinds/literals.test.ts)钉着。
走补丁版:封闭集一个值都没动、形状一格都没动、拒绝的话一个字都没改,老包收不到任何新东西;
活动包要跟的:没有。
协同模块的 viewFormExtrasOf 改名 viewCellTagsOf(答「哪一格标什么」,取值集 VIEW_CELL_TAGS;投影从此不认识哪一种单多哪一格)——导出面撤一个名字、随本版发出;活动包不调它,不影响清单。
9.0.0:台账的每一个数都出自本次落定写下(或冲销)的单据行(产品设计 §1.7「台账只随单据变」;
系统设计 §3.8「机检」)。从前「无单据不过账」只要求同一张单里至少记了一张单据,管不了过账那个数
打哪儿来:add / sub 取得了件上任意一格,于是一本账随件走而不是随单据走
——账上那一笔对不回任何一行单据,而一本对不回去的账比一本错账更难查。两条改动:
- 机检第七查多一道(定义是静态的,机检够了,落定那一道不必再判)。对每一条
post项,add/sub的每个来源、以及set里除台账主键列之外的每个来源(写明的与同名直落解出的 过同一把尺——只判写明的话,把那一格删掉让同名直落去解就绕过去了,而绕过去的那一版落进库的 是同一个数):column要有一项append以同一张表格为行来源且那一列落进了它;field要落进某一项顶层一行的append;from指的那一项要是append或reverse。value(常量) ·serial·submittedAt/submittedBy·ref(+column,引用格的主键段) 不受此限——它们不是「账上的一笔数」,是号、时刻、人与一个写死的步长;台账主键列的set也不受此限:它是这一行的身份。另加一条:rowIndex不许进add/sub(行号答的是件上 那张表格的第几行,把它加进一本账等于让账随「这一行摆在第几位」变)——这一条只看定义就判得了, 清单那把 zod 也拦。 from指得到reverse项:落定引擎里冲销那一项找到并锁住了那一行,把它的列 暴露给后面的项,与append写下的那一行同一副读法。红冲那张单因此这么写: 顶层一行reverse冲掉单头,再post从{ from: <冲销项>, column: … }取数反着过账 ——取的是库里那一行的真值,而不是活动上一次读库读到、摆在件上的那个数 (两者差多少,从前两边都不会报错)。
清单侧收窄,走大版本:按「从前跑得起来的包会不会跑不起来」这把尺——会。
一份把 add 取自件上某一格的旧包,从前装得上、跑得起来,9.0 的机检当场拦下并点名。
仓里的包都跟了:采购链的 payment-void 从「按件上那张表格每行一笔」改成「整单级、数从冲销项取」,
走查夹具多一张单头单据 walk.probe_run(顶层一行的过账要有一张顶层一行的单据)。
活动包要跟的:逐条核一遍 post 项,改法优先「让那个数落在单据行上」(把它写进记单据那一项的
某一列),而不是删掉过账;红冲那几张改成 from 指冲销项。contract 范围写 ^9.0.0。
9.2.0:作业指导书的步与验收判据的条钉在件上(产品设计 §3.2「件上的注」,系统设计 §3.7 / §3.9)。
guide.steps[] 每一步收一句话,或 { text, at? };acceptance.criteria[] 多一格 at?。
at 是一节的 id 或一个顶层字段名(表格的列不作锚点:一行高 40px,一条注钉上去要么把行撑开、
要么盖住相邻的格;要指一列就指那张表格本身)。件把步渲在那一节 / 那一格之上、把条渲在之下,
条上另摆活动的判定章;没写 at 的在件顶,standard 在件尾。签核的勾不进件——那是担责的那一下,
由宿主渲在件右侧的签核栏、按件报的位置与那一条对齐(定义者 2026-09-21 裁定)。
从前这几样摆在件上面那一张「处理区」卡里:人一边照着第 3 步做,一边要在下面二十格里找它说的是 哪一格;十几条判据与它们各自判的那一格隔着一整块。
机检核锚点并点名:at 指不到、或指到一张表格里的列名、或一个名字同时是节 id 与字段名,都当场
fail 并把这张单上挂得住注的地方全列出来。不拦的话那一条会悄悄跑到件顶、照样印得出来、照样签得了,
只是不在它该在的那一格旁,而屏上一处报错都没有。
只加一格可选的,走小版本:按「从前跑得起来的包会不会跑不起来」这把尺——不会
(一步写成一句话的旧包一个字都不必改,没写 at 的注钉在件顶)。活动包要跟的:没有;要把步与条
钉到格旁的,给它们补一个 at 就是了。contract 范围照旧写 ^9.0.0。
视图协议另走一版(它自己计版):件上多了「注」这一格、桥多了 bpos:anchors / bpos:goto 两条,
默认通用视图的自述递到 3;按 2 写的视图文件装不进来——条文只在件上印得出来,而它读不到那一格。
9.1.0:表格分大表与小表(产品设计 §3.2「件」,系统设计 §3.2 big 那一行与 §3.7)。
表格字段多一格可选的 big: { rows }(2 – 50):卡内固定展示 rows 行、超过的在卡内上下滚、
列头钉在滚动区顶上,卡头另出一个筛选框(按这张表每一列屏上印的样子字面匹配、大小写不敏感)
与列头排序(点一次升、再点降、再点还原;数按数比、日期按日期比、其余按屏上印的串 localeCompare('zh-CN')),
卡头常驻「共 N 行 · 筛出 M 行」。不写是小表——与 9.0 逐字一样:行全摆开、不筛不排。
从前只有小表那一档,于是一张芯片 BOM 的报价单在件那条窄栏里独占几千像素,人要找一颗料只能一路滚。
只说怎么摆(与 span · width · primary · top 同一档):筛与排都是看法——
不改数据对象里行的次序、不改保存与落账的内容,筛掉的行照样在、照样落;编辑态里筛着也改得了行
(件上输入框绑的仍是原行下标字段[原下标].列,所以 bpos:point 指得到、保存送的仍是整份原次序),
新加的行落在最后并立刻可见,加删改仍按主键比。它因此一格都不碰 missingOf / evalCalc / tableRowGaps。
只加一格可选的,走小版本:按「从前跑得起来的包会不会跑不起来」这把尺——不会
(不写这一格的包一个字都不必改,屏上也逐字一样)。同一次撤掉的只有视图那一侧的一样东西:
默认通用视图表格卡上那个「表格 / 图表」开关(它是视图层的看法,从来不在契约里、不在数据里)——
要看图就声明派生图(chart.from)。活动包要跟的:没有;明细行上百的那几张表标一格
big: { rows: … } 就是了。contract 范围照旧写 ^9.0.0(9.1 只加了一格可选的)。
9.3.0:大表的起用行数(产品设计 §3.2「件」,系统设计 §3.2 big 那一行 · §3.7 · §5.6)。
big 多一格可选的 from:行数到了它才按大表摆,不到就按小表摆开
("big": { "rows": 8, "from": 21 } —— 一张 BOM 二十个料号以内摆开看,二十一个起才收成大表)。
不写 from 仍是恒按大表,9.1 那一档一个字不变。机检 from > rows:不大于 rows 的起用行数
写不通——到线那一刻卡里正好摆得下全部行,滚动区是空的,这一格等于没写。
从前 big 是一句恒成立的话,于是同一格表格要么永远收成大表(三五行的单据只摆了半张卡、
上面还挂着一个筛不出什么的筛选框),要么永远摆开(几十行的 BOM 独占几千像素)。
一张单的行数本来就随这一次的业务变,摆法该跟着它变。
这一判在投影里做,不在契约里、也不在件里(§5.6):宿主那只纯函数按投影那一刻这张表的行数
解出是大表还是小表,解完只把 { rows } 递给件——from 不进渲染模型。所以编辑中加过了线不当场切,
下一次打开再算;冻结件重渲按冻下的那一份数据算,与办结时看到的一致。件自己数的话,同一份数据
在两份视图里摆得不一样,而屏上一处报错都没有。
只加一格可选的,走小版本:按「从前跑得起来的包会不会跑不起来」这把尺——不会
(不写 from 的包一个字都不必改,屏上也逐字一样)。活动包要跟的:没有;行数随这一次的业务
大起大落的那几张表(BOM、明细)标上 from 就是了。contract 范围照旧写 ^9.0.0。
机检加一条 warn 也算改了清单侧的尺子：包的 build.ts 要求 0 warn（一份自己都不干净的清单不该打成包），
所以一条新 warn 会让一个字都没改的包当场红——6.4.0 的 nameColumn 就这样撞红过 A1 1.1.0。
升版的那条车道因此要把仓里已有的包各 build 一遍（活动仓 BPOS-Activity/ 的与本仓 activities/ 的），
撞红的那几个包一并改到：这是升版自己的尾，收不掉就别升。
拒绝
业务上的拒绝用 HTTP 200 承载（ok: false + error + message + hint）——它不是传输错误，
是系统对这次调用的回答，活动要读得到才知道下一步做什么。真正的 4xx 只有两种：
令牌不对 401、这一步已交出或这一单已挂起 409。码是封闭集，见 CAPABILITY_ERRORS。
Dependencies
Dependencies
| ID | Version |
|---|---|
| zod | 4.4.3 |
Development Dependencies
| ID | Version |
|---|---|
| @types/node | ^24.0.0 |
| tsx | ^4.19.0 |
| typescript | ^5.6.0 |