tasklite-engine 2.0.0__py3-none-any.whl → 2.2.0__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 (48) hide show
  1. tasklite/__init__.py +35 -18
  2. tasklite/backend/base.py +87 -77
  3. tasklite/backend/memory.py +150 -95
  4. tasklite/backend/sqlite_backend.py +336 -255
  5. tasklite/engine/__init__.py +1 -1
  6. tasklite/engine/admission.py +113 -236
  7. tasklite/engine/channel.py +426 -296
  8. tasklite/engine/completion.py +153 -121
  9. tasklite/engine/config.py +31 -28
  10. tasklite/engine/dispatch.py +186 -207
  11. tasklite/engine/errorclass.py +79 -64
  12. tasklite/engine/governor.py +160 -21
  13. tasklite/engine/in_flight.py +39 -38
  14. tasklite/engine/ops.py +72 -72
  15. tasklite/engine/recovery.py +64 -160
  16. tasklite/engine/resource.py +34 -34
  17. tasklite/engine/runtime.py +118 -37
  18. tasklite/engine/scheduler.py +95 -52
  19. tasklite/engine/selection.py +244 -0
  20. tasklite/engine/session.py +16 -21
  21. tasklite/engine/store.py +368 -208
  22. tasklite/engine/types.py +20 -20
  23. tasklite/engine/wait.py +3 -3
  24. tasklite/exceptions.py +8 -0
  25. tasklite/hooks.py +16 -16
  26. tasklite/models/artifact.py +80 -0
  27. tasklite/models/attempt.py +17 -14
  28. tasklite/models/context.py +117 -135
  29. tasklite/models/job.py +53 -73
  30. tasklite/models/state.py +138 -141
  31. tasklite/models/task.py +30 -19
  32. tasklite/models/trigger.py +18 -0
  33. tasklite/pipeline.py +107 -96
  34. tasklite/selection.py +116 -0
  35. tasklite/testing.py +17 -11
  36. tasklite/triggers.py +46 -0
  37. tasklite/utils/artifact.py +203 -0
  38. tasklite/utils/clock.py +27 -1
  39. tasklite/utils/encoding.py +6 -6
  40. tasklite/utils/ipc.py +503 -614
  41. tasklite/utils/lockfile.py +8 -8
  42. tasklite/wrappers/discovery.py +74 -79
  43. {tasklite_engine-2.0.0.dist-info → tasklite_engine-2.2.0.dist-info}/METADATA +51 -82
  44. tasklite_engine-2.2.0.dist-info/RECORD +55 -0
  45. {tasklite_engine-2.0.0.dist-info → tasklite_engine-2.2.0.dist-info}/WHEEL +1 -1
  46. tasklite_engine-2.0.0.dist-info/RECORD +0 -49
  47. {tasklite_engine-2.0.0.dist-info → tasklite_engine-2.2.0.dist-info}/licenses/LICENSE +0 -0
  48. {tasklite_engine-2.0.0.dist-info → tasklite_engine-2.2.0.dist-info}/top_level.txt +0 -0
tasklite/__init__.py CHANGED
@@ -7,10 +7,10 @@
7
7
 
8
8
  公开面:TaskLite 门面(六步调用契约)、模型层、异常族、错误分类
9
9
  (ErrorClassifier 与 ERR_* 错误码)、单射编码族、资源体系、失败档案
10
- 条目、用户钩子三件套、准入与重入队策略 seam、排序策略 seam、持久化
11
- 后端与运行摘要值对象,均经本文件集中导出(``from tasklite import
12
- ...`` 是唯一承诺稳定的导入面)。``__version__`` 为版本单一事实源
13
- (pyproject 动态读取点)。
10
+ 条目、用户钩子三件套、准入与重入队策略 seam、排序策略 seam、执行选择
11
+ 规则值对象、持久化后端与运行摘要值对象,均经本文件集中导出
12
+ (``from tasklite import ...`` 是唯一承诺稳定的导入面)。``__version__``
13
+ 为版本单一事实源(pyproject 动态读取点)。
14
14
 
15
15
  分层单向依赖红线:``tasklite/models/`` 严禁 import
16
16
  ``tasklite/engine/``(IPC 声明读写一律下沉 ``tasklite/utils/ipc.py``),
