@bpos/activity-contract (6.0.0)
Installation
@bpos:registry=https://gitea.akhr-ai.com/api/packages/ChaiHao/npm/npm install @bpos/activity-contract@6.0.0"@bpos/activity-contract": "6.0.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 / deliverableIssues / chartIssues / archiveIssues），以及件上 ref 那一格的值形状（refValueSchema / refIsEmpty / refKeyOf） |
| 不在这里的 | — | 实践的图（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 · card-reply · human-say · timer · control · handoff-refused
（现算一份在 SYSTEM_EVENTS）。
每条带 id、按本任务节点内的先后顺序投、至少送到一次——活动用自己的实例状态去重，
系统不重放（§6.2）。每种事件的来处见 SYSTEM_EVENT_SOURCE：发出去的每一个口对着一条回来的路。
名词
工单 4（create · read · write · void）· 对话 3（say · card · input）· 模型 1 ·
业务数据 5（table.read · ledger.append · ledger.reverse · object.upsert · artifact.archive）·
工作持久 4（state · memory 各两个）· 文件 4（get · text · put · info）· 定时 1 · 本步读数 1
（现算一份在 CAPABILITIES）。
卡只有两种（决策 / 补格）：制品卡 6.0 撤了——制品从工单来（产品设计 §1.5），
要人认一版草稿的派验收工单，要人做出一份文件的派协同工单，件上标了 archive 的文件格
在放行成立的那个事务里归档。artifact.archive 因此只剩资料一档。
审批不在里面：活动不声明审批、不知道审批、收不到裁决。 邮箱也不在里面：信箱只服务系统的事件规则（监听一个信箱、命中条件就起一单）， 起单之后活动与那封信再无关系——活动既不发信、也不收信。 对象新建卡也不在里面：那是系统触发活动时的副作用，人答完系统自己建对象。
什么改动要升大版本
往 CAPABILITIES / SYSTEM_EVENTS / CAPABILITY_ERRORS 这几个封闭集里减一个值，
对已经打好的活动包是破坏性的——那些包把旧的枚举内联进了 dist/activity.mjs。加一个值
破不破，看这个值从哪一头来：系统答出去的（一种事件、一个拒绝码）加了就破——老包拒收并报
「系统答的形状不对」，而毛病在系统；活动发出来的（一个能力名词）加了不破——老包不认识它，
也永远不会收到它。破坏性的走大版本，其余走小版本。
往事件载荷里加一个字段同样不破（zod 对象默认非严格，多的字段被忽略），走小版本。
分界线不是「改没改契约」，是「老包会不会收到一个它解不出来的东西」——看的是活动包内联的那一份。
清单那一侧收窄不按这条走：清单不在活动包内联校验的那条线上（manifestSchema 是系统在装包那一刻用的尺子），
所以判据换成一条：收窄之后从前跑得起来的包会不会跑不起来。会 → 大版本；
只是把一个本来就用不成的值提前拦下来（拦点从下游挪到机检，并说得更清楚）→ 小版本。
icon 收进图标调色板走的就是后者：调色板外的值从前装得进、机检还全绿，可它建不出活动类型来（建类型 422），
从来没有一个包靠它跑起来过。
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 }。
拒绝
业务上的拒绝用 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 |