dsh-workplan 1.9.1 → 1.10.6

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.
package/src/plan.ts CHANGED
@@ -1745,11 +1745,13 @@ export function applyResultStatuses(statuses: any, result: any) {
1745
1745
  if (!current) continue
1746
1746
  /*
1747
1747
  * A manually re-adjudicated status (durable `workplan-update`) must not be
1748
- * rolled back by an older result snapshot. Only comparable revisions are
1749
- * ordered; legacy entries without `revision` keep the old "last wins" rule.
1748
+ * rolled back by an older result snapshot — and the *same* snapshot must not
1749
+ * be applied twice. 1.9.1 skipped only `entry.revision < current.revision`,
1750
+ * so an equal revision was re-applied and bumped every row by one revision
1751
+ * on each replay (T1 实测:T1–T7 各 +1)。
1750
1752
  */
1751
1753
  if (Number.isInteger(entry.revision) && Number.isInteger(current.revision)
1752
- && Number(entry.revision) < Number(current.revision)) continue
1754
+ && Number(entry.revision) <= Number(current.revision)) continue
1753
1755
  try {
1754
1756
  next = applyStatus(next, entry.subtaskId, {
1755
1757
  status: entry.status,
@@ -1813,7 +1815,19 @@ export function applyStatus(statuses: any, subtaskId: any, patch: any) {
1813
1815
  if (patch.startedAt !== undefined) next.startedAt = patch.startedAt
1814
1816
  if (patch.finishedAt !== undefined) next.finishedAt = patch.finishedAt
1815
1817
  if (patch.summary !== undefined) next.summary = truncate(String(patch.summary), 3000)
1816
- if (patch.error !== undefined) next.error = patch.error === null ? null : truncate(String(patch.error), 2000)
1818
+ if (patch.error !== undefined) {
1819
+ /*
1820
+ * [1.10.0] 显式清空 `error` 也属于一次「失败记录退场」:先留档再清空。
1821
+ *
1822
+ * 回放路径(`applyResultStatuses`)对 done 行传的是 `error: null`,如果这里
1823
+ * 只是把它抹掉,事故记录里「为什么这一行曾经没做完」就再也查不到了。
1824
+ */
1825
+ if (patch.error === null && typeof current.error === 'string' && current.error.trim() !== '') {
1826
+ next.lastError = current.error
1827
+ next.lastErrorAt = Date.now()
1828
+ }
1829
+ next.error = patch.error === null ? null : truncate(String(patch.error), 2000)
1830
+ }
1817
1831
  if (patch.verification !== undefined) {
1818
1832
  if (!VERIFICATIONS.includes(patch.verification)) {
1819
1833
  throw new PlanError(`非法 verification:${String(patch.verification)}`, 'INVALID_VERIFICATION')
@@ -1834,6 +1848,20 @@ export function applyStatus(statuses: any, subtaskId: any, patch: any) {
1834
1848
  })
1835
1849
  }
1836
1850
  if (patch.needs !== undefined) next.needs = readEvidenceNeeds(patch.needs)
1851
+ /*
1852
+ * [1.10.6] The files a retry refused to touch.
1853
+ *
1854
+ * A ceiling timeout can be retried once, but only when the artifacts the first
1855
+ * attempt landed are unchanged. When they did change, `runtime.ts` records
1856
+ * their refs here instead of overwriting them, so "why was there no retry"
1857
+ * stays answerable from the plan record alone.
1858
+ */
1859
+ if (patch.artifactConflict !== undefined) {
1860
+ next.artifactConflict = (Array.isArray(patch.artifactConflict) ? patch.artifactConflict : [])
1861
+ .slice(0, 8)
1862
+ .map((ref: any) => truncate(String(ref ?? ''), 300))
1863
+ .filter((ref: string) => ref !== '')
1864
+ }
1837
1865
  if (patch.blockedBy !== undefined) {
1838
1866
  next.blockedBy = (Array.isArray(patch.blockedBy) ? patch.blockedBy : [])
1839
1867
  .slice(0, 10)
@@ -1853,6 +1881,45 @@ export function applyStatus(statuses: any, subtaskId: any, patch: any) {
1853
1881
  if (patch.status === 'done') {
1854
1882
  next.progress = 100
1855
1883
  if (next.finishedAt === null) next.finishedAt = Date.now()
1884
+ /*
1885
+ * [1.10.0] R-01:「完成」与「失败原因」不能同时成立。
1886
+ *
1887
+ * 1.9.1 及以前,done 分支根本不碰 `error`,而改判路径对非 blocked 传的是
1888
+ * `undefined`,被上面 1816 行解释成「保留旧值」。于是「预算用尽,等待续跑」
1889
+ * 这类上一轮的失败文本会永久留在一个 status=done 的行上,界面再无条件把它
1890
+ * 渲染成「卡住原因」——同一行同时写着「已完成」和「卡住了」,就是这次
1891
+ * 事故的同屏矛盾。
1892
+ *
1893
+ * 旧文本不丢弃,迁入 `lastError` 供审计;`error` 只描述「当前这一行为什么
1894
+ * 没做完」,完成的行没有这种原因。
1895
+ */
1896
+ if (typeof next.error === 'string' && next.error.trim() !== '') {
1897
+ next.lastError = next.error
1898
+ next.lastErrorAt = Date.now()
1899
+ }
1900
+ /*
1901
+ * [1.10.2] 写侧补漏:显式传 `error` 的 done 也必须清空。
1902
+ *
1903
+ * 1.10.0/1.10.1 只在 `patch.error` 为 `undefined`/`null` 时清空,因此
1904
+ * `applyStatus(rows, id, { status: 'done', error: '...' })`(以及把子会话
1905
+ * result 原样回放的 `applyResultStatuses`)仍能把「完成 + 失败文本」写进
1906
+ * 持久化记录。读侧 `normaliseStatusEntry` 会在下发的载荷里清洗,界面看不到,
1907
+ * 但只要有任何消费者直接读 `record.statuses`(审计、导出、后续新增字段),
1908
+ * 这个不变量就又破了。这里与读侧使用同一条规则:旧文本只进 `lastError`。
1909
+ */
1910
+ next.error = null
1911
+ next.completedBy = ['child', 'agent', 'system'].includes(patch.completedBy)
1912
+ ? patch.completedBy
1913
+ : (next.completedBy ?? (next.updatedBy as any) ?? 'system')
1914
+ if (next.attemptOutcome !== undefined && next.attemptOutcome !== null
1915
+ && next.attemptOutcome !== 'completed' && next.attemptOutcome !== 'manual') {
1916
+ next.priorOutcome = next.attemptOutcome
1917
+ }
1918
+ next.attemptOutcome = patch.attemptOutcome
1919
+ ?? (next.completedBy === 'agent' ? 'manual' : 'completed')
1920
+ next.attemptEndedAt = patch.attemptEndedAt ?? Date.now()
1921
+ // [1.10.6] A finished row cannot also be "we refused to overwrite it".
1922
+ if (patch.artifactConflict === undefined) next.artifactConflict = undefined
1856
1923
  }
1857
1924
  if (patch.status === 'pending') {
1858
1925
  /*
@@ -1877,9 +1944,13 @@ export function applyStatus(statuses: any, subtaskId: any, patch: any) {
1877
1944
  if (patch.missingArtifacts === undefined) next.missingArtifacts = undefined
1878
1945
  if (patch.needs === undefined) next.needs = undefined
1879
1946
  if (patch.blockedBy === undefined) next.blockedBy = undefined
1947
+ // [1.10.6] A conflict belongs to one attempt; a reset starts a new one.
1948
+ if (patch.artifactConflict === undefined) next.artifactConflict = undefined
1880
1949
  }
1881
1950
  if (patch.status === 'in_progress') {
1882
1951
  if (next.startedAt === null) next.startedAt = Date.now()
1952
+ // [1.10.6] The retry of a conflicting row is itself the new attempt.
1953
+ if (patch.artifactConflict === undefined) next.artifactConflict = undefined
1883
1954
  /*
1884
1955
  * [1.5.2] 「正在做」不允许自称 100%。
1885
1956
  *
@@ -1999,6 +2070,21 @@ export function normaliseStatusEntry(entry: any): StatusEntry {
1999
2070
  const source: any = entry ?? {}
2000
2071
  const status: SubtaskStatus = isSubtaskStatus(source.status) ? source.status : 'pending'
2001
2072
  const progress = status === 'done' ? 100 : status === 'pending' ? 0 : clampProgress(source.progress)
2073
+ /*
2074
+ * [1.10.0] R-01 读侧兜底:历史脏数据在载荷层就要干净。
2075
+ *
2076
+ * 1.9.1 写下的记录里,被人工改判为 done 的行仍带着上一轮的失败文本。只修写
2077
+ * 入口不会让已经落盘的记录自愈,而状态只存在于会话事件日志里、不会重写,
2078
+ * 所以必须在每次派生载荷时把「done + error」拆成「done + lastError」,
2079
+ * 否则用户刷新一次就又能看到「已完成 + 卡住原因」。
2080
+ */
2081
+ const legacyError = typeof source.error === 'string' && source.error.trim() !== ''
2082
+ ? source.error
2083
+ : null
2084
+ const error = status === 'done' ? null : legacyError
2085
+ const lastError = status === 'done'
2086
+ ? (typeof source.lastError === 'string' && source.lastError !== '' ? source.lastError : legacyError)
2087
+ : (typeof source.lastError === 'string' ? source.lastError : null)
2002
2088
  return {
2003
2089
  ...source,
2004
2090
  subtaskId: stringOr(source.subtaskId, ''),
@@ -2012,7 +2098,8 @@ export function normaliseStatusEntry(entry: any): StatusEntry {
2012
2098
  startedAt: status === 'pending' ? null : numberOrNull(source.startedAt),
2013
2099
  finishedAt: status === 'pending' ? null : numberOrNull(source.finishedAt),
2014
2100
  summary: stringOr(source.summary, ''),
2015
- error: typeof source.error === 'string' ? source.error : null,
2101
+ error,
2102
+ ...(lastError ? { lastError } : {}),
2016
2103
  }
2017
2104
  }
2018
2105
 
@@ -2044,7 +2131,7 @@ export function normaliseStatuses(statuses: any): StatusEntry[] {
2044
2131
  * therefore never drag the plan's percentage up to where the cards say it is
2045
2132
  * finished — that was the “100% 但 11/12” contradiction users saw.
2046
2133
  */
2047
- export function deriveAggregates(statuses: readonly StatusEntry[]): {
2134
+ export function deriveAggregates(statuses: readonly StatusEntry[], expectedTotal?: number): {
2048
2135
  stats: Stats
2049
2136
  departments: DepartmentSummary[]
2050
2137
  } {
@@ -2083,7 +2170,20 @@ export function deriveAggregates(statuses: readonly StatusEntry[]): {
2083
2170
  departments.set(item.department, department)
2084
2171
  }
2085
2172
 
2086
- const total = statuses.length
2173
+ /*
2174
+ * [1.10.0] R-07:分母必须来自「计划定义」,不能是「实际有几行状态」。
2175
+ *
2176
+ * 1.9.1 的 `total = statuses.length`,而 I1 又只是拿它和自身比较(同义反复),
2177
+ * 于是构造出「定义 13 项、只写 5 行状态」就得到 5/5 = 100%(T3 反例 C16)。
2178
+ * 现在调用方把定义条数传进来:缺的行按 pending 计入总数,既不会把分母缩小,
2179
+ * 也不会凭空造出几行明细。
2180
+ */
2181
+ const defined = Number.isInteger(expectedTotal) && Number(expectedTotal) > 0
2182
+ ? Number(expectedTotal)
2183
+ : 0
2184
+ const total = Math.max(statuses.length, defined)
2185
+ const missing = Math.max(0, total - statuses.length)
2186
+ pending += missing
2087
2187
  const allDone = total > 0 && done === total
2088
2188
  /*
2089
2189
  * [1.5.2] 加权进度在「未全部完成」时不得四舍五入成 100。
@@ -2114,9 +2214,9 @@ export function deriveAggregates(statuses: readonly StatusEntry[]): {
2114
2214
  * values share one array instance, so `stats`, `departments` and `statuses` in
2115
2215
  * a single payload cannot disagree.
2116
2216
  */
2117
- export function derivePlanSnapshot(raw: any): PlanSnapshot {
2217
+ export function derivePlanSnapshot(raw: any, expectedTotal?: number): PlanSnapshot {
2118
2218
  const statuses = normaliseStatuses(raw)
2119
- const { stats, departments } = deriveAggregates(statuses)
2219
+ const { stats, departments } = deriveAggregates(statuses, expectedTotal)
2120
2220
  return { statuses, stats, departments }
2121
2221
  }
2122
2222
 
@@ -2146,8 +2246,23 @@ export function aggregateInvariantViolations(snapshot: PlanSnapshot, phase?: any
2146
2246
  const violations: string[] = []
2147
2247
  const { statuses, stats, departments } = snapshot
2148
2248
 
2149
- if (stats.total !== statuses.length) {
2150
- violations.push(`I1 stats.total=${stats.total} 与 statuses.length=${statuses.length} 不一致`)
2249
+ /*
2250
+ * [1.10.0] I1 改为「不得小于」,并新增 I12/I13。
2251
+ *
2252
+ * 旧 I1 是 `stats.total === statuses.length`——与产生它的表达式同义反复,
2253
+ * 永远成立,等于没检查(T3 实测 C16)。现在分母允许大于明细行数(缺行按
2254
+ * pending 计入),真正要禁止的是「分母比明细还小」这种把 100% 造出来的情形。
2255
+ * I12 封住本次事故的同屏矛盾:done 行不允许带 error。
2256
+ * I13 封住反过来的一侧:全部 done 却写着 progress<100。
2257
+ */
2258
+ if (stats.total < statuses.length) {
2259
+ violations.push(`I1 stats.total=${stats.total} 小于 statuses.length=${statuses.length}`)
2260
+ }
2261
+ if (stats.total > 0 && stats.done === stats.total && stats.progress !== 100) {
2262
+ violations.push(`I13 全部 ${stats.total} 项已 done,但 stats.progress=${stats.progress}`)
2263
+ }
2264
+ if (stats.done < stats.total && stats.progress >= 100) {
2265
+ violations.push(`I13 仅 ${stats.done}/${stats.total} 项 done,但 stats.progress=100`)
2151
2266
  }
2152
2267
  const counted = stats.done + stats.blocked + stats.inProgress + stats.pending
2153
2268
  if (counted !== stats.total) {
@@ -2178,6 +2293,10 @@ export function aggregateInvariantViolations(snapshot: PlanSnapshot, phase?: any
2178
2293
  if (item.status === 'done' && item.progress !== 100) {
2179
2294
  violations.push(`I6 ${item.subtaskId} 是 done 但 progress=${item.progress}`)
2180
2295
  }
2296
+ /* [1.10.0] I12:「完成」与「卡住原因」不能同屏。 */
2297
+ if (item.status === 'done' && typeof item.error === 'string' && item.error.trim() !== '') {
2298
+ violations.push(`I12 ${item.subtaskId} 是 done 但仍带 error=${item.error.slice(0, 80)}`)
2299
+ }
2181
2300
  }
2182
2301
 
2183
2302
  const sums = { total: 0, done: 0, blocked: 0, inProgress: 0 }
@@ -2377,6 +2496,18 @@ export function deliveryReadiness(snapshot: PlanSnapshot, options: { phase?: any
2377
2496
  }
2378
2497
  const done = Number(snapshot?.stats?.done ?? 0)
2379
2498
  const total = Number(snapshot?.stats?.total ?? 0)
2499
+ /*
2500
+ * [1.10.1] DF-05(P0):分母对账必须同时作用在交付门上。
2501
+ *
2502
+ * 1.10.0 把 `stats.total` 改成了计划定义条数,但 `deliveryReadiness` 仍然只遍历
2503
+ * 实际存在的状态行——于是「定义 13 项、只写 5 行且全 done」会得到
2504
+ * `done=5 / total=13` 却 **ready=true**,present 门禁可放行只做了 5/13 的计划
2505
+ * (T10 实测 `[done=5,total=13,ready=True]`)。缺失的行就是没做完,必须算阻塞。
2506
+ */
2507
+ const missingRows = total - statuses.length
2508
+ if (total > 0 && missingRows > 0) {
2509
+ blockers.push(`状态明细缺少 ${missingRows} 行(计划定义 ${total} 项,实际只写 ${statuses.length} 行):缺失项按未完成计`)
2510
+ }
2380
2511
  if (phase === 'cancelled' && (remaining.length > 0 || blockers.length > 0)) {
2381
2512
  blockers.unshift(`计划已取消但只完成 ${done}/${total}:取消只停止执行,不等于完成`)
2382
2513
  }