@@ -22,14 +22,18 @@
22
22
  """
23
23
  from __future__ import annotations
24
24
 
25
- __version__ = "2.0.0"
25
+ __version__ = "2.2.0"
26
26
 
27
27
  # ── 门面(六步调用契约的唯一入口)────────────────────────────────────
28
28
  from .pipeline import TaskLite
29
29
 
30
+ # ── 执行选择(pipeline 级规则值对象与规则集)─────────────────────────
31
+ from .selection import Exclude, Selection, Skip
32
+
30
33
  # ── 模型层:规格 / 实例 / 轨迹 / 上下文 ──────────────────────────────
31
34
  from .models.attempt import AttemptRecord
32
35
  from .models.context import JobContext
36
+ from .models.trigger import TriggerContext
33
37
  from .models.job import Job, JobRuntimeState
34
38
  from .models.task import Task, TaskRegistry, validate_resource_amounts
35
39
 
@@ -49,6 +53,8 @@ from .engine.errorclass import (
49
53
  ERR_COMMIT_FAILURE,
50
54
  ERR_DEADLOCK_GAP,
51
55
  ERR_DEPENDENCY_DEADLOCK,
56
+ ERR_DEPENDENCY_EXCLUDED,
57
+ ERR_DEPENDENCY_SKIPPED,
52
58
  ERR_DISPATCH_FAILURE,
53
59
  ERR_IPC_WRITE_DEGRADED_PREFIX,
54
60
  ERR_JOB_DEPENDENCY,
@@ -60,6 +66,7 @@ from .engine.errorclass import (
60
66
  ERR_PROCESS_CRASH_PREFIX,
61
67
  ERR_PROCESS_SIGNAL_DEATH,
62
68
  ERR_RESOURCE_DEADLOCK,
69
+ ERR_SKIPPED,
63
70
  ERR_TIMEOUT_PREFIX,
64
71
  FATAL_EXCEPTIONS,
65
72
  TRANSIENT_EXCEPTIONS,
@@ -68,7 +75,7 @@ from .engine.errorclass import (
68
75
  ErrorClassifier,
69
76
  ValidationErrorItem,
70
77
  ValidationResult,
71
- classify_error_type,
78
+ classify_error_category,
72
79
  classify_exception,
73
80
  is_transient_exception,
74
81
  validate_payload_errors,
@@ -81,15 +88,16 @@ from .engine.resource import (
81
88
  Resource,
82
89
  )
83
90
 
84
- # ── 失败档案条目 ─────────────────────────────────────────────────────
91
+ # ── 失败档案条目与挂起条目 ───────────────────────────────────────────
92
+ from .engine.ops import SuspendEntry
85
93
  from .engine.store import FailureEntry
86
94
 
87
- # ── 策略 seam:准入(rerun)与重入队(节奏)─────────────────────────
95
+ # ── 策略 seam:准入(trigger)与重入队(节奏)─────────────────────────
88
96
  from .engine.admission import (
89
97
  ImmediateRequeuePolicy,
90
98
  RequeuePlan,
91
99
  RequeuePolicy,
92
- RerunPolicy,
100
+ TriggerRegistry,
93
101
  )
94
102
 
95
103
  # ── 策略 seam:调度排序 ──────────────────────────────────────────────
@@ -97,11 +105,11 @@ from .engine.scheduler import FifoOrderingPolicy, OrderingPolicy
97
105
 
98
106
  # ── 运行值对象:run()/stop() 调用边界直接遭遇的形状 ──────────────────
99
107
  from .engine.types import (
100
- AttemptFinish,
108
+ AttemptOutcome,
101
109
  ExitReason,
102
110
  RunSummary,
103
111
  StopMode,
104
- TaskStats,
112
+ RunStats,
105
113
  )
106
114
 
107
115
  # ── 持久化后端 ───────────────────────────────────────────────────────
@@ -114,7 +122,7 @@ from .utils.encoding import (
114
122
  encode_identifier,
115
123
  encode_job_component,
116
124
  percent_encode,
117
- safe_uid_filename,
125
+ encode_job_uid_filename,
118
126
  )
119
127
 
120
128
  # ── JSON 序列化统一出口 ──────────────────────────────────────────────
@@ -123,10 +131,15 @@ from .utils import jsonutil
123
131
  __all__ = [
124
132
  # 门面
125
133
  "TaskLite",
134
+ # 执行选择
135
+ "Exclude",
136
+ "Selection",
137
+ "Skip",
126
138
  # 模型层
127
139
  "AttemptRecord",
128
140
  "Job",
129
141
  "JobContext",
142
+ "TriggerContext",
130
143
  "JobRuntimeState",
131
144
  "Task",
132
145
  "TaskRegistry",
@@ -146,7 +159,7 @@ __all__ = [
146
159
  "ErrorClassifier",
147
160
  "ValidationErrorItem",
148
161
  "ValidationResult",
149
- "classify_error_type",
162
+ "classify_error_category",
150
163
  "classify_exception",
151
164
  "is_transient_exception",
152
165
  "validate_payload_errors",
@@ -160,6 +173,9 @@ __all__ = [
160
173
  "ERR_COMMIT_FAILURE",
161
174
  "ERR_DISPATCH_FAILURE",
162
175
  "ERR_DEADLOCK_GAP",
176
+ "ERR_DEPENDENCY_EXCLUDED",
177
+ "ERR_DEPENDENCY_SKIPPED",
178
+ "ERR_SKIPPED",
163
179
  "ERR_TIMEOUT_PREFIX",
164
180
  "ERR_PROCESS_CRASH_PREFIX",
165
181
  "ERR_NO_IPC_RESULT",
@@ -172,21 +188,22 @@ __all__ = [
172
188
  "CapacityResource",
173
189
  "RateLimitResource",
174
190
  "Resource",
175
- # 失败档案
191
+ # 失败档案与挂起
176
192
  "FailureEntry",
193
+ "SuspendEntry",
177
194
  # 策略 seam
178
195
  "ImmediateRequeuePolicy",
179
196
  "RequeuePlan",
180
197
  "RequeuePolicy",
181
- "RerunPolicy",
198
+ "TriggerRegistry",
182
199
  "FifoOrderingPolicy",
183
200
  "OrderingPolicy",
184
201
  # 运行值对象
185
- "AttemptFinish",
202
+ "AttemptOutcome",
186
203
  "ExitReason",
187
204
  "RunSummary",
188
205
  "StopMode",
189
- "TaskStats",
206
+ "RunStats",
190
207
  # 持久化后端
191
208
  "InMemoryStateBackend",
192
209
  "SQLiteStateBackend",
@@ -196,7 +213,7 @@ __all__ = [
196
213
  "encode_identifier",
197
214
  "encode_job_component",
198
215
  "percent_encode",
199
- "safe_uid_filename",
216
+ "encode_job_uid_filename",
200
217
  # 序列化
201
218
  "jsonutil",
202
219
  ]
tasklite/backend/base.py CHANGED
@@ -5,10 +5,10 @@ delta 语义组织:队列行的「弹出」从不单独落盘——被弹出
5
5
  磁盘队列中,直到 commit_job_success / commit_job_failure /
6
6
  commit_retry / commit_skip 的事务内才删除(at-least-once 崩溃契约)。
7
7
 
8
- 失败档案(failed)术语:按 uid 唯一终态,wall/failed 全局互斥——
9
- 成功 commit 删 failed 同名行、失败 commit 删 wall 行,「最终状态唯一」
8
+ 失败档案(failed)术语:按 uid 唯一终态,successes/failed 全局互斥——
9
+ 成功 commit 删 failed 同名行、失败 commit 删 successes 行,「最终状态唯一」
10
10
  由此保证;失败历史与执行时间线由 attempts 旁路轨迹承接,本表不注入
11
- 计数字段。attempts 为 append-only 旁路观测面:不参与 wall/failed 的
11
+ 计数字段。attempts 为 append-only 旁路观测面:不参与 successes/failed 的
12
12
  互斥与 REPLACE 语义。
13
13
  """
