tasklite-engine 3.0.0.dev0__py3-none-any.whl → 3.0.0.dev1__py3-none-any.whl

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.
Files changed (60) hide show
  1. tasklite/__init__.py +42 -18
  2. tasklite/__main__.py +205 -0
  3. tasklite/_report.py +562 -0
  4. tasklite/backend/__init__.py +19 -2
  5. tasklite/backend/base.py +327 -156
  6. tasklite/backend/memory.py +261 -339
  7. tasklite/backend/sqlite_backend.py +416 -488
  8. tasklite/edit.py +1276 -0
  9. tasklite/engine/__init__.py +6 -7
  10. tasklite/engine/_worker_bootstrap.py +221 -0
  11. tasklite/engine/_worker_runtime.py +229 -0
  12. tasklite/engine/admission.py +20 -114
  13. tasklite/engine/authorization.py +989 -0
  14. tasklite/engine/channel.py +531 -468
  15. tasklite/engine/completion.py +193 -275
  16. tasklite/engine/config.py +5 -11
  17. tasklite/engine/dispatch.py +299 -384
  18. tasklite/engine/governor.py +134 -69
  19. tasklite/engine/in_flight.py +20 -88
  20. tasklite/engine/launcher.py +1173 -0
  21. tasklite/engine/recovery.py +147 -100
  22. tasklite/engine/resource.py +50 -103
  23. tasklite/engine/runtime.py +158 -525
  24. tasklite/engine/scheduler.py +9 -46
  25. tasklite/engine/session.py +60 -15
  26. tasklite/engine/store.py +235 -462
  27. tasklite/engine/types.py +29 -40
  28. tasklite/engine/wait.py +8 -0
  29. tasklite/exceptions.py +0 -1
  30. tasklite/models/artifact.py +84 -62
  31. tasklite/models/context.py +37 -30
  32. tasklite/models/graph.py +114 -0
  33. tasklite/models/job.py +3 -5
  34. tasklite/models/records.py +482 -0
  35. tasklite/models/state.py +19 -125
  36. tasklite/models/trigger.py +63 -3
  37. tasklite/pipeline.py +92 -100
  38. tasklite/resource.py +79 -2
  39. tasklite/snapshot.py +608 -405
  40. tasklite/testing.py +424 -11
  41. tasklite/utils/artifact.py +1091 -179
  42. tasklite/utils/encoding.py +21 -40
  43. tasklite/utils/ipc.py +49 -1
  44. tasklite/utils/lockfile.py +50 -19
  45. tasklite/wrappers/__init__.py +1 -1
  46. tasklite/wrappers/discovery.py +13 -16
  47. tasklite/wrappers/http.py +77 -43
  48. {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev1.dist-info}/METADATA +22 -16
  49. tasklite_engine-3.0.0.dev1.dist-info/RECORD +60 -0
  50. tasklite/contrib/__init__.py +0 -7
  51. tasklite/engine/execution_access.py +0 -39
  52. tasklite/engine/files.py +0 -52
  53. tasklite/engine/ops.py +0 -25
  54. tasklite/engine/selection.py +0 -186
  55. tasklite/hooks.py +0 -49
  56. tasklite/triggers.py +0 -47
  57. tasklite_engine-3.0.0.dev0.dist-info/RECORD +0 -58
  58. {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev1.dist-info}/WHEEL +0 -0
  59. {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev1.dist-info}/licenses/LICENSE +0 -0
  60. {tasklite_engine-3.0.0.dev0.dist-info → tasklite_engine-3.0.0.dev1.dist-info}/top_level.txt +0 -0
