dsh-workplan 1.8.18 → 1.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,116 @@
1
+ /**
2
+ * [W1] 覆盖摘要:`supersededBy.mapping` 的规范化摘要(canonical mapping digest)。
3
+ *
4
+ * 规则依据(落盘文档,不在本文件重复全文):
5
+ * - `_rerun_20261101/GATE_rule_design.md` §6.1:`"digest": "sha256(canonical(mapping))"`;
6
+ * §6.3:present 时「复验必须从日志重算,不读缓存数值;digest 不一致即 stale」;
7
+ * §7.2 第 6 条:运行时复算 `coverage==='full'`,写入 `digest`。
8
+ * - `_rerun_20261101/GATE_case_matrix.md:158`(W1):规范化口径固定为
9
+ * 「sort_keys + 紧凑分隔符 + 仅 mapping 的 JSON」。
10
+ *
11
+ * 本模块把 W1 那一行「补一行规范化定义」落成可执行契约:
12
+ *
13
+ * 1. 输入对象:`supersededBy.mapping` —— 映射数组本身,不含
14
+ * `supersededBy` 包装层(planId / coverage / verifiedAt 等不参与摘要)。
15
+ * 数组元素按**存储原样**参与摘要:`from`/`to`/`basis`/`evidence` 若存在
16
+ * 则全部计入(与 T9 `gate_rule_check.py::mapping_digest` 同口径,
17
+ * 该脚本的合成用例已用同一算法产出并自校验 `sha256:a686…`)。
18
+ * 2. 规范化:JSON,对象键按 Unicode 码位升序(sort_keys),分隔符为
19
+ * `,`/`:`(无空白),字符串不转义为非 ASCII(UTF-8),数组顺序保持
20
+ * 存储顺序(不排序)。
21
+ * 3. 摘要:`sha256:<64 位小写十六进制>`,对规范化文本的 UTF-8 字节取
22
+ * SHA-256。
23
+ * 4. 失败语义:`verifyMappingDigest` 只在「mapping 是数组、digest 形如
24
+ * `sha256:<64hex>`、且重算值逐字符相等」时返回 true;其余(缺字段、
25
+ * 类型不对、被改动)一律 false —— 调用方据此 fail-closed(stale),
26
+ * 不允许把「无法复核」当成「通过」。
27
+ *
28
+ * 语义边界:摘要只证明「存下来的 mapping 没被改动」,**不**证明「两项工作
29
+ * 在语义上等价」。等价是人的判断,只能靠用户确认(V8)与审计留痕承载,
30
+ * 与 `GATE_rule_design.md` §6.1 末尾的边界声明一致。
31
+ *
32
+ * 约定:写入方(host 工具层)必须先对本模块产出的 digest 落盘,再写 durable
33
+ * 信封;读取方(replay / present 复验)只重算、不信任缓存值。
34
+ */
35
+ import { createHash } from 'node:crypto'
36
+
37
+ export const MAPPING_DIGEST_PREFIX = 'sha256:'
38
+
39
+ const MAPPING_DIGEST_RE = /^sha256:[0-9a-f]{64}$/
40
+
41
+ /**
42
+ * 规范化 JSON:对象键按码位排序、紧凑分隔符、无 ASCII 转义。
43
+ *
44
+ * 与 Python `json.dumps(value, ensure_ascii=False, sort_keys=True,
45
+ * separators=(',', ':'))` 对齐(T9 脚本即用该实现固化 W1 口径)。
46
+ * `undefined`/函数/符号与 `JSON.stringify` 一致:对象里省略、数组里变 `null`。
47
+ */
48
+ export function canonicalMappingJson(value: unknown): string {
49
+ if (value === null) return 'null'
50
+ const type = typeof value
51
+ if (type === 'string') return JSON.stringify(value)
52
+ if (type === 'number' || type === 'boolean') return JSON.stringify(value)
53
+ if (type === 'bigint') return JSON.stringify(String(value))
54
+ if (type !== 'object') return 'null'
55
+ if (Array.isArray(value)) {
56
+ return `[${value.map((item) => canonicalMappingJson(item)).join(',')}]`
57
+ }
58
+ const record = value as Record<string, unknown>
59
+ const keys = Object.keys(record)
60
+ .filter((key) => record[key] !== undefined && typeof record[key] !== 'function' && typeof record[key] !== 'symbol')
61
+ .sort(compareCodePoints)
62
+ const body = keys.map((key) => `${JSON.stringify(key)}:${canonicalMappingJson(record[key])}`).join(',')
63
+ return `{${body}}`
64
+ }
65
+
66
+ /** 按 Unicode 码位比较(而非 UTF-16 码元),与 Python `sort_keys` 的键序一致。 */
67
+ function compareCodePoints(left: string, right: string): number {
68
+ const a = Array.from(left, (char) => char.codePointAt(0) ?? 0)
69
+ const b = Array.from(right, (char) => char.codePointAt(0) ?? 0)
70
+ const length = Math.min(a.length, b.length)
71
+ for (let i = 0; i < length; i += 1) {
72
+ if (a[i] !== b[i]) return a[i] - b[i]
73
+ }
74
+ return a.length - b.length
75
+ }
76
+
77
+ /**
78
+ * 计算 `digest = sha256(canonical(mapping))`。
79
+ *
80
+ * 非数组输入抛 `TypeError`:写入一个无法摘要的覆盖记录是编程错误,写入前
81
+ * 就应该失败,而不是把 `null` 的摘要当成合法值落盘。读取侧请用
82
+ * `verifyMappingDigest`(它对任何坏输入都返回 false,不抛)。
83
+ */
84
+ export function computeMappingDigest(mapping: unknown): string {
85
+ if (!Array.isArray(mapping)) {
86
+ throw new TypeError('supersededBy.mapping 必须是数组,才能计算 sha256(canonical(mapping))')
87
+ }
88
+ const canonical = canonicalMappingJson(mapping)
89
+ return MAPPING_DIGEST_PREFIX + createHash('sha256').update(canonical, 'utf8').digest('hex')
90
+ }
91
+
92
+ /** digest 是否形如 `sha256:<64 位小写十六进制>`。 */
93
+ export function isMappingDigest(value: unknown): value is string {
94
+ return typeof value === 'string' && MAPPING_DIGEST_RE.test(value)
95
+ }
96
+
97
+ /**
98
+ * 复验:从 mapping 重算摘要并与记录里的 digest 比对。
99
+ * 任何坏输入(缺 mapping、digest 缺失/格式错、被改动)都返回 false。
100
+ */
101
+ export function verifyMappingDigest(mapping: unknown, digest: unknown): boolean {
102
+ if (!Array.isArray(mapping) || !isMappingDigest(digest)) return false
103
+ return computeMappingDigest(mapping) === digest
104
+ }
105
+
106
+ /**
107
+ * 写入侧辅助:返回带有复算 digest 的 `supersededBy` 副本。
108
+ * 运行时是唯一 write-side 复算者(§7.2 第 6 条),调用方不得自报 digest。
109
+ */
110
+ export function withMappingDigest<T extends Record<string, unknown>>(supersededBy: T): T & { digest: string } {
111
+ const mapping = supersededBy?.mapping
112
+ if (!Array.isArray(mapping)) {
113
+ throw new TypeError('supersededBy.mapping 必须是数组,才能写入 digest')
114
+ }
115
+ return { ...supersededBy, digest: computeMappingDigest(mapping) }
116
+ }
@@ -0,0 +1,429 @@
1
+ /**
2
+ * [1.9.2] `superseded`(责任已转移)的**唯一写入路径**。
3
+ *
4
+ * 规则出处(落盘文档,不在本文件重复全文):
5
+ * - `_rerun_20261101/GATE_rule_design.md` §6.1(字段 schema:工具入参 vs
6
+ * 运行时存储)、§6.2(V1–V8 核验与失败码)、§7.2(迁移证据要求)、
7
+ * §7.4(幂等 / 撤销 / 批量 / 失败即不变)。
8
+ * - `docs/postmortem-1.8.7-20261031.md` §16「残余:superseded 写入路径」。
9
+ *
10
+ * 为什么要有这一个文件:1.9.0/1.9.1 只做了读侧(replay 读
11
+ * `cancel.disposition === 'superseded'`、present 的覆盖链判定、dispatch 的
12
+ * `PLAN_SUPERSEDED`),写侧完全不存在。任何「就地改一下 record.phase」的
13
+ * 捷径都会造成 live 与 replay 分叉——UI 说被取代、重启后说未完成/已取消,
14
+ * 正是本子任务要杜绝的绕过。因此写入只允许经过本模块:
15
+ *
16
+ * 1. 先做 V1–V8 全量核验(任一失败:返回 `ok:false` + `SUPERSEDE_*` 码,
17
+ * **不改内存、不写日志**);
18
+ * 2. 由运行时复算 `coverage` 与 `digest`(模型只能给映射意图,不能自报
19
+ * 计数/摘要);
20
+ * 3. 用 `buildCancelMessage(..., { disposition:'superseded' })`——全仓库唯一
21
+ * 拼装 `workplan-cancel` 信封的函数——写 durable 记录;
22
+ * 4. 只有 append 成功之后才把内存记录翻成 `phase='superseded'`。
23
+ *
24
+ * 语义边界(必须明说):运行时能验的是承接计划那一侧的机器事实(存在、时序、
25
+ * 状态、结构化证据、验收、产物);「两项工作在语义上等价」是人的判断,只能
26
+ * 由用户消息确认(V8)承载。这不是实现缺陷,而是 RC-2(自证闭环)的结构性
27
+ * 防线。
28
+ */
29
+ import {
30
+ buildCancelMessage,
31
+ derivePlanSnapshot,
32
+ flattenSubtasks,
33
+ isRecord,
34
+ isTerminalPhase,
35
+ messageText,
36
+ parseWorkplanMessage,
37
+ truncate,
38
+ } from './plan.js'
39
+ import { withMappingDigest } from './supersede-digest.js'
40
+
41
+ /** V1–V8 的失败码。对外契约:工具结果、测试与审计日志按字面值断言。 */
42
+ export const SUPERSEDE_CODES = {
43
+ TARGET_UNKNOWN: 'SUPERSEDE_TARGET_UNKNOWN',
44
+ ORDER_INVALID: 'SUPERSEDE_ORDER_INVALID',
45
+ SOURCE_NOT_CANCELLED: 'SUPERSEDE_SOURCE_NOT_CANCELLED',
46
+ SOURCE_DONE: 'SUPERSEDE_SOURCE_DONE',
47
+ /** 设计 §7.1:空计划不是交付对象,不能走 supersede(U6)。 */
48
+ SOURCE_EMPTY: 'SUPERSEDE_SOURCE_EMPTY',
49
+ MAPPING_INCOMPLETE: 'SUPERSEDE_MAPPING_INCOMPLETE',
50
+ TARGET_ITEM_UNKNOWN: 'SUPERSEDE_TARGET_ITEM_UNKNOWN',
51
+ EVIDENCE_GAP: 'SUPERSEDE_EVIDENCE_GAP',
52
+ TARGET_TERMINAL: 'SUPERSEDE_TARGET_TERMINAL',
53
+ NOT_CONFIRMED: 'SUPERSEDE_NOT_CONFIRMED',
54
+ /** 信封构造失败(含 digest 无法复算):fail-closed,不写日志。 */
55
+ WRITE_FAILED: 'SUPERSEDE_WRITE_FAILED',
56
+ } as const
57
+
58
+ export type SupersedeCode = (typeof SUPERSEDE_CODES)[keyof typeof SUPERSEDE_CODES]
59
+
60
+ /** V8 的确认词,逐字取自规则设计 §6.2。 */
61
+ const CONFIRMATION_WORDS = /确认|同意|可以|按此执行/u
62
+
63
+ /** mapping 上限:计划最多 15 项,留出审计余量,防止异常输入撑爆日志。 */
64
+ const MAX_MAPPING_ENTRIES = 100
65
+
66
+ export interface SupersedeDeps {
67
+ /** `reconstructFromSession`:由调用方注入,避免 runtime ↔ supersede 循环 import。 */
68
+ reconstruct: (session: any, planId: string) => any
69
+ }
70
+
71
+ function messageOf(event: any) {
72
+ return event?.data?.message ?? event?.data
73
+ }
74
+
75
+ /** 计划定义在会话日志中的位置;找不到返回 -1(V2 的输入,fail-closed)。 */
76
+ export function planDefinitionSeq(session: any, planId: string): number {
77
+ if (!planId || typeof session?.eventAt !== 'function') return -1
78
+ for (let i = 0; i < session.seq; i += 1) {
79
+ let event
80
+ try {
81
+ event = session.eventAt(i)
82
+ } catch {
83
+ continue
84
+ }
85
+ if (!event || event.type !== 'user/message') continue
86
+ const plan = parseWorkplanMessage(messageOf(event))?.plan
87
+ if (plan && String(plan.planId ?? '') === planId) return i
88
+ }
89
+ return -1
90
+ }
91
+
92
+ /**
93
+ * V8:本会话中**真实用户消息**(非工具结果、非插件通知)需同时包含源与承接
94
+ * 两个 planId,且含确认词;返回该消息的 seq(未确认返回 -1)。
95
+ *
96
+ * 只认 `role==='user'` 且 `source.kind` 为 `user`/省略的消息:插件自己写的
97
+ * plan/result/cancel/update 通知也都是 role user,但带 `source.kind`,必须排除,
98
+ * 否则「计划正文里同时出现两个 planId」会被误当用户确认。
99
+ */
100
+ export function confirmationSeq(session: any, sourcePlanId: string, successorPlanId: string): number {
101
+ if (!sourcePlanId || !successorPlanId || typeof session?.eventAt !== 'function') return -1
102
+ for (let i = session.seq - 1; i >= 0; i -= 1) {
103
+ let event
104
+ try {
105
+ event = session.eventAt(i)
106
+ } catch {
107
+ continue
108
+ }
109
+ if (!event || event.type !== 'user/message') continue
110
+ const message = messageOf(event)
111
+ if (!message || message.role !== 'user') continue
112
+ const kind = message.source?.kind
113
+ if (kind !== undefined && kind !== 'user') continue
114
+ const text = messageText(message)
115
+ if (!text || !text.includes(sourcePlanId) || !text.includes(successorPlanId)) continue
116
+ if (CONFIRMATION_WORDS.test(text)) return i
117
+ }
118
+ return -1
119
+ }
120
+
121
+ function definedSubtasks(plan: any): any[] {
122
+ try {
123
+ return flattenSubtasks(plan).map((entry: any) => entry.subtask)
124
+ } catch {
125
+ return []
126
+ }
127
+ }
128
+
129
+ /**
130
+ * V6:承接计划某个目标项的机器事实缺口(空数组 = 通过)。
131
+ *
132
+ * 判据逐字取自规则设计 §6.2:`status==='done'` ∧ `verification==='structured'`
133
+ * ∧ `acceptance` 非空且逐项 `result==='pass'` ∧ `missingArtifacts` 为空 ∧
134
+ * 声明产物 `exists!==false`。
135
+ */
136
+ export function mappedEvidenceGaps(item: any): string[] {
137
+ const gaps: string[] = []
138
+ if (item?.status !== 'done') gaps.push(`状态为 ${String(item?.status ?? '缺失')}`)
139
+ const verification = typeof item?.verification === 'string' ? item.verification : ''
140
+ if (verification !== 'structured') gaps.push(`verification=${verification || '缺失'}`)
141
+ const acceptance = Array.isArray(item?.acceptance) ? item.acceptance : []
142
+ if (acceptance.length === 0) gaps.push('未提供验收项(acceptance 为空)')
143
+ for (const entry of acceptance) {
144
+ if (entry?.result !== 'pass') {
145
+ gaps.push(`验收未通过:${truncate(String(entry?.criterion ?? '未命名验收项'), 60)}`)
146
+ }
147
+ }
148
+ const missing = Array.isArray(item?.missingArtifacts) ? item.missingArtifacts.filter(Boolean) : []
149
+ if (missing.length > 0) gaps.push(`缺少声明产物:${missing.slice(0, 3).join('、')}`)
150
+ const artifacts = Array.isArray(item?.artifacts) ? item.artifacts : []
151
+ for (const artifact of artifacts) {
152
+ if (artifact?.exists === false) {
153
+ gaps.push(`声明产物不存在:${truncate(String(artifact?.ref ?? '未命名产物'), 80)}`)
154
+ }
155
+ }
156
+ return gaps
157
+ }
158
+
159
+ /**
160
+ * 唯一的 superseded 写入函数。
161
+ *
162
+ * 返回值直接是工具结果(`ok/code/error/hint`)。**任何失败分支都不写日志、
163
+ * 不改 record**(§7.4「失败即不变」);只有 V1–V8 全通过且 append 成功才
164
+ * 翻状态。幂等:已 superseded 再次调用返回 `ok:true, alreadySuperseded:true`,
165
+ * 不追加记录、不改变状态。
166
+ */
167
+ export function supersedePlanRecord(session: any, record: any, args: any, deps: SupersedeDeps): any {
168
+ const planId = String(record?.plan?.planId ?? '')
169
+ const snapshot = derivePlanSnapshot(record?.statuses ?? [])
170
+ const stats = snapshot.stats
171
+
172
+ const deny = (code: SupersedeCode, detail: string, extra: any = {}) => ({
173
+ ok: false,
174
+ code,
175
+ planId,
176
+ phase: String(record?.phase ?? 'cancelled'),
177
+ stats,
178
+ error: detail,
179
+ hint: '状态未改变:仍为 cancelled 且未完成。不得调用 present,不得声称“已完成/最终版/已交付”;'
180
+ + '修正该缺口后,再调用 dsh_workplan_cancel({ disposition:"superseded", supersededBy:{…} })。',
181
+ ...extra,
182
+ })
183
+
184
+ // §7.4 幂等:被取代是终态,重复调用不得追加记录。
185
+ if (record?.phase === 'superseded' || record?.superseded === true) {
186
+ return {
187
+ ok: true,
188
+ planId,
189
+ phase: 'superseded',
190
+ alreadySuperseded: true,
191
+ supersededBy: record?.supersededBy ?? null,
192
+ stats,
193
+ hint: '该计划已被取代:本次调用是幂等 no-op(不追加记录、不改变状态)。被取代不等于完成。',
194
+ }
195
+ }
196
+
197
+ // V3:源计划必须是**已落盘**的 cancelled,且未全部 done。
198
+ if (record?.phase !== 'cancelled') {
199
+ return deny(
200
+ SUPERSEDE_CODES.SOURCE_NOT_CANCELLED,
201
+ `源计划 ${planId} 当前为 ${String(record?.phase ?? '未知')},不是 cancelled:禁止静默取代运行中/未取消的计划`,
202
+ )
203
+ }
204
+ if (record?.cancelRecorded === false) {
205
+ return deny(
206
+ SUPERSEDE_CODES.SOURCE_NOT_CANCELLED,
207
+ `源计划 ${planId} 的取消记录没有成功落盘(cancelRecorded=false):先重试取消,再考虑覆盖迁移`,
208
+ )
209
+ }
210
+ if (Number(stats.total) > 0 && Number(stats.done) === Number(stats.total)) {
211
+ return deny(
212
+ SUPERSEDE_CODES.SOURCE_DONE,
213
+ `源计划 ${planId} 已 ${stats.done}/${stats.total} 全部 done:完成态不得被取代(应保持 done,不能洗成 superseded)`,
214
+ )
215
+ }
216
+ const sourceItems = definedSubtasks(record?.plan)
217
+ if (sourceItems.length === 0) {
218
+ return deny(SUPERSEDE_CODES.SOURCE_EMPTY, `源计划 ${planId} 没有定义任何子任务:空计划不是交付对象,不能走 supersede`)
219
+ }
220
+
221
+ // 入参:只接受「映射意图」,计数与摘要由运行时复算。
222
+ const byInput = isRecord(args?.supersededBy) ? args.supersededBy : null
223
+ const successorPlanId = typeof byInput?.planId === 'string' ? byInput.planId.trim() : ''
224
+ if (!successorPlanId) {
225
+ return deny(SUPERSEDE_CODES.TARGET_UNKNOWN, '缺少 supersededBy.planId:无法指定承接计划')
226
+ }
227
+ if (!Array.isArray(byInput?.mapping)) {
228
+ return deny(SUPERSEDE_CODES.MAPPING_INCOMPLETE, '缺少 supersededBy.mapping:必须逐项给出源→承接的映射与 basis')
229
+ }
230
+
231
+ // V1:承接计划存在、是同会话日志里的真实计划定义、且定义了子任务。
232
+ const successor = deps.reconstruct(session, successorPlanId)
233
+ if (!successor?.plan || String(successor.plan.planId ?? '') !== successorPlanId) {
234
+ return deny(SUPERSEDE_CODES.TARGET_UNKNOWN, `承接计划 ${successorPlanId} 不存在于本会话日志`)
235
+ }
236
+ const successorItems = definedSubtasks(successor.plan)
237
+ if (successorItems.length === 0) {
238
+ return deny(SUPERSEDE_CODES.TARGET_UNKNOWN, `承接计划 ${successorPlanId} 没有定义任何子任务,不能作为覆盖计划`)
239
+ }
240
+
241
+ // V2:承接计划必须定义得比源计划晚(防止用历史计划反盖当前计划)。
242
+ const sourceSeq = planDefinitionSeq(session, planId)
243
+ const successorSeq = planDefinitionSeq(session, successorPlanId)
244
+ if (sourceSeq < 0 || successorSeq < 0) {
245
+ return deny(
246
+ SUPERSEDE_CODES.ORDER_INVALID,
247
+ `无法在会话日志中定位计划定义(源 ${planId}=seq ${sourceSeq},承接 ${successorPlanId}=seq ${successorSeq}):`
248
+ + '覆盖时序无法复核,按 fail-closed 拒绝',
249
+ )
250
+ }
251
+ if (successorSeq <= sourceSeq) {
252
+ return deny(
253
+ SUPERSEDE_CODES.ORDER_INVALID,
254
+ `承接计划 ${successorPlanId} 定义于 seq ${successorSeq},不晚于源计划 ${planId} 的 seq ${sourceSeq}`,
255
+ )
256
+ }
257
+
258
+ // V7:承接计划不得是终态(不能拿另一个 cancelled/superseded 当覆盖)。
259
+ if (isTerminalPhase(successor.phase)) {
260
+ return deny(
261
+ SUPERSEDE_CODES.TARGET_TERMINAL,
262
+ `承接计划 ${successorPlanId} 本身是终态(${String(successor.phase)}):不能用一个已终止的计划承担交付责任`,
263
+ )
264
+ }
265
+
266
+ // V4:mapping.from 恰好覆盖源计划全部定义子任务,各一次,无多余项。
267
+ const sourceIds = sourceItems.map((item: any) => String(item.id))
268
+ const sourceIdSet = new Set(sourceIds)
269
+ const successorIds = new Set(successorItems.map((item: any) => String(item.id)))
270
+ const seen = new Map<string, number>()
271
+ const mappingProblems: string[] = []
272
+ const mapping: Array<{ from: string; to: string; basis: string }> = []
273
+ byInput.mapping.slice(0, MAX_MAPPING_ENTRIES).forEach((raw: any, index: number) => {
274
+ if (!isRecord(raw)) {
275
+ mappingProblems.push(`第 ${index + 1} 项不是对象`)
276
+ return
277
+ }
278
+ const from = typeof raw.from === 'string' ? raw.from.trim() : ''
279
+ const to = typeof raw.to === 'string' ? raw.to.trim() : ''
280
+ const basis = typeof raw.basis === 'string' ? raw.basis.trim() : ''
281
+ if (!from || !to) {
282
+ mappingProblems.push(`第 ${index + 1} 项缺少 from/to`)
283
+ return
284
+ }
285
+ if (!basis) mappingProblems.push(`${from} 缺少 basis(覆盖依据)`)
286
+ if (!sourceIdSet.has(from)) {
287
+ mappingProblems.push(`from=${from} 不是源计划 ${planId} 的定义子任务`)
288
+ } else if (seen.has(from)) {
289
+ mappingProblems.push(`from=${from} 重复映射`)
290
+ } else {
291
+ seen.set(from, 1)
292
+ }
293
+ mapping.push({ from, to, basis: truncate(basis, 500) })
294
+ })
295
+ if (byInput.mapping.length > MAX_MAPPING_ENTRIES) {
296
+ mappingProblems.push(`映射项超过 ${MAX_MAPPING_ENTRIES} 条上限`)
297
+ }
298
+ const missingFrom = sourceIds.filter((id: string) => !seen.has(id))
299
+ if (mappingProblems.length > 0 || missingFrom.length > 0) {
300
+ return deny(
301
+ SUPERSEDE_CODES.MAPPING_INCOMPLETE,
302
+ '映射不完整或非法:必须逐项覆盖源计划全部定义子任务(各一次)',
303
+ {
304
+ requiredCount: sourceIds.length,
305
+ coveredCount: seen.size,
306
+ missingFrom,
307
+ problems: mappingProblems.slice(0, 20),
308
+ },
309
+ )
310
+ }
311
+
312
+ // V5:每个映射目标都必须是承接计划的定义子任务。
313
+ const unknownTargets = mapping.filter((entry) => !successorIds.has(entry.to)).map((entry) => entry.to)
314
+ if (unknownTargets.length > 0) {
315
+ return deny(
316
+ SUPERSEDE_CODES.TARGET_ITEM_UNKNOWN,
317
+ `映射目标不存在于承接计划 ${successorPlanId}`,
318
+ { unknownTargets: [...new Set(unknownTargets)].slice(0, 20) },
319
+ )
320
+ }
321
+
322
+ // V6:逐项机器事实(done + structured + 验收全 pass + 产物齐)。
323
+ const successorStatus = new Map<string, any>(
324
+ (Array.isArray(successor.statuses) ? successor.statuses : []).map((item: any) => [String(item?.subtaskId ?? ''), item]),
325
+ )
326
+ const evidenceGaps: string[] = []
327
+ const normalizedMapping = mapping.map((entry) => {
328
+ const item = successorStatus.get(entry.to)
329
+ const gaps = mappedEvidenceGaps(item)
330
+ if (gaps.length > 0) evidenceGaps.push(`${entry.from}→${entry.to}:${gaps.join(';')}`)
331
+ return {
332
+ ...entry,
333
+ evidence: { status: 'done', verification: 'structured', acceptance: 'all-pass', artifacts: 'ok' },
334
+ }
335
+ })
336
+ if (evidenceGaps.length > 0) {
337
+ return deny(
338
+ SUPERSEDE_CODES.EVIDENCE_GAP,
339
+ `承接计划 ${successorPlanId} 的映射目标存在证据缺口:被取代不等于完成,缺口补不齐就不得迁移`,
340
+ { gaps: evidenceGaps.slice(0, 20) },
341
+ )
342
+ }
343
+
344
+ // V8:用户确认(真实用户消息,同时含两个 planId 与确认词)。
345
+ const confirmedAtSeq = confirmationSeq(session, planId, successorPlanId)
346
+ if (confirmedAtSeq < 0) {
347
+ return deny(
348
+ SUPERSEDE_CODES.NOT_CONFIRMED,
349
+ `没有找到用户确认:本会话需要一条用户消息同时包含 ${planId} 与 ${successorPlanId},`
350
+ + '并含「确认/同意/可以/按此执行」之一;模型自述不算确认',
351
+ )
352
+ }
353
+
354
+ // 运行时复算 coverage 与 digest(模型不得自报),再写 durable 记录。
355
+ const verifiedAt = Date.now()
356
+ let supersededBy: any
357
+ try {
358
+ supersededBy = withMappingDigest({
359
+ planId: successorPlanId,
360
+ requiredCount: sourceIds.length,
361
+ coveredCount: normalizedMapping.length,
362
+ coverage: normalizedMapping.length === sourceIds.length ? 'full' : 'partial',
363
+ mapping: normalizedMapping,
364
+ verifiedAt,
365
+ verifiedBy: 'runtime-recompute',
366
+ successorSeenAtSeq: successorSeq,
367
+ confirmedAtSeq,
368
+ })
369
+ } catch (error: any) {
370
+ return deny(SUPERSEDE_CODES.WRITE_FAILED, `无法计算覆盖摘要:${error?.message ?? String(error)}`)
371
+ }
372
+ const reason = typeof args?.reason === 'string' && args.reason.trim()
373
+ ? truncate(args.reason.trim(), 300)
374
+ : '责任已转移给可验证的承接计划'
375
+ let message
376
+ try {
377
+ message = buildCancelMessage(planId, reason, {
378
+ disposition: 'superseded',
379
+ supersededAt: verifiedAt,
380
+ supersededBy,
381
+ })
382
+ } catch (error: any) {
383
+ return deny(SUPERSEDE_CODES.WRITE_FAILED, `构造取代记录失败:${error?.message ?? String(error)}`)
384
+ }
385
+ try {
386
+ session.append('user/message', message, { surfaceOp: 'append' })
387
+ } catch (error: any) {
388
+ record.errors = [...(Array.isArray(record?.errors) ? record.errors : []),
389
+ `写入取代记录失败:${error instanceof Error ? error.message : String(error)}`].slice(-20)
390
+ record.supersedeRecorded = false
391
+ return {
392
+ ok: false,
393
+ code: SUPERSEDE_CODES.WRITE_FAILED,
394
+ planId,
395
+ phase: String(record?.phase ?? 'cancelled'),
396
+ stats,
397
+ error: `取代记录写入会话日志失败:${error instanceof Error ? error.message : String(error)}`,
398
+ hint: '日志未写入,状态保持不变(仍为 cancelled/未完成):不得调用 present。'
399
+ + '修复日志写入后重试;不要用内存改判伪造 superseded。',
400
+ }
401
+ }
402
+
403
+ // 只有 durable 记录写入成功后,才允许翻内存状态(live 与 replay 同源)。
404
+ record.phase = 'superseded'
405
+ record.superseded = true
406
+ record.supersededBy = supersededBy
407
+ record.cancelled = false
408
+ record.supersedeRecorded = true
409
+ record.supersededAt = verifiedAt
410
+ record.updatedAt = verifiedAt
411
+
412
+ return {
413
+ ok: true,
414
+ planId,
415
+ phase: 'superseded',
416
+ reason,
417
+ supersededAt: verifiedAt,
418
+ supersededBy,
419
+ coverage: supersededBy.coverage,
420
+ requiredCount: supersededBy.requiredCount,
421
+ coveredCount: supersededBy.coveredCount,
422
+ successorSeenAtSeq: successorSeq,
423
+ confirmedAtSeq,
424
+ supersedeRecorded: true,
425
+ stats,
426
+ hint: '已写入 superseded 记录(replay 后仍为 superseded)。被取代不等于完成:'
427
+ + `源计划仍是 ${stats.done}/${stats.total},交付只能用承接计划 ${successorPlanId} 通过交付就绪检查的产物。`,
428
+ }
429
+ }