14
14
  from __future__ import annotations
@@ -19,7 +19,7 @@ from typing import Any, Callable, Mapping, Sequence
19
19
  from ..models.attempt import ATTEMPT_OUTCOMES, AttemptRecord
20
20
 
21
21
 
22
- def validate_queue_replacement(jobs: Any) -> None:
22
+ def validate_queue_replacement(job_snapshots: Any) -> None:
23
23
  """整表替换集统一形状校验(save_queue / replace_queue_atomic 共用)。
24
24
 
25
25
  契约:替换集必须是 job dict 的 list/tuple(与 load_queue 行形态一致);
@@ -29,16 +29,16 @@ def validate_queue_replacement(jobs: Any) -> None:
29
29
  混过校验,SQLite 腿「DELETE 全表成功 + INSERT 全跳过」会静默清空整条
30
30
  队列且事务正常提交,与 Memory 腿抛 TypeError 且队列原状形成行为分叉。
31
31
  """
32
- if not isinstance(jobs, (list, tuple)):
32
+ if not isinstance(job_snapshots, (list, tuple)):
33
33
  raise TypeError(
34
34
  f"queue replacement must be a list of job dicts, "
35
- f"got {type(jobs).__name__}"
35
+ f"got {type(job_snapshots).__name__}"
36
36
  )