tasklite/edit.py ADDED
@@ -0,0 +1,1276 @@
1
+ """原子图修整事务上下文(EditTransaction,ADR-0012 §3.1)。
2
+
3
+ 提供 Run 外唯一的状态图增、删、替换与纯状态流转事务:
4
+ - 内存通过轻量三表视图容器 ``_GraphTables`` 维护基准态与工作图(queue / successes / failed)
5
+ + 待补写遗留 running 失败 Attempt;
6
+ - 仅强制维护 Schema 6 固有的 ``successes ∩ failed == ∅`` 互斥不变式;
7
+ - ``set_status`` 与 ``remove`` 零依赖 ``TaskRegistry``(空实例与 CLI 可直接使用);
8
+ - 退出提交期单次全量攒错(防删出新孤儿、活跃/成功/触碰节点零孤儿与无环、
9
+ ``from_output`` 契约闭合、非执行 ``succeeded`` 物理产出在场),全部通过后经
10
+ ``GraphEditCommit`` 单写事务原子落盘。
11
+ """
12
+ from __future__ import annotations
13
+
14
+ from collections import defaultdict
15
+ from collections.abc import Callable, Collection, Mapping
16
+ import copy
17
+ from dataclasses import dataclass, field
18
+ import logging
19
+ import sys
20
+ from typing import Any, Literal
21
+
22
+ from .backend.base import GraphEditCommit, RunningAttemptRecovery
23
+ from .engine.recovery import build_unsettled_running_recovery
24
+ from .engine.store import StateStore
25
+ from .exceptions import TaskLiteError
26
+ from .models.graph import build_dependents_index, collect_downstream, find_cycle_components
27
+ from .models.job import Job
28
+ from .models.records import (
29
+ build_manual_failure_entry,
30
+ build_manual_success_record,
31
+ extract_job_snapshot_from_archive,
32
+ )
33
+ from .snapshot import StateSnapshot
34
+ from .utils.encoding import parse_job_uid
35
+
36
+ logger = logging.getLogger("tasklite")
37
+
38
+ _VALID_ADD_STATUSES = frozenset({"pending", "succeeded", "failed"})
39
+ _VALID_SET_STATUSES = frozenset({"pending", "failed"})
40
+ _VALID_REMOVE_ENTRIES = frozenset({"queue", "successes", "failures"})
41
+ _STATUS_ORDER = ("pending", "running", "succeeded", "failed")
42
+
43
+
44
+ @dataclass
45
+ class _QueueSlot:
46
+ """内存工作图队列槽位。
47
+
48
+ ``queue_position`` 为非 ``None`` 时表示未触碰的基准行(提交时零扰动);
49
+ 任意原语写入或更新队列时将其置为 ``None``(提交时按写入序排入队尾)。
50
+ """
51
+
52
+ job_uid: str
53
+ job_snapshot: dict[str, Any]
54
+ status: Literal["pending", "running"] = "pending"
55
+ execution_id: str | None = None
56
+ run_id: str | None = None
57
+ attempt_no: int | None = None
58
+ started_at: str | None = None
59
+ queue_position: int | None = None
60
+
61
+
62
+ @dataclass
63
+ class _GraphTables:
64
+ """轻量三表视图容器,统一承载 ``queue > successes > failed`` 优先级查询与投影。"""
65
+
66
+ queue: dict[str, _QueueSlot] = field(default_factory=dict)
67
+ successes: dict[str, dict[str, Any]] = field(default_factory=dict)
68
+ failed: dict[str, tuple[dict[str, Any], dict[str, Any] | None]] = field(default_factory=dict)
69
+
70
+ def all_uids(self) -> set[str]:
71
+ return set(self.queue) | set(self.successes) | set(self.failed)
72
+
73
+ def __contains__(self, uid: object) -> bool:
74
+ return isinstance(uid, str) and (
75
+ uid in self.queue or uid in self.successes or uid in self.failed
76
+ )
77
+
78
+ def effective_status(self, uid: str) -> Literal["pending", "running", "succeeded", "failed"] | None:
79
+ slot = self.queue.get(uid)
80
+ if slot is not None:
81
+ return slot.status
82
+ if uid in self.successes:
83
+ return "succeeded"
84
+ if uid in self.failed:
85
+ return "failed"
86
+ return None
87
+
88
+ def effective_snapshot(self, uid: str) -> dict[str, Any] | None:
89
+ slot = self.queue.get(uid)
90
+ if slot is not None:
91
+ return copy.deepcopy(slot.job_snapshot)
92
+ if uid in self.successes:
93
+ return extract_job_snapshot_from_archive(
94
+ uid, self.successes[uid], fill_missing_identity=True
95
+ )
96
+ if uid in self.failed:
97
+ meta, payload = self.failed[uid]
98
+ return extract_job_snapshot_from_archive(
99
+ uid, meta, payload=payload, fill_missing_identity=True
100
+ )
101
+ return None
102
+
103
+ def count_statuses(self) -> dict[str, int]:
104
+ counts = {s: 0 for s in _STATUS_ORDER}
105
+ for uid in self.all_uids():
106
+ st = self.effective_status(uid)
107
+ if st in counts:
108
+ counts[st] += 1
109
+ return counts
110
+
111
+ def to_snapshot(self, *, attempts: list[dict[str, Any]], source: str) -> StateSnapshot:
112
+ queue_rows = [
113
+ {
114
+ "job_uid": slot.job_uid,
115
+ "job": copy.deepcopy(slot.job_snapshot),
116
+ "status": slot.status,
117
+ "run_id": slot.run_id,
118
+ "attempt_no": slot.attempt_no,
119
+ "started_at": slot.started_at,
120
+ }
121
+ for slot in self.queue.values()
122
+ ]
123
+ return StateSnapshot._from_tables(
124
+ queue_rows=queue_rows,
125
+ successes=copy.deepcopy(self.successes),
126
+ failed=copy.deepcopy(self.failed),
127
+ attempts=attempts,
128
+ source=source,
129
+ )
130
+
131
+
132
+ @dataclass(frozen=True)
133
+ class _ValidationReport:
134
+ """闭环体检结果:硬错误、OS 异常与只读告警。"""
135
+
136
+ errors: tuple[str, ...]
137
+ os_errors: tuple[str, ...]
138
+ warnings: tuple[str, ...]
139
+
140
+
141
+ def _validate_uid(uid: Any, *, param_name: str = "uid") -> str:
142
+ """校验 canonical 'task_type::job_id' 形态,非法一律抛 TaskLiteError。"""
143
+ if not isinstance(uid, str) or not uid:
144
+ raise TaskLiteError(f"{param_name} must be a non-empty str, got {uid!r}")
145
+ try:
146
+ parse_job_uid(uid)
147
+ except Exception as exc:
148
+ raise TaskLiteError(
149
+ f"{param_name} must be a valid canonical 'task_type::job_id' str, got {uid!r}"
150
+ ) from exc
151
+ return uid
152
+
153
+
154
+ def _format_signed(delta: int) -> str:
155
+ if delta > 0:
156
+ return f"+{delta}"
157
+ if delta < 0:
158
+ return str(delta)
159
+ return "+0"
160
+
161
+
162
+ def _summarize_file_entry(spec: Any) -> str:
163
+ if not isinstance(spec, Mapping):
164
+ return repr(spec)
165
+ role = spec.get("role", "output")
166
+ if spec.get("producer_uid") is not None:
167
+ return f"from_output({spec['producer_uid']!r}, {spec.get('output_name')!r}, role={role!r})"
168
+ return f"{spec.get('path')!r} (role={role!r})"
169
+
170
+
171
+ class EditTransaction:
172
+ """Run 外原子图修整事务上下文管理器(由 ``TaskLite.edit()`` 创建)。"""
173
+
174
+ def __init__(
175
+ self,
176
+ store: StateStore,
177
+ *,
178
+ dry_run: bool = True,
179
+ note: str | None = None,
180
+ ensure_active: Callable[[str], None] | None = None,
181
+ set_editing: Callable[[bool], None] | None = None,
182
+ ) -> None:
183
+ self._store = store
184
+ self._dry_run = dry_run
185
+ self._note = note
186
+ self._ensure_active = ensure_active
187
+ self._set_editing = set_editing
188
+
189
+ self._entered = False
190
+ self._active = False
191
+ self._exited = False
192
+ self._lock_cm: Any = None
193
+
194
+ # 基准只读三表视图与可变工作三表视图
195
+ self._base = _GraphTables()
196
+ self._work = _GraphTables()
197
+ self._base_running_rows: dict[str, dict[str, Any]] = {}
198
+ self._base_attempts: list[dict[str, Any]] = []
199
+ self._job_sequences: dict[str, int] = {}
200
+ self._settled_attempt_nos: dict[str, frozenset[int]] = {}
201
+ self._recovery_attempts: dict[str, RunningAttemptRecovery] = {}
202
+
203
+ # 变更与告警追踪(用于闭环校验与结构化 diff)
204
+ self._touched_uids: set[str] = set()
205
+ self._added_or_replaced_uids: set[str] = set()
206
+ self._written_succeeded_uids: set[str] = set()
207
+ self._partial_removed_uids: set[str] = set()
208
+ self._origin_of: dict[str, str] = {}
209
+ self._replaced_in_place_uids: set[str] = set()
210
+
211
+ self._version = 0
212
+ self._logged_warnings_version = -1
213
+ self._before_snapshot: StateSnapshot | None = None
214
+ self._after_cache: tuple[int, StateSnapshot] | None = None
215
+
216
+ # ── 上下文管理器生命周期 ───────────────────────────────────────────
217
+
218
+ def __enter__(self) -> EditTransaction:
219
+ if self._entered or self._exited:
220
+ raise TaskLiteError("EditTransaction cannot be entered more than once")
221
+ if self._ensure_active is not None:
222
+ self._ensure_active("edit")
223
+
224
+ lock_cm = self._store.exclusive_access()
225
+ lock_cm.__enter__()
226
+ self._lock_cm = lock_cm
227
+ editing_marked = False
228
+ try:
229
+ if self._set_editing is not None:
230
+ self._set_editing(True)
231
+ editing_marked = True
232
+ snap = self._store.load_consistent_snapshot()
233
+ successes = snap["successes"]
234
+ failed = snap["failed"]
235
+ overlap = successes.keys() & failed.keys()
236
+ if overlap:
237
+ raise TaskLiteError(
238
+ f"Invariant conflict: Jobs have both terminal records: {overlap}"
239
+ )
240
+
241
+ failure_payloads = snap["failure_payloads"]
242
+ self._base_attempts = copy.deepcopy(snap["attempts"])
243
+ self._job_sequences = dict(snap.get("job_sequences") or {})
244
+
245
+ settled_map: dict[str, set[int]] = defaultdict(set)
246
+ for att in self._base_attempts:
247
+ att_uid = att.get("job_uid")
248
+ att_no = att.get("attempt_no")
249
+ if isinstance(att_uid, str) and isinstance(att_no, int):
250
+ settled_map[att_uid].add(att_no)
251
+ self._settled_attempt_nos = {
252
+ uid: frozenset(nos) for uid, nos in settled_map.items()
253
+ }
254
+
255
+ for row in snap["queue_jobs"]:
256
+ uid = row["job_uid"]
257
+ st: Literal["pending", "running"] = (
258
+ "running" if row.get("status") == "running" else "pending"
259
+ )
260
+ slot = _QueueSlot(
261
+ job_uid=uid,
262
+ job_snapshot=copy.deepcopy(row["job"]),
263
+ status=st,
264
+ execution_id=row.get("execution_id"),
265
+ run_id=row.get("run_id"),
266
+ attempt_no=row.get("attempt_no"),
267
+ started_at=row.get("started_at"),
268
+ queue_position=row.get("queue_position"),
269
+ )
270
+ self._base.queue[uid] = copy.deepcopy(slot)
271
+ self._work.queue[uid] = slot
272
+ if st == "running":
273
+ self._base_running_rows[uid] = copy.deepcopy(row)
274
+
275
+ for uid, meta in successes.items():
276
+ self._base.successes[uid] = copy.deepcopy(meta)
277
+ self._work.successes[uid] = copy.deepcopy(meta)
278
+
279
+ for uid, meta in failed.items():
280
+ payload = failure_payloads.get(uid)
281
+ self._base.failed[uid] = (copy.deepcopy(meta), copy.deepcopy(payload))
282
+ self._work.failed[uid] = (copy.deepcopy(meta), copy.deepcopy(payload))
283
+
284
+ self._origin_of = {uid: uid for uid in self._base.all_uids()}
285
+ self._before_snapshot = self._base.to_snapshot(
286
+ attempts=copy.deepcopy(self._base_attempts),
287
+ source="edit:before",
288
+ )
289
+ self._entered = True
290
+ self._active = True
291
+ return self
292
+ except BaseException:
293
+ if editing_marked and self._set_editing is not None:
294
+ self._set_editing(False)
295
+ self._release_lock(*sys.exc_info())
296
+ raise
297
+
298
+ def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Literal[False]:
299
+ self._active = False
300
+ self._exited = True
301
+ try:
302
+ if exc_type is not None:
303
+ return False
304
+
305
+ report = self._validate(capture_os_errors=False)
306
+ self._emit_warnings(report.warnings)
307
+ if report.errors:
308
+ summary = "\n".join(f" - {err}" for err in report.errors)
309
+ raise TaskLiteError(
310
+ f"EditTransaction validation failed ({len(report.errors)} error(s)):\n{summary}"
311
+ )
312
+
313
+ if not self._dry_run:
314
+ commit = self._build_commit()
315
+ self._store.apply_graph_edit(commit)
316
+
317
+ # 冻结最终 after 快照(退出后永久可读)
318
+ _ = self.after
319
+ return False
320
+ finally:
321
+ try:
322
+ if self._set_editing is not None:
323
+ self._set_editing(False)
324
+ finally:
325
+ self._release_lock(exc_type, exc_val, exc_tb)
326
+
327
+ def _release_lock(self, exc_type: Any = None, exc_val: Any = None, exc_tb: Any = None) -> None:
328
+ lock_cm = self._lock_cm
329
+ if lock_cm is not None:
330
+ self._lock_cm = None
331
+ lock_cm.__exit__(exc_type, exc_val, exc_tb)
332
+
333
+ def _require_entered(self) -> None:
334
+ if not self._entered:
335
+ raise TaskLiteError("EditTransaction must be used within a 'with' context")
336
+
337
+ def _require_active(self, op_name: str) -> None:
338
+ if not self._entered:
339
+ raise TaskLiteError(
340
+ f"Cannot call {op_name}() before entering EditTransaction context"
341
+ )
342
+ if not self._active:
343
+ raise TaskLiteError(
344
+ f"Cannot call {op_name}() after EditTransaction has exited"
345
+ )
346
+
347
+ def _bump_version(self) -> None:
348
+ self._version += 1
349
+ self._after_cache = None
350
+
351
+ # ── 工作图遍历与遗留 running 恢复准备 ──────────────────────────────
352
+
353
+ def _collect_downstream_uids(self, root_uid: str) -> list[str]:
354
+ """沿当前工作图有效快照的正向 depends_on 闭包收集全部下游 uid(确定性字典序)。"""
355
+ edges: dict[str, list[str]] = {}
356
+ for uid in self._work.all_uids():
357
+ snap = self._work.effective_snapshot(uid)
358
+ if snap is None:
359
+ continue
360
+ edges[uid] = [dep for dep in (snap.get("depends_on") or ()) if isinstance(dep, str)]
361
+ dependents = build_dependents_index(edges)
362
+ return collect_downstream(root_uid, dependents)
363
+
364
+ def _prepare_running_recovery(self, uid: str) -> RunningAttemptRecovery | None:
365
+ """若 uid 当前处于遗留 running,预校验并构造恢复记录(不产生副作用)。"""
366
+ slot = self._work.queue.get(uid)
367
+ if slot is None or slot.status != "running":
368
+ return None
369
+ if uid in self._recovery_attempts:
370
+ return self._recovery_attempts[uid]
371
+ base_row = self._base_running_rows.get(uid)
372
+ if base_row is None:
373
+ raise TaskLiteError(
374
+ f"Invariant conflict: running job {uid!r} has no baseline execution record"
375
+ )
376
+ recovery, _ = build_unsettled_running_recovery(
377
+ base_row,
378
+ attempt_sequence=self._job_sequences.get(uid, 0),
379
+ settled_attempt_nos=self._settled_attempt_nos.get(uid, frozenset()),
380
+ )
381
+ return recovery
382
+
383
+ # ── 6 个公开原语 ───────────────────────────────────────────────────
384
+
385
+ def __contains__(self, uid: object) -> bool:
386
+ """存在性查询:校验 canonical uid 语法,返回是否存在于三表工作图。"""
387
+ self._require_entered()
388
+ valid_uid = _validate_uid(uid)
389
+ return valid_uid in self._work
390
+
391
+ def add(
392
+ self,
393
+ job: Job,
394
+ *,
395
+ status: Literal["pending", "succeeded", "failed"],
396
+ ) -> None:
397
+ """纯新增节点至指定分区;同 uid 已存在或 task_type 未注册立即抛 TaskLiteError。"""
398
+ self._require_active("add")
399
+ if not isinstance(job, Job):
400
+ raise TaskLiteError(f"add() expects a Job, got {type(job).__name__}")
401
+ if type(status) is not str or status not in _VALID_ADD_STATUSES:
402
+ raise TaskLiteError(
403
+ f"status must be one of 'pending', 'succeeded', 'failed', got {status!r}"
404
+ )
405
+ uid = job.uid
406
+ if uid in self._work:
407
+ raise TaskLiteError(
408
+ f"Job {uid!r} already exists in working graph (use replace() to update it)"
409
+ )
410
+ snap = self._store.normalize_new_job_snapshot(job, caller="add")
411
+
412
+ if status == "pending":
413
+ self._work.queue[uid] = _QueueSlot(job_uid=uid, job_snapshot=snap, status="pending")
414
+ elif status == "succeeded":
415
+ self._work.successes[uid] = build_manual_success_record(
416
+ snap, path_policy=self._store.path_policy, note=self._note
417
+ )
418
+ self._written_succeeded_uids.add(uid)
419
+ else:
420
+ self._work.failed[uid] = build_manual_failure_entry(snap, note=self._note)
421
+
422
+ self._touched_uids.add(uid)
423
+ self._added_or_replaced_uids.add(uid)
424
+ self._bump_version()
425
+
426
+ def replace(
427
+ self,
428
+ old_uid: str,
429
+ new_job: Job,
430
+ *,
431
+ status: Literal["pending", "succeeded", "failed"] | None = None,
432
+ ) -> None:
433
+ """演进替换单个节点(可改名、改配置;status=None 继承原有效态,遗留 running 收敛为 failed)。"""
434
+ self._require_active("replace")
435
+ valid_old = _validate_uid(old_uid, param_name="old_uid")
436
+ if not isinstance(new_job, Job):
437
+ raise TaskLiteError(f"replace() expects a Job for new_job, got {type(new_job).__name__}")
438
+ self._replace_batch([(valid_old, new_job)], status=status, caller="replace")
439
+
440
+ def replace_many(
441
+ self,
442
+ mapping: Mapping[str, Job],
443
+ *,
444
+ status: Literal["pending", "succeeded", "failed"] | None = None,
445
+ ) -> None:
446
+ """批量演进替换(先摘除全部旧键再放入新 Job,天然支持编号顺移或互换)。"""
447
+ self._require_active("replace_many")
448
+ if not isinstance(mapping, Mapping):
449
+ raise TaskLiteError(
450
+ f"replace_many() expects a Mapping[str, Job], got {type(mapping).__name__}"
451
+ )
452
+ if status is not None and (type(status) is not str or status not in _VALID_ADD_STATUSES):
453
+ raise TaskLiteError(
454
+ f"status must be one of 'pending', 'succeeded', 'failed', or None; got {status!r}"
455
+ )
456
+ if not mapping:
457
+ return
458
+ pairs: list[tuple[str, Job]] = []
459
+ for raw_old, new_job in mapping.items():
460
+ valid_old = _validate_uid(raw_old, param_name="old_uid")
461
+ if not isinstance(new_job, Job):
462
+ raise TaskLiteError(
463
+ f"replace_many() expects Job values, got {type(new_job).__name__} for {valid_old!r}"
464
+ )
465
+ pairs.append((valid_old, new_job))
466
+ self._replace_batch(pairs, status=status, caller="replace_many")
467
+
468
+ def _replace_batch(
469
+ self,
470
+ pairs: list[tuple[str, Job]],
471
+ *,
472
+ status: Literal["pending", "succeeded", "failed"] | None,
473
+ caller: str = "replace",
474
+ ) -> None:
475
+ if status is not None and (type(status) is not str or status not in _VALID_ADD_STATUSES):
476
+ raise TaskLiteError(
477
+ f"status must be one of 'pending', 'succeeded', 'failed', or None; got {status!r}"
478
+ )
479
+
480
+ # 全量前置校验(任何错误都不留半成品变更)
481
+ seen_new_uids: set[str] = set()
482
+ old_uids = {old_uid for old_uid, _ in pairs}
483
+ prepared: list[tuple[str, str, str, str, dict[str, Any], RunningAttemptRecovery | None]] = []
484
+
485
+ # Phase 0:模拟摘除所有旧键后的剩余分区占用集合(异名替换必须清空三表以杜绝幽灵旧节点)
486
+ sim_queue = set(self._work.queue)
487
+ sim_succ = set(self._work.successes)
488
+ sim_fail = set(self._work.failed)
489
+
490
+ for old_uid, new_job in pairs:
491
+ old_status = self._work.effective_status(old_uid)
492
+ if old_status is None:
493
+ raise TaskLiteError(f"Job {old_uid!r} does not exist in working graph")
494
+ new_uid = new_job.uid
495
+ if new_uid in seen_new_uids:
496
+ raise TaskLiteError(
497
+ f"Duplicate target job UID {new_uid!r} in replace_many()"
498
+ )
499
+ seen_new_uids.add(new_uid)
500
+
501
+ snap = self._store.normalize_new_job_snapshot(new_job, caller=caller)
502
+ recovery = self._prepare_running_recovery(old_uid) if old_status == "running" else None
503
+ target_status = (
504
+ status
505
+ if status is not None
506
+ else ("failed" if old_status == "running" else old_status)
507
+ )
508
+ prepared.append((old_uid, new_uid, old_status, target_status, snap, recovery))
509
+
510
+ if new_uid != old_uid:
511
+ sim_queue.discard(old_uid)
512
+ sim_succ.discard(old_uid)
513
+ sim_fail.discard(old_uid)
514
+ elif old_status in ("pending", "running"):
515
+ sim_queue.discard(old_uid)
516
+ elif old_status == "succeeded":
517
+ sim_succ.discard(old_uid)
518
+ elif old_status == "failed":
519
+ sim_fail.discard(old_uid)
520
+
521
+ surviving_after_vacate = sim_queue | sim_succ | sim_fail
522
+ for old_uid, new_uid, _old_status, _target_status, _snap, _recovery in prepared:
523
+ if new_uid != old_uid and new_uid in surviving_after_vacate:
524
+ raise TaskLiteError(
525
+ f"Replacement target UID {new_uid!r} conflicts with existing job in working graph"
526
+ )
527
+ if new_uid not in old_uids and new_uid in self._work:
528
+ raise TaskLiteError(
529
+ f"Replacement target UID {new_uid!r} conflicts with existing job in working graph"
530
+ )
531
+
532
+ # Phase A:摘除全部旧键(异名替换清三表确保 old_uid 彻底消失;同名替换仅摘除有效态分区)
533
+ orig_for_old: dict[str, str | None] = {}
534
+ for old_uid, new_uid, prev_status, _target_status, _snap, recovery in prepared:
535
+ if recovery is not None and old_uid not in self._recovery_attempts:
536
+ self._recovery_attempts[old_uid] = recovery
537
+ if old_uid != new_uid:
538
+ self._work.queue.pop(old_uid, None)
539
+ self._work.successes.pop(old_uid, None)
540
+ self._work.failed.pop(old_uid, None)
541
+ self._written_succeeded_uids.discard(old_uid)
542
+ self._replaced_in_place_uids.discard(old_uid)
543
+ self._added_or_replaced_uids.discard(old_uid)
544
+ self._partial_removed_uids.discard(old_uid)
545
+ elif prev_status in ("pending", "running"):
546
+ self._work.queue.pop(old_uid, None)
547
+ elif prev_status == "succeeded":
548
+ self._work.successes.pop(old_uid, None)
549
+ self._written_succeeded_uids.discard(old_uid)
550
+ elif prev_status == "failed":
551
+ self._work.failed.pop(old_uid, None)
552
+
553
+ if old_uid in self._origin_of:
554
+ if old_uid not in self._work or old_uid == new_uid:
555
+ orig_for_old[old_uid] = self._origin_of.pop(old_uid)
556
+ else:
557
+ orig_for_old[old_uid] = self._origin_of[old_uid]
558
+ else:
559
+ orig_for_old[old_uid] = None
560
+
561
+ # Phase B:将全部新 Job 写入目标分区(显式 status='pending' 同步清空历史终态档案)
562
+ for old_uid, new_uid, _old_status, next_status, snap, _recovery in prepared:
563
+ if next_status == "pending":
564
+ if status is not None:
565
+ self._work.successes.pop(new_uid, None)
566
+ self._work.failed.pop(new_uid, None)
567
+ self._written_succeeded_uids.discard(new_uid)
568
+ self._work.queue.pop(new_uid, None)
569
+ self._work.queue[new_uid] = _QueueSlot(
570
+ job_uid=new_uid, job_snapshot=snap, status="pending"
571
+ )
572
+ elif next_status == "succeeded":
573
+ self._work.failed.pop(new_uid, None)
574
+ self._work.successes[new_uid] = build_manual_success_record(
575
+ snap, path_policy=self._store.path_policy, note=self._note
576
+ )
577
+ self._written_succeeded_uids.add(new_uid)
578
+ else:
579
+ self._work.successes.pop(new_uid, None)
580
+ self._written_succeeded_uids.discard(new_uid)
581
+ self._work.failed[new_uid] = build_manual_failure_entry(snap, note=self._note)
582
+
583
+ orig = orig_for_old.get(old_uid)
584
+ if orig is not None:
585
+ self._origin_of[new_uid] = orig
586
+ if new_uid == orig:
587
+ self._replaced_in_place_uids.add(new_uid)
588
+ self._touched_uids.add(old_uid)
589
+ self._touched_uids.add(new_uid)
590
+ self._added_or_replaced_uids.add(new_uid)
591
+
592
+ self._bump_version()
593
+
594
+ def set_status(
595
+ self,
596
+ uid: str,
597
+ status: Literal["pending", "failed"],
598
+ *,
599
+ recursive: bool,
600
+ ) -> None:
601
+ """纯状态流转(仅 pending/failed,零依赖 TaskRegistry,命中遗留 running 自动补写失败 Attempt)。"""
602
+ self._require_active("set_status")
603
+ valid_uid = _validate_uid(uid)
604
+ if type(status) is not str or status not in _VALID_SET_STATUSES:
605
+ raise TaskLiteError(
606
+ f"set_status() status must be 'pending' or 'failed', got {status!r}"
607
+ )
608
+ if type(recursive) is not bool:
609
+ raise TaskLiteError(f"recursive must be a bool, got {type(recursive).__name__}")
610
+ if valid_uid not in self._work:
611
+ raise TaskLiteError(f"Job {valid_uid!r} does not exist in working graph")
612
+
613
+ targets = [valid_uid]
614
+ if recursive:
615
+ targets.extend(self._collect_downstream_uids(valid_uid))
616
+
617
+ # 前置校验全部待恢复的遗留 running
618
+ prepared: list[tuple[str, dict[str, Any], RunningAttemptRecovery | None]] = []
619
+ for t_uid in targets:
620
+ snap = self._work.effective_snapshot(t_uid)
621
+ if snap is None:
622
+ continue
623
+ recovery = self._prepare_running_recovery(t_uid)
624
+ prepared.append((t_uid, snap, recovery))
625
+
626
+ for t_uid, snap, recovery in prepared:
627
+ if recovery is not None and t_uid not in self._recovery_attempts:
628
+ self._recovery_attempts[t_uid] = recovery
629
+ if status == "pending":
630
+ self._work.successes.pop(t_uid, None)
631
+ self._written_succeeded_uids.discard(t_uid)
632
+ self._work.failed.pop(t_uid, None)
633
+ self._work.queue.pop(t_uid, None)
634
+ self._work.queue[t_uid] = _QueueSlot(
635
+ job_uid=t_uid, job_snapshot=snap, status="pending"
636
+ )
637
+ else:
638
+ self._work.queue.pop(t_uid, None)
639
+ self._work.successes.pop(t_uid, None)
640
+ self._written_succeeded_uids.discard(t_uid)
641
+ self._work.failed[t_uid] = build_manual_failure_entry(snap, note=self._note)
642
+ self._touched_uids.add(t_uid)
643
+
644
+ self._bump_version()
645
+
646
+ def remove(
647
+ self,
648
+ uid: str,
649
+ *,
650
+ entries: Collection[Literal["queue", "successes", "failures"]] = (
651
+ "queue",
652
+ "successes",
653
+ "failures",
654
+ ),
655
+ recursive: bool,
656
+ ) -> int:
657
+ """按字面从指定分区移除条目(零依赖 TaskRegistry,绝不删 attempts/磁盘文件或重置序列)。"""
658
+ self._require_active("remove")
659
+ valid_uid = _validate_uid(uid)
660
+ if type(recursive) is not bool:
661
+ raise TaskLiteError(f"recursive must be a bool, got {type(recursive).__name__}")
662
+ if not isinstance(entries, Collection) or isinstance(entries, (str, bytes)):
663
+ raise TaskLiteError(
664
+ "entries must be a collection of 'queue', 'successes', 'failures', "
665
+ f"got {type(entries).__name__}"
666
+ )
667
+ entry_set = set(entries)
668
+ if not entry_set:
669
+ raise TaskLiteError("entries must not be empty")
670
+ unknown = entry_set - _VALID_REMOVE_ENTRIES
671
+ if unknown:
672
+ raise TaskLiteError(
673
+ f"entries contains unknown or forbidden target(s): {sorted(unknown)!r}; "
674
+ f"allowed: {sorted(_VALID_REMOVE_ENTRIES)!r}"
675
+ )
676
+
677
+ targets = [valid_uid]
678
+ if recursive and valid_uid in self._work:
679
+ targets.extend(self._collect_downstream_uids(valid_uid))
680
+
681
+ # 前置校验若删 queue 时命中的遗留 running
682
+ recoveries: dict[str, RunningAttemptRecovery] = {}
683
+ if "queue" in entry_set:
684
+ for t_uid in targets:
685
+ rec = self._prepare_running_recovery(t_uid)
686
+ if rec is not None:
687
+ recoveries[t_uid] = rec
688
+
689
+ removed_count = 0
690
+ is_partial = entry_set != _VALID_REMOVE_ENTRIES
691
+ for t_uid in targets:
692
+ removed_any = False
693
+ if "queue" in entry_set and t_uid in self._work.queue:
694
+ if t_uid in recoveries and t_uid not in self._recovery_attempts:
695
+ self._recovery_attempts[t_uid] = recoveries[t_uid]
696
+ del self._work.queue[t_uid]
697
+ removed_any = True
698
+ if "successes" in entry_set and t_uid in self._work.successes:
699
+ del self._work.successes[t_uid]
700
+ self._written_succeeded_uids.discard(t_uid)
701
+ removed_any = True
702
+ if "failures" in entry_set and t_uid in self._work.failed:
703
+ del self._work.failed[t_uid]
704
+ removed_any = True
705
+
706
+ if removed_any:
707
+ removed_count += 1
708
+ self._touched_uids.add(t_uid)
709
+ if t_uid not in self._work:
710
+ self._origin_of.pop(t_uid, None)
711
+ self._replaced_in_place_uids.discard(t_uid)
712
+ self._added_or_replaced_uids.discard(t_uid)
713
+ elif is_partial:
714
+ self._partial_removed_uids.add(t_uid)
715
+
716
+ if removed_count > 0:
717
+ self._bump_version()
718
+ return removed_count
719
+
720
+ # ── 快照视图与结构化 Diff ──────────────────────────────────────────
721
+
722
+ def _overlay_attempts(self) -> list[dict[str, Any]]:
723
+ combined = copy.deepcopy(self._base_attempts)
724
+ next_id = max(
725
+ (int(a.get("attempt_id") or 0) for a in combined),
726
+ default=0,
727
+ ) + 1
728
+ for rec in self._recovery_attempts.values():
729
+ combined.append({
730
+ "attempt_id": next_id,
731
+ "job_uid": rec.job_uid,
732
+ "attempt_no": rec.attempt_no,
733
+ "run_id": rec.run_id,
734
+ "outcome": "failure",
735
+ "started_at": rec.started_at,
736
+ "settled_at": rec.settled_at,
737
+ "job": copy.deepcopy(rec.job_snapshot),
738
+ "files": copy.deepcopy(rec.files),
739
+ "result": copy.deepcopy(rec.result),
740
+ "error_message": rec.error_message,
741
+ })
742
+ next_id += 1
743
+ return combined
744
+
745
+ @property
746
+ def before(self) -> StateSnapshot:
747
+ """进入事务前的只读一致基准快照(退出 with 后永久可读)。"""
748
+ self._require_entered()
749
+ assert self._before_snapshot is not None
750
+ return self._before_snapshot
751
+
752
+ @property
753
+ def after(self) -> StateSnapshot:
754
+ """当前暂存工作图的只读一致投影快照(含待补写遗留 running Attempt,退出后永久可读)。"""
755
+ self._require_entered()
756
+ if self._after_cache is not None and self._after_cache[0] == self._version:
757
+ return self._after_cache[1]
758
+ snap = self._work.to_snapshot(
759
+ attempts=self._overlay_attempts(),
760
+ source="edit:after",
761
+ )
762
+ self._after_cache = (self._version, snap)
763
+ return snap
764
+
765
+ def diff(self) -> str:
766
+ """生成面向人类的 6 段紧凑对比报告(永不因校验失败或 OSError 抛异常)。"""
767
+ self._require_entered()
768
+ report = self._validate(capture_os_errors=True)
769
+ self._emit_warnings(report.warnings)
770
+
771
+ before_counts = self._base.count_statuses()
772
+ after_counts = self._work.count_statuses()
773
+ before_total = sum(before_counts.values())
774
+ after_total = sum(after_counts.values())
775
+
776
+ mode_tag = "dry_run=True" if self._dry_run else "dry_run=False"
777
+ lines: list[str] = [f"TaskLite Edit Diff ({mode_tag}):"]
778
+ for st in _STATUS_ORDER:
779
+ b_val = before_counts[st]
780
+ a_val = after_counts[st]
781
+ lines.append(f" {st:<9}: {b_val} -> {a_val} ({_format_signed(a_val - b_val)})")
782
+ lines.append(
783
+ f" {'total':<9}: {before_total} -> {after_total} "
784
+ f"({_format_signed(after_total - before_total)})"
785
+ )
786
+ if self._recovery_attempts:
787
+ lines.append(
788
+ f" recovery_attempts: +{len(self._recovery_attempts)} "
789
+ f"({', '.join(sorted(self._recovery_attempts))})"
790
+ )
791
+
792
+ removed_uids, replaced_pairs, added_uids, status_changes = self._classify_diff_changes()
793
+
794
+ lines.append("")
795
+ lines.append("[- REMOVED]")
796
+ if not removed_uids:
797
+ lines.append(" (none)")
798
+ else:
799
+ removed_succeeded = [
800
+ u for u in removed_uids if self._base.effective_status(u) == "succeeded"
801
+ ]
802
+ removed_other = [
803
+ u for u in removed_uids if self._base.effective_status(u) != "succeeded"
804
+ ]
805
+ for u in removed_succeeded:
806
+ lines.append(f" - [succeeded] {u} (!) removed completed job")
807
+ for u in removed_other:
808
+ st = self._base.effective_status(u) or "unknown"
809
+ lines.append(f" - [{st}] {u}")
810
+
811
+ lines.append("")
812
+ lines.append("[⇄ REPLACED]")
813
+ if not replaced_pairs:
814
+ lines.append(" (none)")
815
+ else:
816
+ for orig_uid, new_uid in replaced_pairs:
817
+ header = f" ⇄ {orig_uid} -> {new_uid}" if orig_uid != new_uid else f" ⇄ {new_uid}"
818
+ b_st = self._base.effective_status(orig_uid)
819
+ a_st = self._work.effective_status(new_uid)
820
+ changes = self._format_replacement_field_diffs(orig_uid, new_uid, b_st, a_st)
821
+ if changes:
822
+ lines.append(f"{header}: " + "; ".join(changes))
823
+ else:
824
+ lines.append(f"{header}: (no field changes)")
825
+
826
+ lines.append("")
827
+ lines.append("[+ ADDED]")
828
+ if not added_uids:
829
+ lines.append(" (none)")
830
+ else:
831
+ for u in added_uids:
832
+ st = self._work.effective_status(u) or "unknown"
833
+ lines.append(f" + [{st}] {u}")
834
+
835
+ lines.append("")
836
+ lines.append("[↻ STATUS]")
837
+ if not status_changes:
838
+ lines.append(" (none)")
839
+ else:
840
+ for u, prev_st, next_st in status_changes:
841
+ lines.append(f" ↻ {u}: {prev_st} -> {next_st}")
842
+
843
+ lines.append("")
844
+ lines.append("[WARNINGS]")
845
+ if not report.warnings:
846
+ lines.append(" (none)")
847
+ else:
848
+ for warn in report.warnings:
849
+ lines.append(f" ! {warn}")
850
+
851
+ lines.append("")
852
+ lines.append("[VALIDATION]")
853
+ if not report.errors and not report.os_errors:
854
+ lines.append(" PASS")
855
+ else:
856
+ if report.errors:
857
+ lines.append(f" FAIL ({len(report.errors)} error(s)):")
858
+ for err in report.errors:
859
+ lines.append(f" - {err}")
860
+ if report.os_errors:
861
+ lines.append(f" OS ERROR ({len(report.os_errors)} error(s)):")
862
+ for oerr in report.os_errors:
863
+ lines.append(f" - {oerr}")
864
+
865
+ return "\n".join(lines)
866
+
867
+ def _classify_diff_changes(
868
+ self,
869
+ ) -> tuple[list[str], list[tuple[str, str]], list[str], list[tuple[str, str, str]]]:
870
+ g_before = self._base.all_uids()
871
+ g_after = self._work.all_uids()
872
+
873
+ surviving_origins = {
874
+ orig for cur, orig in self._origin_of.items() if cur in g_after
875
+ }
876
+ removed_uids = sorted(g_before - surviving_origins)
877
+
878
+ replaced_pairs: list[tuple[str, str]] = []
879
+ replaced_cur_uids: set[str] = set()
880
+ for cur in sorted(g_after):
881
+ orig = self._origin_of.get(cur)
882
+ if orig is not None and (cur != orig or cur in self._replaced_in_place_uids):
883
+ replaced_pairs.append((orig, cur))
884
+ replaced_cur_uids.add(cur)
885
+
886
+ added_uids = sorted(u for u in g_after if u not in self._origin_of)
887
+
888
+ status_changes: list[tuple[str, str, str]] = []
889
+ for u in sorted(g_after & g_before):
890
+ if u in replaced_cur_uids:
891
+ continue
892
+ b_st = self._base.effective_status(u)
893
+ a_st = self._work.effective_status(u)
894
+ if b_st is not None and a_st is not None and b_st != a_st:
895
+ status_changes.append((u, b_st, a_st))
896
+
897
+ return removed_uids, replaced_pairs, added_uids, status_changes
898
+
899
+ def _file_entries_equivalent(self, before: Any, after: Any) -> bool:
900
+ """比对 files 单条配置:具体路径若仅写法不同但指向同一规范路径则视为等价。"""
901
+ if before == after:
902
+ return True
903
+ if not isinstance(before, Mapping) or not isinstance(after, Mapping):
904
+ return False
905
+ if before.get("producer_uid") is not None or after.get("producer_uid") is not None:
906
+ return False
907
+ before_rest = {k: v for k, v in before.items() if k != "path"}
908
+ after_rest = {k: v for k, v in after.items() if k != "path"}
909
+ if before_rest != after_rest:
910
+ return False
911
+ b_path = before.get("path")
912
+ a_path = after.get("path")
913
+ if isinstance(b_path, str) and b_path and isinstance(a_path, str) and a_path:
914
+ try:
915
+ b_key = self._store.path_policy.inspect(b_path, mode="lookup").comparison_key
916
+ a_key = self._store.path_policy.inspect(a_path, mode="lookup").comparison_key
917
+ return b_key == a_key
918
+ except (ValueError, OSError):
919
+ return False
920
+ return False
921
+
922
+ def _format_replacement_field_diffs(
923
+ self,
924
+ orig_uid: str,
925
+ new_uid: str,
926
+ before_status: str | None,
927
+ after_status: str | None,
928
+ ) -> list[str]:
929
+ parts: list[str] = []
930
+ if before_status != after_status:
931
+ parts.append(f"status: {before_status} -> {after_status}")
932
+ b_rec = self.before.get_job(orig_uid)
933
+ a_rec = self.after.get_job(new_uid)
934
+ b_snap: Mapping[str, Any] = b_rec["job"] if b_rec is not None else {}
935
+ a_snap: Mapping[str, Any] = a_rec["job"] if a_rec is not None else {}
936
+
937
+ if b_snap.get("depends_on") != a_snap.get("depends_on"):
938
+ parts.append(f"depends_on: {b_snap.get('depends_on')} -> {a_snap.get('depends_on')}")
939
+
940
+ b_files = b_snap.get("files") or {}
941
+ a_files = a_snap.get("files") or {}
942
+ if b_files != a_files:
943
+ file_diffs: list[str] = []
944
+ for key in sorted(set(b_files) | set(a_files)):
945
+ if key not in b_files:
946
+ file_diffs.append(f"+{key}={_summarize_file_entry(a_files[key])}")
947
+ elif key not in a_files:
948
+ file_diffs.append(f"-{key}")
949
+ elif not self._file_entries_equivalent(b_files[key], a_files[key]):
950
+ file_diffs.append(
951
+ f"{key}: {_summarize_file_entry(b_files[key])} -> "
952
+ f"{_summarize_file_entry(a_files[key])}"
953
+ )
954
+ if file_diffs:
955
+ parts.append("files{" + ", ".join(file_diffs) + "}")
956
+
957
+ b_payload = b_snap.get("payload") or {}
958
+ a_payload = a_snap.get("payload") or {}
959
+ if b_payload != a_payload:
960
+ changed_keys = sorted(
961
+ k for k in (set(b_payload) | set(a_payload))
962
+ if b_payload.get(k) != a_payload.get(k)
963
+ )
964
+ parts.append(f"payload keys changed: {changed_keys}")
965
+
966
+ for cfg_key in ("resources", "max_retries_per_run", "timeout_seconds", "trigger"):
967
+ if b_snap.get(cfg_key) != a_snap.get(cfg_key):
968
+ parts.append(f"{cfg_key}: {b_snap.get(cfg_key)!r} -> {a_snap.get(cfg_key)!r}")
969
+
970
+ return parts
971
+
972
+ def _emit_warnings(self, warnings: tuple[str, ...]) -> None:
973
+ if self._logged_warnings_version == self._version:
974
+ return
975
+ self._logged_warnings_version = self._version
976
+ for warn in warnings:
977
+ logger.warning("TaskLite edit warning: %s", warn)
978
+
979
+ # ── 4 项硬 Error 单次全量攒错 + 4 类只读 Warning ──────────────────
980
+
981
+ def _validate(self, *, capture_os_errors: bool) -> _ValidationReport:
982
+ errors: list[str] = []
983
+ os_errors: list[str] = []
984
+ warnings: list[str] = []
985
+
986
+ g_before = self._base.all_uids()
987
+ g_after = self._work.all_uids()
988
+
989
+ after_status: dict[str, str] = {}
990
+ after_snaps: dict[str, dict[str, Any]] = {}
991
+ for uid in g_after:
992
+ st = self._work.effective_status(uid)
993
+ snap = self._work.effective_snapshot(uid)
994
+ if st is not None:
995
+ after_status[uid] = st
996
+ if snap is not None:
997
+ after_snaps[uid] = snap
998
+
999
+ # ── 硬 Error 1:防删出新孤儿(存活节点原本存在的上游不可消失)
1000
+ reported_missing_edges: set[tuple[str, str]] = set()
1001
+ for u in sorted(g_after & g_before):
1002
+ b_snap = self._base.effective_snapshot(u)
1003
+ a_snap = after_snaps.get(u)
1004
+ if b_snap is None or a_snap is None:
1005
+ continue
1006
+ before_deps = set(b_snap.get("depends_on") or ())
1007
+ for p in a_snap.get("depends_on") or ():
1008
+ if p in before_deps and p in g_before and p not in g_after:
1009
+ reported_missing_edges.add((u, p))
1010
+ errors.append(
1011
+ f"Surviving job {u!r} lost existing dependency {p!r} "
1012
+ f"(upstream was removed without updating or removing {u!r})"
1013
+ )
1014
+
1015
+ # ── 硬 Error 2:活跃/成功/add-replace 触碰节点零悬空依赖 + 迭代式无环
1016
+ checked_nodes: set[str] = {
1017
+ u
1018
+ for u in g_after
1019
+ if after_status.get(u) in ("pending", "running", "succeeded")
1020
+ or u in self._added_or_replaced_uids
1021
+ }
1022
+ for u in sorted(checked_nodes):
1023
+ a_snap = after_snaps.get(u)
1024
+ if a_snap is None:
1025
+ continue
1026
+ for p in a_snap.get("depends_on") or ():
1027
+ if p not in g_after and (u, p) not in reported_missing_edges:
1028
+ reported_missing_edges.add((u, p))
1029
+ errors.append(
1030
+ f"Job {u!r} (status={after_status.get(u)}) references "
1031
+ f"missing dependency {p!r}"
1032
+ )
1033
+
1034
+ edges = {
1035
+ u: [p for p in (after_snaps[u].get("depends_on") or ()) if isinstance(p, str)]
1036
+ for u in g_after
1037
+ if u in after_snaps
1038
+ }
1039
+ for cycle in find_cycle_components(g_after, edges):
1040
+ if any(node in checked_nodes for node in cycle):
1041
+ errors.append(
1042
+ f"Dependency cycle detected involving: {', '.join(cycle)}"
1043
+ )
1044
+
1045
+ # ── 硬 Error 3:from_output(p, key) 契约闭合 + Warning #4(动态声明提示)
1046
+ for u in sorted(checked_nodes):
1047
+ a_snap = after_snaps.get(u)
1048
+ if a_snap is None:
1049
+ continue
1050
+ u_deps = set(a_snap.get("depends_on") or ())
1051
+ u_files = a_snap.get("files") or {}
1052
+ if not isinstance(u_files, Mapping):
1053
+ continue
1054
+ for fname, raw_spec in u_files.items():
1055
+ if not isinstance(raw_spec, Mapping):
1056
+ continue
1057
+ p = raw_spec.get("producer_uid")
1058
+ if p is None:
1059
+ continue
1060
+ key = raw_spec.get("output_name")
1061
+ if p not in u_deps:
1062
+ errors.append(
1063
+ f"Job {u!r} file {fname!r} references from_output({p!r}, {key!r}), "
1064
+ f"but {p!r} is not in direct depends_on"
1065
+ )
1066
+ if p not in g_after:
1067
+ errors.append(
1068
+ f"Job {u!r} file {fname!r} references from_output({p!r}, {key!r}), "
1069
+ f"but producer {p!r} does not exist"
1070
+ )
1071
+ continue
1072
+
1073
+ p_status = after_status.get(p)
1074
+ if p_status == "succeeded":
1075
+ succ_meta = self._work.successes.get(p) or {}
1076
+ p_outer_files = succ_meta.get("files") or {}
1077
+ p_artifacts = succ_meta.get("artifacts") or {}
1078
+ file_desc = (
1079
+ p_outer_files.get(key)
1080
+ if isinstance(p_outer_files, Mapping)
1081
+ else None
1082
+ )
1083
+ art_desc = (
1084
+ p_artifacts.get(key)
1085
+ if isinstance(p_artifacts, Mapping)
1086
+ else None
1087
+ )
1088
+ valid_published = False
1089
+ if isinstance(file_desc, Mapping):
1090
+ valid_published = (
1091
+ file_desc.get("role") == "output"
1092
+ and not bool(file_desc.get("delete_on_success", False))
1093
+ and isinstance(file_desc.get("path"), str)
1094
+ and bool(file_desc.get("path"))
1095
+ and isinstance(art_desc, Mapping)
1096
+ and isinstance(art_desc.get("path"), str)
1097
+ and bool(art_desc.get("path"))
1098
+ )
1099
+ elif isinstance(art_desc, Mapping):
1100
+ valid_published = isinstance(art_desc.get("path"), str) and bool(
1101
+ art_desc.get("path")
1102
+ )
1103
+ if not valid_published:
1104
+ errors.append(
1105
+ f"Job {u!r} file {fname!r} references from_output({p!r}, {key!r}), "
1106
+ f"but succeeded producer {p!r} did not publish retained output {key!r}"
1107
+ )
1108
+ else:
1109
+ p_snap = after_snaps.get(p) or {}
1110
+ p_static_files = p_snap.get("files") or {}
1111
+ if isinstance(p_static_files, Mapping) and key in p_static_files:
1112
+ static_desc = p_static_files[key]
1113
+ if (
1114
+ not isinstance(static_desc, Mapping)
1115
+ or static_desc.get("role") != "output"
1116
+ or bool(static_desc.get("delete_on_success", False))
1117
+ ):
1118
+ errors.append(
1119
+ f"Job {u!r} file {fname!r} references from_output({p!r}, {key!r}), "
1120
+ f"but producer {p!r} statically declares {key!r} as non-retained "
1121
+ f"or non-output"
1122
+ )
1123
+ else:
1124
+ warnings.append(
1125
+ f"Job {u!r} file {fname!r} references from_output({p!r}, {key!r}), "
1126
+ f"which is not statically declared on non-succeeded producer {p!r} "
1127
+ f"(relies on runtime ctx.declare_file)"
1128
+ )
1129
+
1130
+ # ── 硬 Error 4:本次 add/replace 最终处于 succeeded 的保留型 output 物理在场
1131
+ path_policy = self._store.path_policy
1132
+ for uid in sorted(self._written_succeeded_uids):
1133
+ if after_status.get(uid) != "succeeded":
1134
+ continue
1135
+ manual_succ_meta = self._work.successes.get(uid)
1136
+ if manual_succ_meta is None:
1137
+ continue
1138
+ snap = manual_succ_meta.get("job_snapshot") or {}
1139
+ raw_files = snap.get("files") or {}
1140
+ if not isinstance(raw_files, Mapping):
1141
+ continue
1142
+ for fname, raw_spec in raw_files.items():
1143
+ if not isinstance(raw_spec, Mapping):
1144
+ continue
1145
+ if raw_spec.get("role") != "output" or bool(
1146
+ raw_spec.get("delete_on_success", False)
1147
+ ):
1148
+ continue
1149
+ raw_path = raw_spec.get("path")
1150
+ if not isinstance(raw_path, str) or not raw_path:
1151
+ errors.append(
1152
+ f"Manual succeeded job {uid!r} output {fname!r} has no concrete path"
1153
+ )
1154
+ continue
1155
+ try:
1156
+ inspected = path_policy.inspect(raw_path, mode="strict")
1157
+ except ValueError as exc:
1158
+ errors.append(
1159
+ f"Manual succeeded job {uid!r} output {fname!r} failed path check: {exc}"
1160
+ )
1161
+ continue
1162
+ except OSError as exc:
1163
+ if capture_os_errors:
1164
+ os_errors.append(
1165
+ f"Manual succeeded job {uid!r} output {fname!r} OS error: {exc}"
1166
+ )
1167
+ continue
1168
+ raise
1169
+ if not inspected.exists:
1170
+ errors.append(
1171
+ f"Manual succeeded job {uid!r} output {fname!r} does not exist on disk: "
1172
+ f"{inspected.canonical_path}"
1173
+ )
1174
+ else:
1175
+ # 验盘确认的规范路径当场同步回填至外层 files/artifacts 并失效 after 缓存
1176
+ canonical_path = inspected.canonical_path
1177
+ outer_files = manual_succ_meta.setdefault("files", {})
1178
+ artifacts = manual_succ_meta.setdefault("artifacts", {})
1179
+ changed = False
1180
+ existing_file = outer_files.get(fname)
1181
+ if isinstance(existing_file, dict) and existing_file.get("path") != canonical_path:
1182
+ existing_file["path"] = canonical_path
1183
+ changed = True
1184
+ existing_art = artifacts.get(fname)
1185
+ if not isinstance(existing_art, dict) or existing_art.get("path") != canonical_path:
1186
+ artifacts[fname] = {"path": canonical_path}
1187
+ changed = True
1188
+ if changed:
1189
+ self._after_cache = None
1190
+
1191
+ # ── 只读 Warning #1 / #2 / #3(Warning #4 已在 Error 3 循环收集)
1192
+ removed_uids, _, _, _ = self._classify_diff_changes()
1193
+ for uid in removed_uids:
1194
+ if self._base.effective_status(uid) == "succeeded":
1195
+ warnings.append(f"Removing completed [succeeded] job {uid!r}")
1196
+
1197
+ for uid in sorted(self._partial_removed_uids):
1198
+ if uid not in g_after:
1199
+ continue
1200
+ remaining_parts: list[str] = []
1201
+ if uid in self._work.queue:
1202
+ remaining_parts.append("queue")
1203
+ if uid in self._work.successes:
1204
+ remaining_parts.append("successes")
1205
+ if uid in self._work.failed:
1206
+ remaining_parts.append("failures")
1207
+ if remaining_parts:
1208
+ warnings.append(
1209
+ f"Job {uid!r} was removed from selected partition(s) but still remains in "
1210
+ f"{remaining_parts} (effective status: {after_status.get(uid)})"
1211
+ )
1212
+
1213
+ for uid in sorted(self._touched_uids):
1214
+ if after_status.get(uid) != "pending":
1215
+ continue
1216
+ archives: list[str] = []
1217
+ if uid in self._work.successes:
1218
+ archives.append("successes")
1219
+ if uid in self._work.failed:
1220
+ archives.append("failures")
1221
+ if archives:
1222
+ warnings.append(
1223
+ f"Pending job {uid!r} also has historical {archives} archive "
1224
+ f"(next run() will evaluate Trigger against residual archive)"
1225
+ )
1226
+
1227
+ return _ValidationReport(
1228
+ errors=tuple(errors),
1229
+ os_errors=tuple(os_errors),
1230
+ warnings=tuple(warnings),
1231
+ )
1232
+
1233
+ # ── O(Δ) 声明式提交载荷构造 ───────────────────────────────────────
1234
+
1235
+ def _build_commit(self) -> GraphEditCommit:
1236
+ queue_writes: dict[str, dict[str, Any] | None] = {}
1237
+ for uid in self._base.queue:
1238
+ if uid not in self._work.queue:
1239
+ queue_writes[uid] = None
1240
+ for uid, slot in self._work.queue.items():
1241
+ base_slot = self._base.queue.get(uid)
1242
+ if (
1243
+ base_slot is None
1244
+ or slot.queue_position is None
1245
+ or slot.status != base_slot.status
1246
+ or slot.job_snapshot != base_slot.job_snapshot
1247
+ ):
1248
+ queue_writes[uid] = copy.deepcopy(slot.job_snapshot)
1249
+
1250
+ success_writes: dict[str, dict[str, Any] | None] = {}
1251
+ for uid in self._base.successes:
1252
+ if uid not in self._work.successes:
1253
+ success_writes[uid] = None
1254
+ for uid, meta in self._work.successes.items():
1255
+ if uid not in self._base.successes or meta != self._base.successes[uid]:
1256
+ success_writes[uid] = copy.deepcopy(meta)
1257
+
1258
+ failed_writes: dict[str, tuple[dict[str, Any], dict[str, Any] | None] | None] = {}
1259
+ for uid in self._base.failed:
1260
+ if uid not in self._work.failed:
1261
+ failed_writes[uid] = None
1262
+ for uid, entry in self._work.failed.items():
1263
+ if uid not in self._base.failed or entry != self._base.failed[uid]:
1264
+ failed_writes[uid] = (copy.deepcopy(entry[0]), copy.deepcopy(entry[1]))
1265
+
1266
+ return GraphEditCommit(
1267
+ queue_writes=queue_writes,
1268
+ success_writes=success_writes,
1269
+ failed_writes=failed_writes,
1270
+ recovery_attempts=tuple(self._recovery_attempts.values()),
1271
+ )
1272
+
1273
+
1274
+ __all__ = [
1275
+ "EditTransaction",
1276
+ ]