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
@@ -2,30 +2,43 @@
2
2
 
3
3
  实现 AbstractStateBackend 完整契约,提供零文件系统 IO 的纯内存状态
4
4
  存储:瞬态管线、单元测试、沙盒执行。快照隔离的 delta 事务语义与
5
- SQLite 腿对齐——「校验先行、统一落变」模拟事务回滚:返回 False 或
6
- 抛异常时全部集合与调用前完全一致。
5
+ SQLite 腿对齐——「校验先行、统一落变」模拟事务回滚:抛异常时全部集合
6
+ 与调用前完全一致。
7
7
  """
8
8
  from __future__ import annotations
9
9
 
10
10
  import copy
11
11
  import logging
12
- import os
13
12
  import threading
14
- from pathlib import Path
15
- from typing import Any, Callable, Mapping, Sequence
13
+ from collections.abc import Iterator
14
+ from contextlib import contextmanager
15
+ from typing import Any, Literal, Mapping, Sequence, cast
16
16
 
17
17
  from .base import (
18
18
  AbstractStateBackend,
19
+ FailureEntry,
20
+ GraphEditCommit,
19
21
  QUEUE_EXECUTION_ID_KEY,
20
- execution_id_matches_run,
22
+ is_valid_authorization_target_type,
23
+ normalize_authorization_path,
24
+ normalize_failure_entries,
21
25
  public_queue_snapshot,
22
26
  queue_snapshot_execution_id,
23
27
  queue_snapshot_with_execution_id,
24
- validate_queue_replacement,
28
+ resolve_authorized_at,
29
+ validate_authorization_target_type,
30
+ validate_cursor_key,
31
+ validate_cursor_value,
32
+ validate_graph_edit_commit,
33
+ validate_mark_job_running_args,
34
+ validate_mark_job_running_state,
35
+ validate_recovery_attempt_state,
36
+ validate_running_settlement_state,
37
+ validate_settlement_args,
25
38
  )
26
39
  from ..exceptions import TaskLiteError
27
40
  from ..models.state import job_uid_from_snapshot
28
- from ..utils.clock import utc_now_iso
41
+ from ..utils.artifact import TargetType, evaluate_authorization
29
42
 
30
43
  logger = logging.getLogger("tasklite")
31
44
 
@@ -52,6 +65,19 @@ class InMemoryStateBackend(AbstractStateBackend):
52
65
  self._job_sequences: dict[str, int] = {}
53
66
  self._authorizations: dict[str, dict[str, Any]] = {}
54
67
 
68
+ @contextmanager
69
+ def exclusive_access(self) -> Iterator[None]:
70
+ """非阻塞获取内存后端进程内独占执行锁,离开作用域归还。"""
71
+ if not self._exec_lock.acquire(blocking=False):
72
+ raise TaskLiteError(
73
+ "Another run() or management operation is in progress; "
74
+ "concurrent runs or management operations on the same state are forbidden."
75
+ )
76
+ try:
77
+ yield
78
+ finally:
79
+ self._exec_lock.release()
80
+
55
81
  # 全量加载 -------------------------------------------------------
56
82
 
57
83
  def load_successes(self) -> dict[str, dict[str, Any]]:
@@ -62,105 +88,50 @@ class InMemoryStateBackend(AbstractStateBackend):
62
88
  with self._lock:
63
89
  return copy.deepcopy(self._failed)
64
90
 
65
- def load_failure_payloads(self) -> dict[str, dict[str, Any]]:
66
- """读取失败档案各 uid 的原始业务 payload 快照(无快照的 uid 不出现)。"""
67
- with self._lock:
68
- return copy.deepcopy(self._failure_payloads)
69
-
70
91
  def load_cursors(self) -> dict[str, str]:
71
92
  with self._lock:
72
93
  return dict(self._cursors)
73
94
 
74
- def load_queue(self) -> list[dict[str, Any]]:
75
- with self._lock:
76
- return [
77
- public_queue_snapshot(j)
78
- for j in self._queue if j.get("status", "pending") == "pending"
79
- ]
80
-
81
- # 整表重写 -------------------------------------------------------
82
-
83
- def _dedup_copy(self, job_snapshots: list[dict[str, Any]]) -> list[dict[str, Any]]:
84
- """整表替换行的单一出口(save_queue 与 replace_queue_atomic 共用)。
85
-
86
- 替换集先经 ``validate_queue_replacement`` 校验(与 SQLite 腿同一
87
- 出口、同一时机——赋值之前 fail-loud,``_queue`` 保持调用前状态)。
88
- 保存兜底去重:重复 uid 保留首条 + 告警,与 SQLite 腿
89
- ``_rewrite_queue_rows`` 同语义;条目一律 deepcopy,杜绝外部可变
90
- 别名穿透快照隔离。
91
- """
92
- validate_queue_replacement(job_snapshots)
93
- seen: set[str] = set()
94
- clean: list[dict[str, Any]] = []
95
- for j in job_snapshots:
96
- u = job_uid_from_snapshot(j)
97
- if u in seen:
98
- logger.warning(f"save_queue: duplicate uid {u} dropped (kept first).")
99
- continue
100
- seen.add(u)
101
- clean.append(copy.deepcopy(j))
102
- return clean
103
-
104
- def save_queue(self, job_snapshots: list[dict[str, Any]]) -> None:
105
- with self._lock:
106
- self._queue = self._dedup_copy(job_snapshots)
107
-
108
- def replace_queue_atomic(
109
- self,
110
- compute: Callable[[list[dict[str, Any]]], list[dict[str, Any]]],
111
- ) -> None:
112
- with self._lock:
113
- # 锁内读真相 → 纯计算 → 替换:compute 抛异常时 _queue 赋值
114
- # 未发生,队列保持调用前状态(对齐 SQLite 腿事务回滚)。
115
- self._queue = self._dedup_copy(compute(copy.deepcopy(self._queue)))
116
-
117
95
  # delta 提交 -----------------------------------------------------
118
96
 
119
-
120
- def commit_job_failure(
121
- self, job_uid: str, failure_metadata: dict, payload: dict[str, Any] | None = None
122
- ) -> bool:
97
+ def commit_job_failures(self, entries: Sequence[FailureEntry]) -> None:
98
+ normalized = normalize_failure_entries(entries)
99
+ if not normalized:
100
+ return
123
101
  with self._lock:
124
102
  try:
125
- # 校验先行:失败 meta 与 payload 快照的拷贝在变更前完成,
126
- # 任一步失败 ⇒ failed/queue/successes 整体不变(对齐 SQLite 回滚)。
127
- meta_copy = copy.deepcopy(failure_metadata or {})
128
- payload_copy = (
129
- copy.deepcopy(payload) if payload is not None else None
130
- )
131
- remaining = [j for j in self._queue if job_uid_from_snapshot(j) != job_uid]
132
- self._failed[job_uid] = meta_copy
133
- # payload 快照 latest-wins;None 表示本路径无 payload,保留
134
- # 既有快照(与 SQLite 腿 _write_failed_row 的保留语义对齐)。
135
- if payload_copy is not None:
136
- self._failure_payloads[job_uid] = payload_copy
137
- self._queue = remaining
138
- # 同一事务语义内清理 successes 旧记录:重跑任务失败时旧成功
139
- # 记录作废(最终状态唯一),防 successes∩failed 并存。
140
- self._successes.pop(job_uid, None)
141
- return True
103
+ # 所有可失败的复制与队列构造先于统一发布(payload=None 保留既有快照)。
104
+ staged = [
105
+ (
106
+ job_uid,
107
+ copy.deepcopy(meta or {}),
108
+ copy.deepcopy(payload) if payload is not None else None,
109
+ )
110
+ for job_uid, meta, payload in normalized
111
+ ]
112
+ fail_uids = {uid for uid, _, _ in staged}
113
+ new_failed = dict(self._failed)
114
+ new_payloads = dict(self._failure_payloads)
115
+ for uid, meta_copy, payload_copy in staged:
116
+ new_failed[uid] = meta_copy
117
+ if payload_copy is not None:
118
+ new_payloads[uid] = payload_copy
119
+ new_successes = {
120
+ uid: meta for uid, meta in self._successes.items() if uid not in fail_uids
121
+ }
122
+ new_queue = [j for j in self._queue if job_uid_from_snapshot(j) not in fail_uids]
123
+ self._failed = new_failed
124
+ self._failure_payloads = new_payloads
125
+ self._successes = new_successes
126
+ self._queue = new_queue
142
127
  except Exception as e:
143
- logger.critical(f"Failed to commit job failure for {job_uid}: {e}")
128
+ logger.critical(f"Failed to commit failure archive entries: {e}")
144
129
  raise
145
130
 
146
-
147
- def commit_job_failures(self, job_uids_metadata: list[tuple[str, dict]]) -> None:
148
- with self._lock:
149
- # 所有可失败的复制与队列构造先于统一发布。
150
- entries = [(job_uid, copy.deepcopy(meta or {})) for job_uid, meta in job_uids_metadata]
151
- fail_uids = {u for u, _ in entries}
152
- remaining = [j for j in self._queue if job_uid_from_snapshot(j) not in fail_uids]
153
- failed = self._failed | dict(entries)
154
- successes = {uid: meta for uid, meta in self._successes.items() if uid not in fail_uids}
155
- self._failed = failed
156
- self._successes = successes
157
- self._queue = remaining
158
-
159
131
  def commit_skip(self, job_uid: str) -> None:
160
132
  with self._lock:
161
133
  self._queue = [j for j in self._queue if job_uid_from_snapshot(j) != job_uid]
162
134
 
163
-
164
135
  # 增量入队 -------------------------------------------------------
165
136
 
166
137
  def enqueue_jobs(self, job_snapshots: list[dict[str, Any]], *, front: bool = False) -> list[str]:
@@ -172,8 +143,6 @@ class InMemoryStateBackend(AbstractStateBackend):
172
143
  batch_seen: set[str] = set()
173
144
  for j in job_snapshots:
174
145
  u = job_uid_from_snapshot(j)
175
- # 批次内重复(同一调用传相同 uid 两次)与队列中已有的
176
- # uid 都跳过(首个存储,后续跳过)。
177
146
  if u in existing or u in batch_seen:
178
147
  continue
179
148
  batch_seen.add(u)
@@ -186,183 +155,112 @@ class InMemoryStateBackend(AbstractStateBackend):
186
155
  self._queue.extend(fresh)
187
156
  return [job_uid_from_snapshot(j) for j in fresh]
188
157
 
189
- # 定向删除与种子 --------------------------------------------------
190
-
191
- def delete_queue_uids(self, job_uids: list[str]) -> int:
192
- """按 uid 定向批量删除队列条目,与 SQLite 腿同语义:不触碰其余条目。"""
193
- if not job_uids:
194
- return 0
195
- with self._lock:
196
- del_set = set(job_uids)
197
- kept = [j for j in self._queue if job_uid_from_snapshot(j) not in del_set]
198
- removed = len(self._queue) - len(kept)
199
- self._queue = kept
200
- return removed
158
+ # 管理写与查询 --------------------------------------------------
201
159
 
202
- def delete_failed(self, job_uids: list[str]) -> int:
203
- with self._lock:
204
- del_set = set(job_uids)
205
- count = 0
206
- for u in del_set:
207
- if u in self._failed:
208
- del self._failed[u]
209
- self._failure_payloads.pop(u, None)
210
- count += 1
211
- return count
212
-
213
- def delete_successes(self, job_uids: list[str]) -> int:
214
- with self._lock:
215
- del_set = set(job_uids)
216
- count = 0
217
- for u in del_set:
218
- if u in self._successes:
219
- del self._successes[u]
220
- count += 1
221
- return count
222
-
223
- def apply_manual_status(
224
- self,
225
- updates: Sequence[tuple[str, str, dict[str, Any], dict[str, Any] | None]],
226
- ) -> None:
227
- """批量原子应用人工状态变更 (job_uid, status, snapshot, metadata)。"""
228
- if not updates:
160
+ def commit_graph_edit(self, commit: GraphEditCommit) -> None:
161
+ """在单锁 Copy-on-Write 临界区内校验并原子应用图修整变更,故障零污染。"""
162
+ if not validate_graph_edit_commit(commit):
229
163
  return
230
- with self._lock:
231
- new_successes = copy.deepcopy(self._successes)
232
- new_failed = copy.deepcopy(self._failed)
233
- new_failure_payloads = copy.deepcopy(self._failure_payloads)
234
- new_queue = copy.deepcopy(self._queue)
235
- for job_uid, status, snapshot, metadata in updates:
236
- snap_copy = copy.deepcopy(snapshot)
237
- meta_copy = copy.deepcopy(metadata or {})
238
- if status == "pending":
239
- new_successes.pop(job_uid, None)
240
- new_failed.pop(job_uid, None)
241
- new_failure_payloads.pop(job_uid, None)
242
- new_queue = [
243
- j for j in new_queue
244
- if job_uid_from_snapshot(j) != job_uid
245
- ]
246
- snap_copy["status"] = "pending"
247
- snap_copy["run_id"] = None
248
- snap_copy["attempt_no"] = None
249
- snap_copy["started_at"] = None
250
- snap_copy.pop(QUEUE_EXECUTION_ID_KEY, None)
251
- new_queue.append(snap_copy)
252
- elif status == "succeeded":
253
- new_queue = [
254
- j for j in new_queue
255
- if job_uid_from_snapshot(j) != job_uid
256
- ]
257
- new_failed.pop(job_uid, None)
258
- new_failure_payloads.pop(job_uid, None)
259
- new_successes[job_uid] = meta_copy
260
- elif status == "failed":
261
- new_queue = [
262
- j for j in new_queue
263
- if job_uid_from_snapshot(j) != job_uid
264
- ]
265
- new_successes.pop(job_uid, None)
266
- new_failed[job_uid] = meta_copy
267
- new_failure_payloads[job_uid] = snap_copy.get("payload") or {}
268
- else:
269
- raise ValueError(f"Unsupported manual status: {status!r}")
270
-
271
- self._successes = new_successes
272
- self._failed = new_failed
273
- self._failure_payloads = new_failure_payloads
274
- self._queue = new_queue
275
-
276
- @staticmethod
277
- def _snapshot_from_metadata(metadata: Any) -> dict[str, Any] | None:
278
- if not isinstance(metadata, dict):
279
- return None
280
- snapshot = metadata.get("job_snapshot")
281
- return snapshot if isinstance(snapshot, dict) else None
282
164
 
283
- def load_known_job_snapshot(self, uid: str) -> dict[str, Any] | None:
284
- """按队列、成功、失败、Attempt 历史的优先级读取完整配置。"""
285
165
  with self._lock:
286
- for snapshot in self._queue:
287
- if job_uid_from_snapshot(snapshot) == uid:
288
- return public_queue_snapshot(snapshot)
166
+ new_attempts = dict(self._attempts)
167
+ new_attempt_seq = self._attempt_seq
289
168
 
290
- success_snapshot = self._snapshot_from_metadata(self._successes.get(uid))
291
- if success_snapshot is not None:
292
- return copy.deepcopy(success_snapshot)
169
+ for rec in commit.recovery_attempts:
170
+ running = next(
171
+ (item for item in self._queue if job_uid_from_snapshot(item) == rec.job_uid),
172
+ None,
173
+ )
174
+ settled = any(
175
+ attempt.get("job_uid") == rec.job_uid
176
+ and attempt.get("attempt_no") == rec.attempt_no
177
+ for attempt in new_attempts.values()
178
+ )
179
+ validate_recovery_attempt_state(
180
+ rec,
181
+ present_in_queue=running is not None,
182
+ queue_status=running.get("status") if running is not None else None,
183
+ queue_run_id=running.get("run_id") if running is not None else None,
184
+ queue_attempt_no=running.get("attempt_no") if running is not None else None,
185
+ queue_execution_id=(
186
+ queue_snapshot_execution_id(running) if running is not None else None
187
+ ),
188
+ attempt_sequence=self._job_sequences.get(rec.job_uid),
189
+ already_settled=settled,
190
+ )
191
+ new_attempts[new_attempt_seq] = {
192
+ "attempt_id": new_attempt_seq,
193
+ "job_uid": rec.job_uid,
194
+ "attempt_no": rec.attempt_no,
195
+ "run_id": rec.run_id,
196
+ "outcome": "failure",
197
+ "started_at": rec.started_at,
198
+ "settled_at": rec.settled_at,
199
+ "job": copy.deepcopy(rec.job_snapshot),
200
+ "files": copy.deepcopy(rec.files),
201
+ "result": copy.deepcopy(rec.result),
202
+ "error_message": rec.error_message,
203
+ }
204
+ new_attempt_seq += 1
293
205
 
294
- failure_snapshot = self._snapshot_from_metadata(self._failed.get(uid))
295
- if failure_snapshot is not None:
296
- return copy.deepcopy(failure_snapshot)
206
+ touched_queue_uids = set(commit.queue_writes)
207
+ new_queue = [
208
+ j for j in self._queue if job_uid_from_snapshot(j) not in touched_queue_uids
209
+ ]
210
+ for uid, snap in commit.queue_writes.items():
211
+ if snap is not None:
212
+ clean = public_queue_snapshot(snap)
213
+ clean["status"] = "pending"
214
+ clean["run_id"] = None
215
+ clean["attempt_no"] = None
216
+ clean["started_at"] = None
217
+ new_queue.append(clean)
297
218
 
298
- for attempt_id in sorted(self._attempts, reverse=True):
299
- attempt = self._attempts[attempt_id]
300
- if attempt.get("job_uid") != uid:
301
- continue
302
- attempt_snapshot = attempt.get("job")
303
- if isinstance(attempt_snapshot, dict):
304
- return copy.deepcopy(attempt_snapshot)
305
- return None
219
+ new_successes = dict(self._successes)
220
+ for uid, meta in commit.success_writes.items():
221
+ if meta is None:
222
+ new_successes.pop(uid, None)
223
+ else:
224
+ new_successes[uid] = copy.deepcopy(meta)
306
225
 
307
- def load_known_job_snapshots(self) -> dict[str, dict[str, Any]]:
308
- """读取全部已知 Job 的完整配置,低优先级来源先写入。"""
309
- with self._lock:
310
- known: dict[str, dict[str, Any]] = {}
311
- for attempt_id in sorted(self._attempts):
312
- attempt = self._attempts[attempt_id]
313
- uid = attempt.get("job_uid")
314
- snapshot = attempt.get("job")
315
- if isinstance(uid, str) and isinstance(snapshot, dict):
316
- known[uid] = copy.deepcopy(snapshot)
317
-
318
- for uid, metadata in self._failed.items():
319
- snapshot = self._snapshot_from_metadata(metadata)
320
- if snapshot is not None:
321
- known[uid] = copy.deepcopy(snapshot)
322
-
323
- for uid, metadata in self._successes.items():
324
- snapshot = self._snapshot_from_metadata(metadata)
325
- if snapshot is not None:
326
- known[uid] = copy.deepcopy(snapshot)
327
-
328
- for snapshot in self._queue:
329
- known[job_uid_from_snapshot(snapshot)] = public_queue_snapshot(snapshot)
330
- return known
331
-
332
- def clear_history(self, uid: str, records: set[str]) -> int:
333
- """从 successes/failed/attempts 清除指定 job_uid 的记录,返回删除条数。"""
334
- total = 0
335
- with self._lock:
336
- if "successes" in records and uid in self._successes:
337
- del self._successes[uid]
338
- total += 1
339
- if "failures" in records:
340
- if uid in self._failed:
341
- del self._failed[uid]
342
- total += 1
343
- self._failure_payloads.pop(uid, None)
344
- if "attempts" in records:
345
- initial = len(self._attempts)
346
- self._attempts = {
347
- k: v for k, v in self._attempts.items()
348
- if v.get("job_uid") != uid
349
- }
350
- total += initial - len(self._attempts)
351
- return total
226
+ new_failed = dict(self._failed)
227
+ new_failure_payloads = dict(self._failure_payloads)
228
+ for uid, entry in commit.failed_writes.items():
229
+ if entry is None:
230
+ new_failed.pop(uid, None)
231
+ new_failure_payloads.pop(uid, None)
232
+ else:
233
+ fail_meta, payload = entry
234
+ new_failed[uid] = copy.deepcopy(fail_meta)
235
+ if payload is not None:
236
+ new_failure_payloads[uid] = copy.deepcopy(payload)
237
+ else:
238
+ new_failure_payloads.pop(uid, None)
239
+
240
+ overlap = new_successes.keys() & new_failed.keys()
241
+ if overlap:
242
+ sample = next(iter(sorted(overlap)))
243
+ raise TaskLiteError(
244
+ f"Invariant conflict: job {sample!r} cannot exist in both successes and failed"
245
+ )
246
+
247
+ self._attempts = new_attempts
248
+ self._attempt_seq = new_attempt_seq
249
+ self._queue = new_queue
250
+ self._successes = new_successes
251
+ self._failed = new_failed
252
+ self._failure_payloads = new_failure_payloads
352
253
 
353
254
  def get_cursor(self, key: str) -> str | None:
354
255
  """查询单个游标的最新已提交值,不存在返回 None。"""
355
- if not isinstance(key, str) or not key:
356
- raise TypeError(f"cursor key must be a non-empty str, got {key!r}")
256
+ validate_cursor_key(key)
357
257
  with self._lock:
358
258
  return self._cursors.get(key)
359
259
 
360
260
  def set_cursor(self, key: str, value: str | None) -> None:
361
261
  """设置或删除单个游标(None 为删除)。"""
362
- if not isinstance(key, str) or not key:
363
- raise TypeError(f"cursor key must be a non-empty str, got {key!r}")
364
- if value is not None and not isinstance(value, str):
365
- raise TypeError(f"cursor value must be str or None, got {type(value).__name__}")
262
+ validate_cursor_key(key)
263
+ validate_cursor_value(value)
366
264
  with self._lock:
367
265
  if value is None:
368
266
  self._cursors.pop(key, None)
@@ -371,7 +269,6 @@ class InMemoryStateBackend(AbstractStateBackend):
371
269
 
372
270
  # 尝试轨迹(append-only 旁路观测面)--------------------------------
373
271
 
374
-
375
272
  def load_latest_succeeded_finished_at(self, job_uid: str) -> str | None:
376
273
  """按 attempt_id 倒序读取指定 Job 最新成功 Attempt 的结算时间。"""
377
274
  with self._lock:
@@ -382,10 +279,6 @@ class InMemoryStateBackend(AbstractStateBackend):
382
279
 
383
280
  # 元数据 ---------------------------------------------------------
384
281
 
385
- def get_engine_metadata(self, key: str) -> str | None:
386
- with self._lock:
387
- return self._engine_metadata.get(key)
388
-
389
282
  def set_engine_metadata(self, key: str, value: str) -> None:
390
283
  with self._lock:
391
284
  self._engine_metadata[key] = str(value)
@@ -395,25 +288,22 @@ class InMemoryStateBackend(AbstractStateBackend):
395
288
  def mark_job_running(
396
289
  self, job_uid: str, *, execution_id: str, run_id: str, started_at: str
397
290
  ) -> int:
398
- if not isinstance(execution_id, str) or not execution_id:
399
- raise ValueError("execution_id must be a non-empty str")
400
- if not isinstance(run_id, str) or not run_id:
401
- raise ValueError("run_id must be a non-empty str")
402
- if not execution_id_matches_run(execution_id, run_id):
403
- raise ValueError(f"execution_id {execution_id!r} does not belong to run {run_id!r}")
404
- if not isinstance(started_at, str) or not started_at:
405
- raise ValueError("started_at must be a non-empty str")
291
+ validate_mark_job_running_args(
292
+ execution_id=execution_id, run_id=run_id, started_at=started_at
293
+ )
406
294
  with self._lock:
407
295
  job_idx = None
408
296
  for idx, item in enumerate(self._queue):
409
297
  if job_uid_from_snapshot(item) == job_uid:
410
298
  job_idx = idx
411
299
  break
412
- if job_idx is None:
413
- raise ValueError(f"Job {job_uid} not found in queue")
300
+ validate_mark_job_running_state(
301
+ job_uid,
302
+ present_in_queue=job_idx is not None,
303
+ queue_status=self._queue[job_idx].get("status") if job_idx is not None else None,
304
+ )
305
+ assert job_idx is not None
414
306
  job_data = self._queue[job_idx]
415
- if job_data.get("status") == "running":
416
- raise ValueError(f"Job {job_uid} is already running")
417
307
 
418
308
  next_no = self._job_sequences.get(job_uid, 0) + 1
419
309
  self._job_sequences[job_uid] = next_no
@@ -430,14 +320,20 @@ class InMemoryStateBackend(AbstractStateBackend):
430
320
  with self._lock:
431
321
  return self._job_sequences.get(job_uid, 0)
432
322
 
433
- def clear_attempts(self, job_uid: str) -> int:
434
- with self._lock:
435
- initial = len(self._attempts)
436
- self._attempts = {
437
- k: v for k, v in self._attempts.items()
438
- if v.get("job_uid") != job_uid
323
+ def load_consistent_snapshot(self) -> dict[str, Any]:
324
+ """在单锁内原子捕获一致内存状态快照供恢复、入队、StateSnapshot 与 EditTransaction 使用。"""
325
+ with self._lock:
326
+ return {
327
+ "queue_jobs": self.load_queue_jobs(),
328
+ "successes": copy.deepcopy(self._successes),
329
+ "failed": copy.deepcopy(self._failed),
330
+ "failure_payloads": copy.deepcopy(self._failure_payloads),
331
+ "cursors": dict(self._cursors),
332
+ # attempts 单条记录入库时已深拷贝不可变,锁内仅浅拷贝外层列表以控制峰值内存;
333
+ # 查询输出的深拷贝隔离由快照投影核心负责。
334
+ "attempts": list(self._attempts.values()),
335
+ "job_sequences": dict(self._job_sequences),
439
336
  }
440
- return initial - len(self._attempts)
441
337
 
442
338
  def load_settled_attempts(self, job_uid: str) -> list[dict[str, Any]]:
443
339
  with self._lock:
@@ -489,46 +385,40 @@ class InMemoryStateBackend(AbstractStateBackend):
489
385
  requeued_job_snapshot: dict[str, Any] | None = None,
490
386
  record_attempt: bool = True,
491
387
  ) -> None:
492
- if outcome not in ("success", "failure", "retry", "pending"):
493
- raise ValueError(f"Invalid outcome: {outcome}")
494
- if not isinstance(attempt_no, int) or isinstance(attempt_no, bool) or attempt_no < 1:
495
- raise TypeError(f"attempt_no must be int >= 1, got {attempt_no!r}")
496
- if not isinstance(execution_id, str) or not execution_id:
497
- raise ValueError(f"execution_id must be non-empty str, got {execution_id!r}")
498
- if not isinstance(run_id, str) or not run_id:
499
- raise ValueError(f"run_id must be non-empty str, got {run_id!r}")
500
- if not execution_id_matches_run(execution_id, run_id):
501
- raise ValueError(f"execution_id {execution_id!r} does not belong to run {run_id!r}")
502
- if not isinstance(settled_at, str) or not settled_at:
503
- raise ValueError(f"settled_at must be non-empty str, got {settled_at!r}")
504
- if started_at is not None and (not isinstance(started_at, str) or not started_at):
505
- raise ValueError("started_at must be non-empty str or None")
506
- if cursor_updates:
507
- for k, v in cursor_updates.items():
508
- if not isinstance(k, str) or not k:
509
- raise ValueError(f"cursor key must be a non-empty str, got {k!r}")
510
- if v is not None and not isinstance(v, str):
511
- raise TypeError(f"cursor value must be str or None, got {type(v).__name__}")
512
- if spawned_job_snapshots:
513
- validate_queue_replacement(list(spawned_job_snapshots))
388
+ validate_settlement_args(
389
+ outcome=outcome,
390
+ attempt_no=attempt_no,
391
+ execution_id=execution_id,
392
+ run_id=run_id,
393
+ settled_at=settled_at,
394
+ started_at=started_at,
395
+ cursor_updates=cursor_updates,
396
+ spawned_job_snapshots=spawned_job_snapshots,
397
+ )
514
398
 
515
399
  with self._lock:
516
400
  running = next(
517
- (item for item in self._queue if job_uid_from_snapshot(item) == job_uid), {}
401
+ (item for item in self._queue if job_uid_from_snapshot(item) == job_uid), None
518
402
  )
519
- if (
520
- running.get("status"),
521
- running.get("run_id"),
522
- running.get("attempt_no"),
523
- queue_snapshot_execution_id(running),
524
- ) != ("running", run_id, attempt_no, execution_id):
525
- raise TaskLiteError(f"Settlement does not match the running execution for {job_uid}")
526
- if any(
403
+ settled = any(
527
404
  attempt.get("job_uid") == job_uid
528
405
  and attempt.get("attempt_no") == attempt_no
529
406
  for attempt in self._attempts.values()
530
- ):
531
- raise TaskLiteError(f"Execution for {job_uid} attempt {attempt_no} is already settled")
407
+ )
408
+ validate_running_settlement_state(
409
+ job_uid,
410
+ present_in_queue=running is not None,
411
+ queue_status=running.get("status") if running is not None else None,
412
+ queue_run_id=running.get("run_id") if running is not None else None,
413
+ queue_attempt_no=running.get("attempt_no") if running is not None else None,
414
+ queue_execution_id=(
415
+ queue_snapshot_execution_id(running) if running is not None else None
416
+ ),
417
+ run_id=run_id,
418
+ attempt_no=attempt_no,
419
+ execution_id=execution_id,
420
+ already_settled=settled,
421
+ )
532
422
 
533
423
  new_attempts = dict(self._attempts)
534
424
  new_attempt_id = self._attempt_seq
@@ -623,7 +513,6 @@ class InMemoryStateBackend(AbstractStateBackend):
623
513
  new_queue[idx] = target
624
514
  break
625
515
 
626
- # 统一原子落变
627
516
  self._attempts = new_attempts
628
517
  if record_attempt:
629
518
  self._attempt_seq += 1
@@ -633,6 +522,38 @@ class InMemoryStateBackend(AbstractStateBackend):
633
522
  self._failure_payloads = new_failure_payloads
634
523
  self._cursors = new_cursors
635
524
 
525
+ def _existing_auth_pairs(self) -> list[tuple[str, TargetType]]:
526
+ return [
527
+ (rec["path"], cast(TargetType, rec["target_type"]))
528
+ for rec in self._authorizations.values()
529
+ ]
530
+
531
+ def grant_authorization(
532
+ self,
533
+ path: str,
534
+ target_type: Literal["file", "directory"],
535
+ *,
536
+ authorized_at: str | None = None,
537
+ ) -> dict[str, Any]:
538
+ norm_path = normalize_authorization_path(path)
539
+ validated_type = validate_authorization_target_type(target_type, error_type=TaskLiteError)
540
+ ts = resolve_authorized_at(authorized_at)
541
+ with self._lock:
542
+ match = evaluate_authorization(
543
+ self._existing_auth_pairs(),
544
+ norm_path,
545
+ validated_type,
546
+ )
547
+ if match.grant_conflict is not None:
548
+ raise TaskLiteError(match.grant_conflict)
549
+ record = {
550
+ "path": norm_path,
551
+ "target_type": validated_type,
552
+ "authorized_at": ts,
553
+ }
554
+ self._authorizations[norm_path] = record
555
+ return dict(record)
556
+
636
557
  def record_authorization(
637
558
  self,
638
559
  path: str,
@@ -640,46 +561,47 @@ class InMemoryStateBackend(AbstractStateBackend):
640
561
  *,
641
562
  authorized_at: str | None = None,
642
563
  ) -> None:
643
- norm_path = os.path.normpath(os.fspath(path))
644
- if target_type not in ("file", "directory"):
645
- raise ValueError(f"target_type must be 'file' or 'directory', got {target_type!r}")
646
- ts = authorized_at if authorized_at is not None else utc_now_iso()
647
- with self._lock:
564
+ norm_path = normalize_authorization_path(path)
565
+ validated_type = validate_authorization_target_type(target_type, error_type=ValueError)
566
+ ts = resolve_authorized_at(authorized_at)
567
+ with self._lock:
568
+ match = evaluate_authorization(
569
+ self._existing_auth_pairs(),
570
+ norm_path,
571
+ validated_type,
572
+ )
573
+ if match.exact_path is not None and match.exact_path != norm_path:
574
+ self._authorizations.pop(match.exact_path, None)
648
575
  self._authorizations[norm_path] = {
649
576
  "path": norm_path,
650
- "target_type": target_type,
577
+ "target_type": validated_type,
651
578
  "authorized_at": ts,
652
579
  }
653
580
 
654
581
  def list_authorizations(self) -> list[dict[str, Any]]:
655
582
  with self._lock:
656
- records = list(self._authorizations.values())
583
+ records = [dict(rec) for rec in self._authorizations.values()]
657
584
  return sorted(records, key=lambda r: (r["authorized_at"], r["path"]))
658
585
 
659
586
  def revoke_authorization(self, path: str) -> bool:
660
- norm_path = os.path.normpath(os.fspath(path))
587
+ norm_path = normalize_authorization_path(path)
661
588
  with self._lock:
662
- if norm_path in self._authorizations:
663
- del self._authorizations[norm_path]
664
- return True
665
- return False
589
+ match = evaluate_authorization(self._existing_auth_pairs(), norm_path)
590
+ if match.exact_path is None:
591
+ return False
592
+ self._authorizations.pop(match.exact_path, None)
593
+ return True
666
594
 
667
595
  def is_path_authorized(self, path: str, target_type: str) -> bool:
668
- norm_path = os.path.normpath(os.fspath(path))
669
- target_p = Path(norm_path)
596
+ norm_path = normalize_authorization_path(path)
597
+ if not is_valid_authorization_target_type(target_type):
598
+ return False
670
599
  with self._lock:
671
- exact = self._authorizations.get(norm_path)
672
- if exact is not None and exact["target_type"] == target_type:
673
- return True
674
- for record in self._authorizations.values():
675
- if record["target_type"] == "directory":
676
- dir_path = Path(record["path"])
677
- try:
678
- if target_p.is_relative_to(dir_path):
679
- return True
680
- except (ValueError, TypeError):
681
- pass
682
- return False
600
+ return evaluate_authorization(
601
+ self._existing_auth_pairs(),
602
+ norm_path,
603
+ cast(TargetType, target_type),
604
+ ).covered
683
605
 
684
606
  def close(self) -> None:
685
607
  """关闭后端并释放资源(幂等)。"""