37
- for i, job in enumerate(jobs):
38
- if not isinstance(job, dict):
37
+ for i, job_snapshot in enumerate(job_snapshots):
38
+ if not isinstance(job_snapshot, dict):
39
39
  raise TypeError(
40
40
  f"queue replacement item #{i} must be a job dict, "
41
- f"got {type(job).__name__}"
41
+ f"got {type(job_snapshot).__name__}"
42
42
  )
43
43
 
44
44
 
@@ -46,7 +46,7 @@ def validate_attempt_dispatch(record: Any) -> None:
46
46
  """尝试轨迹插入门卫:只接受「派发即插行」形态。
47
47
 
48
48
  契约(attempts append-only 协议的插入侧):AttemptRecord 且
49
- outcome="running"、finished_at 与 error 均为 None——收尾字段由
49
+ outcome="running"、finished_at 与 error_message 均为 None——收尾字段由
50
50
  ``update_attempt`` 唯一写入;插入侧出现收尾字段说明调用方绕过了
51
51
  派发点协议(终态行伪装成派发行,时间线出现空洞),fail-loud 拒绝。
52
52
  """
@@ -55,16 +55,16 @@ def validate_attempt_dispatch(record: Any) -> None:
55
55
  f"attempt record must be an AttemptRecord, "
56
56
  f"got {type(record).__name__} ({record!r})"
57
57
  )
58
- if record.outcome != "running" or record.finished_at is not None or record.error is not None:
58
+ if record.outcome != "running" or record.finished_at is not None or record.error_message is not None:
59
59
  raise ValueError(
60
60
  "dispatch append must be a fresh running row "
61
- "(outcome='running', finished_at=None, error=None), got "
61
+ "(outcome='running', finished_at=None, error_message=None), got "
62
62
  f"outcome={record.outcome!r} finished_at={record.finished_at!r} "
63
- f"error={record.error!r}"
63
+ f"error_message={record.error_message!r}"
64
64
  )
65
65
 
66
66
 
67
- def validate_attempt_finish(outcome: Any, finished_at: Any, error: Any) -> None:
67
+ def validate_attempt_finish(outcome: Any, finished_at: Any, error_message: Any) -> None:
68
68
  """尝试轨迹收尾门卫:outcome 属终态词汇、收尾时刻与错误形态合法。
69
69
 
70
70
  running 是插入侧专属形态——收尾接口把 running 写回会把已派发行
@@ -84,39 +84,39 @@ def validate_attempt_finish(outcome: Any, finished_at: Any, error: Any) -> None:
84
84
  )
85
85
  if not finished_at:
86
86
  raise ValueError("finished_at must be a non-empty str")
87
- if error is not None and not isinstance(error, str):
87
+ if error_message is not None and not isinstance(error_message, str):
88
88
  raise TypeError(
89
- f"error must be a str or None, got {type(error).__name__} ({error!r})"
89
+ f"error_message must be a str or None, got {type(error_message).__name__} ({error_message!r})"
90
90
  )
91
- if error == "":
92
- raise ValueError("error must be a non-empty str or None")
91
+ if error_message == "":
92
+ raise ValueError("error_message must be a non-empty str or None")
93
93
 
94
94
 
95
95
  class AbstractStateBackend(ABC):
96
96
  """管线状态持久化抽象契约(SQLite / Memory 双腿共同口径)。
97
97
 
98
98
  语义分组:
99
- - 全量加载(load_wall / load_failed / load_failed_payloads /
99
+ - 全量加载(load_successes / load_failed / load_failure_payloads /
100
100
  load_cursors / load_queue):仅启动装配与测试装配使用;
101
101
  - 整表重写(save_queue / replace_queue_atomic):读-改-写必须经
102
102
  ``replace_queue_atomic`` 收敛进单个写事务;
103
103
  - delta 提交(commit_job_success / commit_job_failure /
104
- commit_retry / commit_bulk_failure / commit_skip):逐 job 单事务
104
+ commit_retry / commit_job_failures / commit_skip):逐 job 单事务
105
105
  碎片化,禁止多 job 混合长事务;返回 False 表示持久化失败且后端
106
106
  保持调用前状态,调用方不得推进内存镜像并走崩溃契约;
107
107
  - 增量入队(enqueue_jobs):不做全量覆盖,与运行中 delta 提交并发
108
108
  安全(写入侧不覆盖);
109
- - 定向删除与种子(delete_queue_uids / delete_failed / delete_wall /
110
- seed_wall / seed_cursor):加载期 repair 差量落盘与运维接缝;
109
+ - 定向删除与种子(delete_queue_uids / delete_failed / delete_successes /
110
+ seed_successes / seed_cursor):加载期 repair 差量落盘与运维接缝;
111
111
  - 尝试轨迹(append_attempt / update_attempt / load_attempts):
112
112
  append-only 旁路观测面;
113
- - 元数据(get_meta / set_meta):框架级键值(fencing 的 last_run_id 等)。
113
+ - 元数据(get_engine_metadata / set_engine_metadata):框架级键值(fencing 的 last_run_id 等)。
114
114
  """
115
115
 
116
116
  # 全量加载 -------------------------------------------------------
117
117
 
118
118
  @abstractmethod
119
- def load_wall(self) -> dict[str, dict[str, Any]]:
119
+ def load_successes(self) -> dict[str, dict[str, Any]]:
120
120
  """加载全部成功终态(uid → meta)。"""
121
121
 
122
122
  @abstractmethod
@@ -124,7 +124,7 @@ class AbstractStateBackend(ABC):
124
124
  """加载全部失败档案终态(uid → 失败 meta)。"""
125
125
 
126
126
  @abstractmethod
127
- def load_failed_payloads(self) -> dict[str, dict[str, Any]]:
127
+ def load_failure_payloads(self) -> dict[str, dict[str, Any]]:
128
128
  """读取失败档案各 uid 的原始业务 payload 快照(无快照的 uid 不出现)。"""
129
129
 
130
130
  @abstractmethod
@@ -133,12 +133,12 @@ class AbstractStateBackend(ABC):
133
133
 
134
134
  @abstractmethod
135
135
  def load_queue(self) -> list[dict[str, Any]]:
136
- """按 seq 升序加载磁盘队列真相。"""
136
+ """按 queue_position 升序加载磁盘队列真相。"""
137
137
 
138
138
  # 整表重写 -------------------------------------------------------
139
139
 
140
140
  @abstractmethod
141
- def save_queue(self, jobs: list[dict[str, Any]]) -> None:
141
+ def save_queue(self, job_snapshots: list[dict[str, Any]]) -> None:
142
142
  """整表重写队列(测试装配 / replace_queue_atomic 的事务内步骤)。
143
143
 
144
144
  红线:这是「无读基准的整表覆盖」——跨进程并发的 enqueue/commit
@@ -176,39 +176,45 @@ class AbstractStateBackend(ABC):
176
176
  @abstractmethod
177
177
  def commit_job_success(
178
178
  self,
179
- uid: str,
180
- result_meta: dict,
179
+ job_uid: str,
180
+ result_metadata: dict,
181
181
  *,
182
- spawned_jobs: Sequence[dict[str, Any]] = (),
182
+ attempt_id: int | None = None,
183
+ execution_id: str | None = None,
184
+ finished_at: str | None = None,
185
+ spawned_job_snapshots: Sequence[dict[str, Any]] = (),
183
186
  cursor_updates: Mapping[str, str | None] | None = None,
184
187
  ) -> bool:
185
- """原子持久化一个成功 job 的 delta。
188
+ """原子持久化一个成功 job 的 delta,并在同一事务中校验与终结对应 attempts 行。
186
189
 
187
190
  单事务效果:
188
- - wall:INSERT/REPLACE uid → result_meta;
191
+ - attempts:校验 attempt_id / finished_at 非空,对应行存在、job_uid 一致、
192
+ execution_id 一致(传入非空时)、且 outcome == 'running',将其更新为
193
+ outcome='succeeded', finished_at=finished_at, error_message=None;
194
+ - successes:INSERT/REPLACE uid → result_metadata;
189
195
  - queue:DELETE 被弹出的 uid;
190
- - queue:spawned_jobs 队头插入(保序);
191
- - failed:DELETE 同名残行(成功终态唯一,防 wall∩failed 并存);
196
+ - queue:spawned_job_snapshots 队头插入(保序);
197
+ - failed:DELETE 同名残行(成功终态唯一,防 successes∩failed 并存);
192
198
  - cursors:合并 cursor_updates(None 值表示删除游标)。
193
199
 
194
- 返回 True 成功;返回 False 表示任一步持久化失败且后端保持调用前
195
- 状态(被弹出的 uid 仍在磁盘队列),调用方不得更新内存 wall/cursor
196
- 状态,并自行决定是否重入队(崩溃契约)。
200
+ 返回 True 成功;返回 False 表示 attempts 校验失败或任一步持久化失败且
201
+ 后端保持调用前状态(被弹出的 uid 仍在磁盘队列,attempts 仍保持原状),
202
+ 调用方不得更新内存 successes/cursor 状态,并自行决定是否重入队(崩溃契约)。
197
203
  """
198
204
 
199
205
  @abstractmethod
200
206
  def commit_job_failure(
201
207
  self,
202
- uid: str,
203
- result_meta: dict,
204
- job_payload: dict[str, Any] | None = None,
208
+ job_uid: str,
209
+ failure_metadata: dict,
210
+ payload: dict[str, Any] | None = None,
205
211
  ) -> bool:
206
212
  """原子持久化一个失败 job 的 delta(写入失败档案)。
207
213
 
208
- 单事务效果:failed INSERT/REPLACE uid → result_meta;
209
- queue DELETE uid;wall DELETE 同名行——重跑任务重试耗尽时旧成功
210
- 记录作废(最终状态唯一),否则磁盘 wall∩failed 并存破坏互斥。
211
- ``job_payload`` 是原始业务 payload 快照(补跑自足,无需外部反查);
214
+ 单事务效果:failed INSERT/REPLACE uid → failure_metadata;
215
+ queue DELETE uid;successes DELETE 同名行——重跑任务重试耗尽时旧成功
216
+ 记录作废(最终状态唯一),否则磁盘 successes∩failed 并存破坏互斥。
217
+ ``payload`` 是原始业务输入快照(补跑自足,无需外部反查);
212
218
  None 表示本路径无可存快照,保留既有快照不覆盖。
213
219
  返回语义与 ``commit_job_success`` 一致:False ⇒ 后端未变、崩溃契约。
214
220
  """
@@ -216,53 +222,53 @@ class AbstractStateBackend(ABC):
216
222
  @abstractmethod
217
223
  def commit_retry(
218
224
  self,
219
- popped_uid: str,
220
- requeued_job: dict[str, Any],
225
+ popped_job_uid: str,
226
+ requeued_job_snapshot: dict[str, Any],
221
227
  *,
222
228
  front: bool = False,
223
229
  ) -> bool:
224
- """原子持久化一次重入队 delta:DELETE popped_uid + 按 front 插入 requeued_job。
230
+ """原子持久化一次重入队 delta:DELETE popped_job_uid + 按 front 插入 requeued_job_snapshot。
225
231
 
226
- 不写 wall/failed。同 uid 重试是 DELETE+INSERT(一次执行没有独立
232
+ 不写 successes/failed。同 uid 重试是 DELETE+INSERT(一次执行没有独立
227
233
  持久身份,身份仍是 uid)。重插不得静默丢弃:requeued uid 撞上删除
228
234
  popped 后的既有行冲突时返回 False 走崩溃契约,绝不产出重复队列
229
235
  条目却报成功。
230
236
  """
231
237
 
232
238
  @abstractmethod
233
- def commit_bulk_failure(self, uids_metas: list[tuple[str, dict]]) -> bool:
239
+ def commit_job_failures(self, job_uids_metadata: list[tuple[str, dict]]) -> bool:
234
240
  """原子批量写失败档案(死锁/级联场景)的 delta。
235
241
 
236
- 单事务效果:failed INSERT/REPLACE 每个 uid → meta;
242
+ 单事务效果:failed INSERT/REPLACE 每个 uid → metadata;
237
243
  queue 按 uid 精准 DELETE(剩余条目保持原顺序);
238
- wall 批量 DELETE 同名行(与 commit_job_failure 对称的最终状态唯一)。
244
+ successes 批量 DELETE 同名行(与 commit_job_failure 对称的最终状态唯一)。
239
245
  任一行失败 ⇒ 整体回滚、返回 False,绝不留下「队列已删、档案未落」
240
246
  的半成品失败态。
241
247
  """
242
248
 
243
249
  @abstractmethod
244
- def commit_skip(self, uid: str) -> bool:
250
+ def commit_skip(self, job_uid: str) -> bool:
245
251
  """delta 删除队列中已终态(重复)的 uid。
246
252
 
247
- 去重命中(uid 已在 wall/failed)时调用——磁盘队列中该 uid 是残留
253
+ 去重命中(uid 已在 successes/failed)时调用——磁盘队列中该 uid 是残留
248
254
  条目,直接删除以同步内存/磁盘(内存 = 磁盘 − in-flight)。
249
- 不写 wall/failed(重复条目不改变任何状态,只是清理)。
255
+ 不写 successes/failed(重复条目不改变任何状态,只是清理)。
250
256
  返回 True 成功;False 时 on-disk 队列不变,调用方走崩溃契约。
251
257
  """
252
258
 
253
259
  @abstractmethod
254
- def append_failed(self, uid: str, payload: dict[str, Any] | None = None) -> None:
260
+ def append_failed(self, job_uid: str, metadata: dict[str, Any] | None = None) -> None:
255
261
  """绕过队列直接写一条失败档案记录(带外登记面)。
256
262
 
257
- 按 uid REPLACE(幂等);不触碰 queue/wall/cursors。持久化失败
263
+ 按 uid REPLACE(幂等);不触碰 queue/successes/cursors。持久化失败
258
264
  抛异常(不吞)。
259
265
  """
260
266
 
261
267
  # 增量入队 -------------------------------------------------------
262
268
 
263
269
  @abstractmethod
264
- def enqueue_jobs(self, jobs: list[dict[str, Any]], *, front: bool = False) -> list[str]:
265
- """批量增量入队:按 front 在队列头/尾插入 jobs(保序),单事务原子。
270
+ def enqueue_jobs(self, job_snapshots: list[dict[str, Any]], *, front: bool = False) -> list[str]:
271
+ """批量增量入队:按 front 在队列头/尾插入 job_snapshots(保序),单事务原子。
266
272
 
267
273
  跳过与现有队列重复的 uid(含批次内重复,首个存储),返回实际插入
268
274
  的 uid 列表。与 commit_* 的 delta 语义对齐:不做全表重写——运行中
@@ -274,7 +280,7 @@ class AbstractStateBackend(ABC):
274
280
  # 定向删除与种子 --------------------------------------------------
275
281
 
276
282
  @abstractmethod
277
- def delete_queue_uids(self, uids: list[str]) -> int:
283
+ def delete_queue_uids(self, job_uids: list[str]) -> int:
278
284
  """按 uid 定向批量删除队列行(加载期 repair 的差量落盘唯一出口)。
279
285
 
280
286
  与 save_queue 的全表重写相对:只 DELETE 指定 uid 的行,其余行原样
@@ -285,21 +291,21 @@ class AbstractStateBackend(ABC):
285
291
  """
286
292
 
287
293
  @abstractmethod
288
- def delete_failed(self, uids: list[str]) -> int:
294
+ def delete_failed(self, job_uids: list[str]) -> int:
289
295
  """从失败档案批量删除指定 uid(clear_failures 的后端实现)。
290
296
 
291
- 返回实际删除行数(连带清除 payload 快照)。不触碰 queue/wall。
297
+ 返回实际删除行数(连带清除 payload 快照)。不触碰 queue/successes。
292
298
  仅限 run() 之外调用(改变 is_known 判定基础,与 enqueue 同纪律)。
293
299
  """
294
300
 
295
301
  @abstractmethod
296
- def delete_wall(self, uids: list[str]) -> int:
297
- """从 wall 批量删除指定 uid(clear_history 的后端实现 + commit 路径事务内清理)。
302
+ def delete_successes(self, job_uids: list[str]) -> int:
303
+ """从 successes 批量删除指定 uid(clear_history 的后端实现 + commit 路径事务内清理)。
298
304
 
299
305
  两种调用上下文:
300
306
  - 运行外管理 API 的批量删除;
301
- - commit_job_failure / commit_bulk_failure 的同一事务内逐 uid 删除
302
- (重跑任务重跑失败时 wall 旧记录作废,最终状态唯一)。
307
+ - commit_job_failure / commit_job_failures 的同一事务内逐 uid 删除
308
+ (重跑任务重跑失败时 successes 旧记录作废,最终状态唯一)。
303
309
 
304
310
  运行中的调用仅限 commit 事务内部(随失败档案写入原子提交,不改变
305
311
  进行中的派发判定);独立调用仅限 run 之外(改变 is_known 判定
@@ -307,13 +313,13 @@ class AbstractStateBackend(ABC):
307
313
  """
308
314
 
309
315
  @abstractmethod
310
- def seed_wall(self, uids: list[str]) -> int:
311
- """把 uid 批量写入 wall(meta 为空 dict)——存档迁移标记「已处理」。
316
+ def seed_successes(self, job_uids: list[str]) -> int:
317
+ """把 uid 批量写入 successes(meta 为空 dict)——存档迁移标记「已处理」。
312
318
 
313
319
  幂等:已存在的 uid 被覆盖(meta 重置为空)。返回实际写入行数。
314
- 不变式(wall/failed 全局互斥):已在 failed 的 uid 拒绝种子——
320
+ 不变式(successes/failed 全局互斥):已在 failed 的 uid 拒绝种子——
315
321
  冲突整体拒绝(零写入、抛 ValueError),不静默清除失败档案记录;
316
- 持久层与管理 API(OpsConsole.seed_wall)两层同契约。
322
+ 持久层与管理 API(OpsConsole.seed_successes)两层同契约。
317
323
  """
318
324
 
319
325
  @abstractmethod
@@ -322,8 +328,8 @@ class AbstractStateBackend(ABC):
322
328
 
323
329
  入口校验 fail-loud:key 非空 str、value 必须 str——静默 str() 强转
324
330
  会让同一非法入参在 sqlite 腿抛异常、memory 腿写数字串(跨后端行为
325
- 分歧),且与内存镜像值型漂移。discovery 的已见判定走 wall/failed,
326
- 「已见预填」请用 ``seed_wall``;本方法服务通用业务 cursor。
331
+ 分歧),且与内存镜像值型漂移。discovery 的已见判定走 successes/failed,
332
+ 「已见预填」请用 ``seed_successes``;本方法服务通用业务 cursor。
327
333
  """
328
334
 
329
335
  # 尝试轨迹(append-only 旁路观测面)--------------------------------
@@ -334,8 +340,8 @@ class AbstractStateBackend(ABC):
334
340
 
335
341
  协议:仅在派发点调用,record 必须是 outcome="running"、无收尾
336
342
  时刻/错误的派发即插行(``validate_attempt_dispatch`` 门卫),随行
337
- 落盘 started_at / incarnation / run_id。attempts 不参与 wall/failed
338
- 的互斥与 REPLACE 语义,本方法不触碰 queue/wall/failed/cursors;
343
+ 落盘 started_at / execution_id / run_id。attempts 不参与 successes/failed
344
+ 的互斥与 REPLACE 语义,本方法不触碰 queue/successes/failed/cursors;
339
345
  持久化失败抛异常(fail-loud,不吞)。
340
346
  """
341
347
 
@@ -346,9 +352,9 @@ class AbstractStateBackend(ABC):
346
352
  *,
347
353
  outcome: str,
348
354
  finished_at: str,
349
- error: str | None = None,
355
+ error_message: str | None = None,
350
356
  ) -> bool:
351
- """终态/重试时收尾轨迹行:写 finished_at / outcome / error。
357
+ """终态/重试时收尾轨迹行:写 finished_at / outcome / error_message。
352
358
 
353
359
  收尾词汇与 ``AttemptRecord`` 一致(succeeded / failed / requeued /
354
360
  skipped),running 是插入侧专属形态(``validate_attempt_finish``
@@ -362,14 +368,18 @@ class AbstractStateBackend(ABC):
362
368
  def load_attempts(self, job_uid: str) -> list[AttemptRecord]:
363
369
  """按 job_uid 读取全部尝试轨迹(按轨迹 id 升序);无轨迹返回空列表。"""
364
370
 
371
+ @abstractmethod
372
+ def load_latest_succeeded_finished_at(self, job_uid: str) -> str | None:
373
+ """窄查询指定 job_uid 最新一条 outcome == 'succeeded' 轨迹行的 finished_at;无则返回 None。"""
374
+
365
375
  # 元数据 ---------------------------------------------------------
366
376
 
367
377
  @abstractmethod
368
- def get_meta(self, key: str) -> str | None:
378
+ def get_engine_metadata(self, key: str) -> str | None:
369
379
  """读取一条框架级元数据(如 fencing 的 last_run_id)。无则返回 None。"""
370
380
 
371
381
  @abstractmethod
372
- def set_meta(self, key: str, value: str) -> None:
382
+ def set_engine_metadata(self, key: str, value: str) -> None:
373
383
  """写入一条框架级元数据(UPSERT 语义)。失败抛异常(不吞)。"""
374
384
 
375
385