tasklite-engine 2.2.0__py3-none-any.whl → 3.0.0.dev0__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 (57) hide show
  1. tasklite/__init__.py +30 -196
  2. tasklite/backend/__init__.py +2 -5
  3. tasklite/backend/base.py +156 -184
  4. tasklite/backend/memory.py +468 -231
  5. tasklite/backend/sqlite_backend.py +680 -408
  6. tasklite/engine/__init__.py +2 -2
  7. tasklite/engine/admission.py +85 -44
  8. tasklite/engine/channel.py +566 -458
  9. tasklite/engine/completion.py +535 -247
  10. tasklite/engine/config.py +7 -131
  11. tasklite/engine/dispatch.py +415 -321
  12. tasklite/engine/execution_access.py +39 -0
  13. tasklite/engine/files.py +52 -0
  14. tasklite/engine/governor.py +46 -204
  15. tasklite/engine/in_flight.py +15 -13
  16. tasklite/engine/ops.py +9 -347
  17. tasklite/engine/recovery.py +67 -267
  18. tasklite/engine/resource.py +256 -386
  19. tasklite/engine/runtime.py +527 -236
  20. tasklite/engine/scheduler.py +99 -90
  21. tasklite/engine/selection.py +53 -111
  22. tasklite/engine/session.py +49 -77
  23. tasklite/engine/store.py +595 -564
  24. tasklite/engine/types.py +66 -71
  25. tasklite/engine/wait.py +30 -16
  26. tasklite/exceptions.py +4 -57
  27. tasklite/hooks.py +3 -23
  28. tasklite/models/__init__.py +21 -6
  29. tasklite/models/artifact.py +386 -47
  30. tasklite/models/context.py +173 -203
  31. tasklite/models/job.py +115 -266
  32. tasklite/models/result.py +246 -0
  33. tasklite/models/state.py +97 -17
  34. tasklite/models/task.py +52 -105
  35. tasklite/pipeline.py +279 -534
  36. tasklite/resource.py +12 -0
  37. tasklite/selection.py +9 -97
  38. tasklite/snapshot.py +639 -0
  39. tasklite/testing.py +32 -34
  40. tasklite/triggers.py +5 -4
  41. tasklite/utils/artifact.py +85 -17
  42. tasklite/utils/clock.py +3 -3
  43. tasklite/utils/encoding.py +113 -18
  44. tasklite/utils/ipc.py +240 -242
  45. tasklite/utils/lockfile.py +33 -58
  46. tasklite/wrappers/__init__.py +1 -1
  47. tasklite/wrappers/discovery.py +155 -158
  48. tasklite/wrappers/http.py +68 -481
  49. tasklite_engine-3.0.0.dev0.dist-info/METADATA +307 -0
  50. tasklite_engine-3.0.0.dev0.dist-info/RECORD +58 -0
  51. tasklite/engine/errorclass.py +0 -971
  52. tasklite/models/attempt.py +0 -141
  53. tasklite_engine-2.2.0.dist-info/METADATA +0 -369
  54. tasklite_engine-2.2.0.dist-info/RECORD +0 -55
  55. {tasklite_engine-2.2.0.dist-info → tasklite_engine-3.0.0.dev0.dist-info}/WHEEL +0 -0
  56. {tasklite_engine-2.2.0.dist-info → tasklite_engine-3.0.0.dev0.dist-info}/licenses/LICENSE +0 -0
  57. {tasklite_engine-2.2.0.dist-info → tasklite_engine-3.0.0.dev0.dist-info}/top_level.txt +0 -0
@@ -1,12 +1,13 @@
1
1
  """SQLite 状态后端(SQLiteStateBackend)。
2
2
 
3
- queue / successes / failed / attempts / cursors / engine_metadata 六表合一的单 ACID 库。
3
+ 队列、档案、Attempt、编号、游标与授权共享单 ACID 库。
4
4
  全新 schema、零旧库兼容:user_version 只认本代版本号或全新库(0),
5
5
  任何旧版本(含 v1 各代)fail-loud 拒绝启动,不写迁移路径。
6
6
  """
7
7
  from __future__ import annotations
8
8
 
9
9
  import logging
10
+ import os
10
11
  import sqlite3
11
12
  from contextlib import contextmanager
12
13
  from pathlib import Path
@@ -14,43 +15,91 @@ from typing import Any, Callable, Mapping, Sequence
14
15
 
15
16
  from .base import (
16
17
  AbstractStateBackend,
17
- validate_attempt_dispatch,
18
- validate_attempt_finish,
18
+ execution_id_matches_run,
19
+ public_queue_snapshot,
20
+ queue_snapshot_execution_id,
21
+ queue_snapshot_with_execution_id,
19
22
  validate_queue_replacement,
20
23
  )
21
- from ..models.attempt import AttemptRecord
24
+ from ..exceptions import TaskLiteError
22
25
  from ..models.state import job_uid_from_snapshot
26
+ from ..utils.clock import utc_now_iso
23
27
  from ..utils.jsonutil import dumps, loads
24
28
 
25
29
  logger = logging.getLogger("tasklite")
26
30
 
27
31
  # 只接纳本代完整形状或真正空库,不提供自动迁移。
28
- _SCHEMA_VERSION = 5
32
+ TARGET_SCHEMA_VERSION = 6
29
33
 
30
34
  # 核心表的精确列集合;不扩大为 SQL 类型与约束审计。
31
35
  _TABLE_COLUMNS: dict[str, tuple[str, ...]] = {
32
- "queue": ("job_uid", "queue_position", "job_snapshot"),
36
+ "queue": (
37
+ "job_uid", "queue_position", "job_snapshot", "status", "run_id", "attempt_no", "started_at",
38
+ ),
33
39
  "successes": ("job_uid", "metadata"),
34
40
  "failed": ("job_uid", "metadata", "payload"),
35
41
  "attempts": (
36
- "attempt_id", "job_uid", "activation_no", "attempt_no", "execution_id",
37
- "run_id", "started_at", "finished_at", "outcome", "error_message",
42
+ "attempt_id", "job_uid", "attempt_no", "run_id", "outcome", "started_at",
43
+ "settled_at", "job_snapshot", "files", "result", "error_message",
38
44
  ),
45
+ "job_sequences": ("job_uid", "last_attempt_no"),
39
46
  "cursors": ("key", "value"),
40
47
  "engine_metadata": ("key", "value"),
41
48
  }
42
49
 
43
50
 
51
+ def _schema_error(path: Path, detail: str) -> TaskLiteError:
52
+ return TaskLiteError(
53
+ f"{path}: {detail}; 目标 schema {TARGET_SCHEMA_VERSION}。"
54
+ "请保留原库,使用匹配版本读取历史,或显式选择新的状态库路径。"
55
+ )
56
+
57
+
58
+ def _check_schema(
59
+ conn: sqlite3.Connection, path: Path,
60
+ ) -> int:
61
+ version = conn.execute("PRAGMA user_version").fetchone()[0]
62
+ objects = list(conn.execute(
63
+ "SELECT name, type FROM sqlite_master WHERE name NOT GLOB 'sqlite_*'"
64
+ ))
65
+ if version == 0:
66
+ if objects:
67
+ raise _schema_error(
68
+ path,
69
+ f"Unsupported table shape: version 0 非空库,已有对象 {sorted(objects)}"
70
+ )
71
+ return version
72
+ if version != TARGET_SCHEMA_VERSION:
73
+ raise _schema_error(path, f"Unsupported database schema version {version}")
74
+ table_objects = {name: kind for name, kind in objects if kind in ("table", "view")}
75
+ if {"wall", "meta"} & {name.casefold() for name, kind in objects if kind == "table"}:
76
+ raise _schema_error(
77
+ path, f"Unsupported table shape: version {version} 含异代 wall/meta 表"
78
+ )
79
+ for table, expected in _TABLE_COLUMNS.items():
80
+ if table_objects.get(table) != "table":
81
+ raise _schema_error(
82
+ path,
83
+ f"Unsupported table shape for '{table}': version {version}, "
84
+ f"对象类型 {table_objects.get(table)!r},必须为 table"
85
+ )
86
+ columns = {row[1] for row in conn.execute(f'PRAGMA table_xinfo("{table}")')}
87
+ if columns != set(expected):
88
+ raise _schema_error(
89
+ path,
90
+ f"Unsupported table shape for '{table}': version {version}, "
91
+ f"expected columns {expected}, found {sorted(columns)}"
92
+ )
93
+ return version
94
+
95
+
44
96
  class SQLiteStateBackend(AbstractStateBackend):
45
97
  """原子 SQLite 状态后端:逐 job 单事务碎片化的 delta 提交。"""
46
98
 
47
99
  def __init__(self, filepath: str | Path):
48
100
  self.path = Path(filepath)
49
- try:
50
- self.path.parent.mkdir(parents=True, exist_ok=True)
51
- self._init_db()
52
- except Exception as e:
53
- raise self._schema_error(f"SQLite backend initialization failed: {e}") from e
101
+ self.path.parent.mkdir(parents=True, exist_ok=True)
102
+ self._init_db()
54
103
 
55
104
  @contextmanager
56
105
  def _get_conn(self):
@@ -89,56 +138,19 @@ class SQLiteStateBackend(AbstractStateBackend):
89
138
 
90
139
  # 初始化与 schema -------------------------------------------------
91
140
 
92
- def _schema_error(self, detail: str) -> RuntimeError:
93
- return RuntimeError(
94
- f"{self.path}: {detail}; 目标 schema {_SCHEMA_VERSION}。"
95
- "请保留原库,使用匹配版本读取历史,或显式选择新的状态库路径。"
96
- )
97
-
98
141
  def _check_schema(self, conn: sqlite3.Connection) -> int:
99
- version = conn.execute("PRAGMA user_version").fetchone()[0]
100
- objects = list(conn.execute(
101
- "SELECT name, type FROM sqlite_master WHERE name NOT GLOB 'sqlite_*'"
102
- ))
103
- if version == 0:
104
- if objects:
105
- raise self._schema_error(
106
- f"Unsupported table shape: version 0 非空库,已有对象 {sorted(objects)}"
107
- )
108
- return version
109
- if version != _SCHEMA_VERSION:
110
- raise self._schema_error(f"Unsupported database schema version {version}")
111
- table_objects = {name: kind for name, kind in objects if kind in ("table", "view")}
112
- if {"wall", "meta"} & {name.casefold() for name, kind in objects if kind == "table"}:
113
- raise self._schema_error(f"Unsupported table shape: version {version} 含异代 wall/meta 表")
114
- for table, expected in _TABLE_COLUMNS.items():
115
- if table_objects.get(table) != "table":
116
- raise self._schema_error(
117
- f"Unsupported table shape for '{table}': version {version}, "
118
- f"对象类型 {table_objects.get(table)!r},必须为 table"
119
- )
120
- columns = {row[1] for row in conn.execute(f'PRAGMA table_xinfo("{table}")')}
121
- if columns != set(expected):
122
- raise self._schema_error(
123
- f"Unsupported table shape for '{table}': version {version}, "
124
- f"expected columns {expected}, found {sorted(columns)}"
125
- )
126
- return version
142
+ return _check_schema(conn, self.path)
127
143
 
128
144
  def _preflight_schema(self) -> None:
129
145
  try:
130
146
  self.path.stat()
131
147
  except FileNotFoundError:
132
148
  return
133
- except OSError as exc:
134
- raise self._schema_error(f"无法只读确认版本或形状:{exc}") from exc
135
149
  conn = None
136
150
  try:
137
151
  # 普通只读连接必须看到 WAL 中已提交的版本与结构。
138
152
  conn = sqlite3.connect(self.path.resolve().as_uri() + "?mode=ro", uri=True)
139
153
  self._check_schema(conn)
140
- except (sqlite3.Error, OSError) as exc:
141
- raise self._schema_error(f"无法只读确认版本或形状:{exc}") from exc
142
154
  finally:
143
155
  if conn is not None:
144
156
  conn.close()
@@ -149,7 +161,7 @@ class SQLiteStateBackend(AbstractStateBackend):
149
161
  self._check_schema(conn)
150
162
  wal_row = conn.execute('PRAGMA journal_mode=WAL').fetchone()
151
163
  if not wal_row or str(wal_row[0]).lower() != 'wal':
152
- raise RuntimeError(
164
+ raise TaskLiteError(
153
165
  f"journal_mode=WAL could not be engaged on {self.path} "
154
166
  f"(got {wal_row[0] if wal_row else None!r})."
155
167
  )
@@ -158,15 +170,19 @@ class SQLiteStateBackend(AbstractStateBackend):
158
170
  if version == 0:
159
171
  self._create_tables(conn)
160
172
  self._create_indexes(conn)
161
- conn.execute(f"PRAGMA user_version = {_SCHEMA_VERSION}")
173
+ conn.execute(f"PRAGMA user_version = {TARGET_SCHEMA_VERSION}")
162
174
 
163
175
  def _create_tables(self, conn: sqlite3.Connection) -> None:
164
- """只在已确认的空库写事务中建立六张核心表。"""
176
+ """只在已确认的空库写事务中建立核心表。"""
165
177
  conn.execute('''
166
178
  CREATE TABLE IF NOT EXISTS queue (
167
179
  job_uid TEXT PRIMARY KEY,
168
180
  queue_position INTEGER NOT NULL,
169
- job_snapshot TEXT NOT NULL
181
+ job_snapshot TEXT NOT NULL,
182
+ status TEXT NOT NULL DEFAULT 'pending',
183
+ run_id TEXT,
184
+ attempt_no INTEGER,
185
+ started_at TEXT
170
186
  )
171
187
  ''')
172
188
  conn.execute('''
@@ -186,16 +202,23 @@ class SQLiteStateBackend(AbstractStateBackend):
186
202
  CREATE TABLE IF NOT EXISTS attempts (
187
203
  attempt_id INTEGER PRIMARY KEY AUTOINCREMENT,
188
204
  job_uid TEXT NOT NULL,
189
- activation_no INTEGER NOT NULL,
190
205
  attempt_no INTEGER NOT NULL,
191
- execution_id TEXT NOT NULL,
192
206
  run_id TEXT NOT NULL,
193
- started_at TEXT NOT NULL,
194
- finished_at TEXT,
195
207
  outcome TEXT NOT NULL,
208
+ started_at TEXT,
209
+ settled_at TEXT NOT NULL,
210
+ job_snapshot TEXT,
211
+ files TEXT,
212
+ result TEXT,
196
213
  error_message TEXT
197
214
  )
198
215
  ''')
216
+ conn.execute('''
217
+ CREATE TABLE IF NOT EXISTS job_sequences (
218
+ job_uid TEXT PRIMARY KEY,
219
+ last_attempt_no INTEGER NOT NULL
220
+ )
221
+ ''')
199
222
  conn.execute('''
200
223
  CREATE TABLE IF NOT EXISTS cursors (
201
224
  key TEXT PRIMARY KEY,
@@ -208,17 +231,23 @@ class SQLiteStateBackend(AbstractStateBackend):
208
231
  value TEXT NOT NULL
209
232
  )
210
233
  ''')
234
+ conn.execute('''
235
+ CREATE TABLE IF NOT EXISTS authorizations (
236
+ path TEXT PRIMARY KEY,
237
+ target_type TEXT NOT NULL,
238
+ authorized_at TEXT NOT NULL
239
+ )
240
+ ''')
211
241
 
212
242
  def _create_indexes(self, conn: sqlite3.Connection) -> None:
213
243
  """建索引(在形状校验之后:异形表先给出明确的拒绝信息,而非
214
244
  在缺列上建索引时抛出费解的 no such column)。"""
215
245
  conn.execute('CREATE INDEX IF NOT EXISTS idx_queue_position ON queue(queue_position)')
216
246
  conn.execute('CREATE INDEX IF NOT EXISTS idx_attempts_job_uid ON attempts(job_uid)')
217
- # 可信基线窄查询(job_uid + outcome 定位,rowid 即 attempt_id 隐式随索引有序)
218
- conn.execute(
219
- 'CREATE INDEX IF NOT EXISTS idx_attempts_job_uid_outcome '
220
- 'ON attempts(job_uid, outcome)'
221
- )
247
+ conn.execute('CREATE INDEX IF NOT EXISTS idx_queue_status ON queue(status)')
248
+ conn.execute('CREATE INDEX IF NOT EXISTS idx_attempts_job_uid_outcome ON attempts(job_uid, outcome)')
249
+ conn.execute('CREATE INDEX IF NOT EXISTS idx_attempts_job_uid_attempt_no ON attempts(job_uid, attempt_no)')
250
+
222
251
 
223
252
  # 序号分配 ---------------------------------------------------------
224
253
 
@@ -246,63 +275,42 @@ class SQLiteStateBackend(AbstractStateBackend):
246
275
  def load_successes(self) -> dict[str, dict[str, Any]]:
247
276
  if not self.path.exists():
248
277
  return {}
249
- try:
250
- with self._get_conn() as conn:
251
- cursor = conn.execute('SELECT job_uid, metadata FROM successes')
252
- return {row[0]: loads(row[1]) for row in cursor}
253
- except (sqlite3.Error, OSError) as e:
254
- raise RuntimeError(f"Failed to load successes from {self.path.name}: {e}") from e
255
- except ValueError as e:
256
- raise RuntimeError(f"Corrupted successes metadata in {self.path.name}: {e}") from e
278
+ with self._get_conn() as conn:
279
+ cursor = conn.execute('SELECT job_uid, metadata FROM successes')
280
+ return {row[0]: loads(row[1]) for row in cursor}
257
281
 
258
282
  def load_failed(self) -> dict[str, dict[str, Any]]:
259
283
  if not self.path.exists():
260
284
  return {}
261
- try:
262
- with self._get_conn() as conn:
263
- cursor = conn.execute('SELECT job_uid, metadata FROM failed')
264
- return {row[0]: loads(row[1]) for row in cursor}
265
- except (sqlite3.Error, OSError) as e:
266
- raise RuntimeError(f"Failed to load failed archive from {self.path.name}: {e}") from e
267
- except ValueError as e:
268
- raise RuntimeError(f"Corrupted failed metadata in {self.path.name}: {e}") from e
285
+ with self._get_conn() as conn:
286
+ cursor = conn.execute('SELECT job_uid, metadata FROM failed')
287
+ return {row[0]: loads(row[1]) for row in cursor}
269
288
 
270
289
  def load_failure_payloads(self) -> dict[str, dict[str, Any]]:
271
290
  """读取失败档案各 job_uid 的原始业务 payload 快照(无快照的 job_uid 不出现)。"""
272
291
  if not self.path.exists():
273
292
  return {}
274
- try:
275
- with self._get_conn() as conn:
276
- cursor = conn.execute(
277
- 'SELECT job_uid, payload FROM failed WHERE payload IS NOT NULL'
278
- )
279
- return {row[0]: loads(row[1]) for row in cursor}
280
- except (sqlite3.Error, OSError) as e:
281
- raise RuntimeError(f"Failed to load failure payloads from {self.path.name}: {e}") from e
282
- except ValueError as e:
283
- raise RuntimeError(f"Corrupted failed payload in {self.path.name}: {e}") from e
293
+ with self._get_conn() as conn:
294
+ cursor = conn.execute(
295
+ 'SELECT job_uid, payload FROM failed WHERE payload IS NOT NULL'
296
+ )
297
+ return {row[0]: loads(row[1]) for row in cursor}
284
298
 
285
299
  def load_cursors(self) -> dict[str, str]:
286
300
  if not self.path.exists():
287
301
  return {}
288
- try:
289
- with self._get_conn() as conn:
290
- cursor = conn.execute('SELECT key, value FROM cursors')
291
- return {row[0]: row[1] for row in cursor}
292
- except (sqlite3.Error, OSError) as e:
293
- raise RuntimeError(f"Failed to load cursors from {self.path.name}: {e}") from e
302
+ with self._get_conn() as conn:
303
+ cursor = conn.execute('SELECT key, value FROM cursors')
304
+ return {row[0]: row[1] for row in cursor}
294
305
 
295
306
  def load_queue(self) -> list[dict[str, Any]]:
296
307
  if not self.path.exists():
297
308
  return []
298
- try:
299
- with self._get_conn() as conn:
300
- cursor = conn.execute('SELECT job_snapshot FROM queue ORDER BY queue_position ASC')
301
- return [loads(row[0]) for row in cursor]
302
- except (sqlite3.Error, OSError) as e:
303
- raise RuntimeError(f"Failed to load queue from {self.path.name}: {e}") from e
304
- except ValueError as e:
305
- raise RuntimeError(f"Corrupted queue job_snapshot in {self.path.name}: {e}") from e
309
+ with self._get_conn() as conn:
310
+ cursor = conn.execute(
311
+ "SELECT job_snapshot FROM queue WHERE status = 'pending' ORDER BY queue_position ASC"
312
+ )
313
+ return [public_queue_snapshot(loads(row[0])) for row in cursor]
306
314
 
307
315
  # 整表重写 ---------------------------------------------------------
308
316
 
@@ -320,7 +328,7 @@ class SQLiteStateBackend(AbstractStateBackend):
320
328
  conn.execute('DELETE FROM queue')
321
329
  if job_snapshots:
322
330
  seen: set[str] = set()
323
- rows: list[tuple[str, int, str]] = []
331
+ rows: list[tuple] = []
324
332
  for j in job_snapshots:
325
333
  u = job_uid_from_snapshot(j)
326
334
  if u in seen:
@@ -329,9 +337,19 @@ class SQLiteStateBackend(AbstractStateBackend):
329
337
  )
330
338
  continue
331
339
  seen.add(u)
332
- rows.append((u, len(rows), dumps(j)))
340
+ rows.append((
341
+ u,
342
+ len(rows),
343
+ dumps(j),
344
+ j.get("status", "pending"),
345
+ j.get("run_id"),
346
+ j.get("attempt_no"),
347
+ j.get("started_at"),
348
+ ))
333
349
  conn.executemany(
334
- 'INSERT OR REPLACE INTO queue (job_uid, queue_position, job_snapshot) VALUES (?, ?, ?)',
350
+ 'INSERT OR REPLACE INTO queue ('
351
+ 'job_uid, queue_position, job_snapshot, status, run_id, attempt_no, started_at'
352
+ ') VALUES (?, ?, ?, ?, ?, ?, ?)',
335
353
  rows,
336
354
  )
337
355
 
@@ -372,111 +390,6 @@ class SQLiteStateBackend(AbstractStateBackend):
372
390
 
373
391
  # delta 提交 ---------------------------------------------------------
374
392
 
375
- def commit_job_success(
376
- self,
377
- job_uid: str,
378
- result_metadata: dict,
379
- *,
380
- attempt_id: int | None = None,
381
- execution_id: str | None = None,
382
- finished_at: str | None = None,
383
- spawned_job_snapshots: Sequence[dict[str, Any]] = (),
384
- cursor_updates: Mapping[str, str | None] | None = None,
385
- ) -> bool:
386
- """原子 delta:同事务校验并终结对应 attempts 行 + 写 successes + 删 popped job_uid + 删 failed 残行 + 队头插 spawned + 更新 cursors。
387
-
388
- 失败或 attempts 行校验不通过时事务整体回滚,on-disk 队列、attempts 及全表保持不变。
389
- """
390
- if not isinstance(attempt_id, int) or isinstance(attempt_id, bool):
391
- logger.critical(
392
- f"Failed to commit job success for {job_uid} in {self.path.name}: "
393
- f"attempt_id must be an int, got {attempt_id!r}"
394
- )
395
- return False
396
- if execution_id is not None and (not isinstance(execution_id, str) or not execution_id):
397
- logger.critical(
398
- f"Failed to commit job success for {job_uid} in {self.path.name}: "
399
- f"execution_id must be a non-empty str or None, got {execution_id!r}"
400
- )
401
- return False
402
- try:
403
- validate_attempt_finish("succeeded", finished_at, None)
404
- with self._get_conn() as conn:
405
- # 读 attempts 运行态 + spawned 队头插入的 queue_position 分配是读-改-写:
406
- # 先取写锁再读,与并发写入互斥。
407
- conn.execute('BEGIN IMMEDIATE')
408
- attempt_row = conn.execute(
409
- 'SELECT job_uid, execution_id, outcome FROM attempts WHERE attempt_id = ?',
410
- (attempt_id,),
411
- ).fetchone()
412
- if attempt_row is None:
413
- raise RuntimeError(f"attempt {attempt_id} does not exist")
414
- row_uid, row_exec_id, row_outcome = attempt_row
415
- if row_uid != job_uid:
416
- raise RuntimeError(
417
- f"attempt {attempt_id} job_uid mismatch: expected {job_uid!r}, got {row_uid!r}"
418
- )
419
- if execution_id is not None and row_exec_id != execution_id:
420
- raise RuntimeError(
421
- f"attempt {attempt_id} execution_id mismatch: expected {execution_id!r}, got {row_exec_id!r}"
422
- )
423
- if row_outcome != "running":
424
- raise RuntimeError(
425
- f"attempt {attempt_id} already finalized with outcome {row_outcome!r}"
426
- )
427
- conn.execute(
428
- 'UPDATE attempts SET outcome = ?, finished_at = ?, error_message = NULL '
429
- 'WHERE attempt_id = ?',
430
- ("succeeded", finished_at, attempt_id),
431
- )
432
- conn.execute(
433
- 'INSERT OR REPLACE INTO successes (job_uid, metadata) VALUES (?, ?)',
434
- (job_uid, dumps(result_metadata or {})),
435
- )
436
- conn.execute('DELETE FROM queue WHERE job_uid = ?', (job_uid,))
437
- # 成功 commit 时清理 failed 同名残行——否则同一 job_uid 永久
438
- # 「既成功又失败」(失败档案与 successes 矛盾)。幂等,与
439
- # 「job 最终状态唯一」语义一致。
440
- conn.execute('DELETE FROM failed WHERE job_uid = ?', (job_uid,))
441
- if spawned_job_snapshots:
442
- queue_positions = self._queue_position_range(conn, len(spawned_job_snapshots), front=True)
443
- cur = conn.executemany(
444
- 'INSERT OR IGNORE INTO queue (job_uid, queue_position, job_snapshot) VALUES (?, ?, ?)',
445
- [(job_uid_from_snapshot(j), pos, dumps(j))
446
- for j, pos in zip(spawned_job_snapshots, queue_positions)],
447
- )
448
- # 防止 INSERT OR IGNORE 静默丢弃 spawn:若某个 spawned
449
- # job_uid 与磁盘队列冲突(内存 is_known 预筛后的漂移窗口),
450
- # 该 job 只存在于内存、磁盘从未持久化,进程崩溃后静默
451
- # 丢失(at-least-once 违约)。executemany 的 rowcount
452
- # 返回实际插入行数,rowcount < len 即检测到漂移 → 抛
453
- # 异常回滚返回 False 走崩溃契约(重启后 at-least-once
454
- # 重扫),而非静默掩盖。
455
- if cur.rowcount is not None and cur.rowcount < len(spawned_job_snapshots):
456
- logger.critical(
457
- f"commit_job_success for {job_uid}: "
458
- f"{len(spawned_job_snapshots) - cur.rowcount} spawned job(s) "
459
- f"silently dropped by INSERT OR IGNORE (disk/memory "
460
- f"drift). Returning False to trigger crash contract."
461
- )
462
- raise RuntimeError(
463
- f"spawned job job_uid conflict on disk for {job_uid}: "
464
- f"inserted {cur.rowcount}/{len(spawned_job_snapshots)}"
465
- )
466
- if cursor_updates:
467
- # None 值表示删除游标;非 None 值为 str(set_cursor 校验保证)
468
- for k, v in cursor_updates.items():
469
- if v is None:
470
- conn.execute('DELETE FROM cursors WHERE key = ?', (k,))
471
- else:
472
- conn.execute(
473
- 'INSERT OR REPLACE INTO cursors (key, value) VALUES (?, ?)',
474
- (k, v),
475
- )
476
- except Exception as e:
477
- logger.critical(f"Failed to commit job success for {job_uid} in {self.path.name}: {e}")
478
- return False
479
- return True
480
393
 
481
394
  def _write_failed_row(
482
395
  self,
@@ -485,7 +398,7 @@ class SQLiteStateBackend(AbstractStateBackend):
485
398
  meta: dict,
486
399
  payload: dict[str, Any] | None = None,
487
400
  ) -> None:
488
- """失败档案行写入的单一出口(commit_job_failure / commit_job_failures / append_failed 共用)。
401
+ """失败档案行写入的单一出口(commit_job_failure / commit_job_failures 共用)。
489
402
 
490
403
  failed 按 job_uid 唯一终态:INSERT OR REPLACE(最终状态唯一);失败
491
404
  次数与执行时间线由 attempts 旁路轨迹承接,本表不注入计数字段、
@@ -533,47 +446,20 @@ class SQLiteStateBackend(AbstractStateBackend):
533
446
  conn.execute('DELETE FROM successes WHERE job_uid = ?', (job_uid,))
534
447
  except Exception as e:
535
448
  logger.critical(f"Failed to commit job failure for {job_uid} in {self.path.name}: {e}")
536
- return False
449
+ raise
537
450
  return True
538
451
 
539
- def commit_skip(self, job_uid: str) -> bool:
540
- """delta 删除队列中已终态(重复)的 job_uid;不写 successes/failed。"""
452
+ def commit_skip(self, job_uid: str) -> None:
453
+ """移除 Trigger False 或重复候选;不写 successes/failed。"""
541
454
  try:
542
455
  with self._get_conn() as conn:
543
456
  conn.execute('DELETE FROM queue WHERE job_uid = ?', (job_uid,))
544
457
  except Exception as e:
545
458
  logger.critical(f"Failed to commit skip for {job_uid} in {self.path.name}: {e}")
546
- return False
547
- return True
548
-
549
- def commit_retry(
550
- self, popped_job_uid: str, requeued_job_snapshot: dict[str, Any], *, front: bool = False
551
- ) -> bool:
552
- """原子 delta:DELETE popped_job_uid + 按 front 插入 requeued_job_snapshot(同 job_uid DELETE+INSERT)。
459
+ raise
553
460
 
554
- 不写 successes/failed。popped_job_uid 已先删除,故同 job_uid 重插安全(用
555
- INSERT 而非 REPLACE)。不用 INSERT OR IGNORE——若 requeued job_uid 与
556
- 队列既有行冲突(本不该发生),静默丢弃会让 job 无声消失却返回
557
- True;普通 INSERT 让真实冲突抛异常 → 返回 False → 走崩溃契约。
558
- 失败时 on-disk 队列不变(popped job_uid 仍在)。
559
- """
560
- try:
561
- with self._get_conn() as conn:
562
- # queue_position 分配的读与随后的 INSERT 之间不能让并发方插入提交:
563
- # 先取写锁再读(事务纪律详见 _get_conn docstring)。
564
- conn.execute('BEGIN IMMEDIATE')
565
- conn.execute('DELETE FROM queue WHERE job_uid = ?', (popped_job_uid,))
566
- queue_positions = self._queue_position_range(conn, 1, front=front)
567
- conn.execute(
568
- 'INSERT INTO queue (job_uid, queue_position, job_snapshot) VALUES (?, ?, ?)',
569
- (job_uid_from_snapshot(requeued_job_snapshot), queue_positions[0], dumps(requeued_job_snapshot)),
570
- )
571
- except Exception as e:
572
- logger.critical(f"Failed to commit retry for {popped_job_uid} in {self.path.name}: {e}")
573
- return False
574
- return True
575
461
 
576
- def commit_job_failures(self, job_uids_metadata: list[tuple[str, dict]]) -> bool:
462
+ def commit_job_failures(self, job_uids_metadata: list[tuple[str, dict]]) -> None:
577
463
  """原子 delta:批量写失败档案 + 按 job_uid 精准删除队列行 + 批量清 successes 旧记录。
578
464
 
579
465
  与 commit_job_failure 对称,同一事务内批量 ``DELETE FROM successes``
@@ -596,21 +482,9 @@ class SQLiteStateBackend(AbstractStateBackend):
596
482
  )
597
483
  except Exception as e:
598
484
  logger.critical(f"Failed to commit bulk failure in {self.path.name}: {e}")
599
- return False
600
- return True
601
-
602
- def append_failed(self, job_uid: str, metadata: dict[str, Any] | None = None) -> None:
603
- try:
604
- with self._get_conn() as conn:
605
- # 快照保留的读-改-写必须持写事务串行化,否则并发 append
606
- # 基于同一旧快照各写各的(详见 _get_conn)。经
607
- # _write_failed_row 单一出口写入。
608
- conn.execute('BEGIN IMMEDIATE')
609
- self._write_failed_row(conn, job_uid, metadata or {})
610
- except Exception as e:
611
- logger.error(f"Failed to append to failed archive in {self.path.name}: {e}")
612
485
  raise
613
486
 
487
+
614
488
  # 增量入队 -----------------------------------------------------------
615
489
 
616
490
  def enqueue_jobs(self, job_snapshots: list[dict[str, Any]], *, front: bool = False) -> list[str]:
@@ -645,9 +519,20 @@ class SQLiteStateBackend(AbstractStateBackend):
645
519
  return []
646
520
  queue_positions = self._queue_position_range(conn, len(fresh), front=front)
647
521
  conn.executemany(
648
- 'INSERT INTO queue (job_uid, queue_position, job_snapshot) VALUES (?, ?, ?)',
649
- [(job_uid_from_snapshot(j), pos, dumps(j))
650
- for j, pos in zip(fresh, queue_positions)],
522
+ 'INSERT INTO queue (job_uid, queue_position, job_snapshot, status, run_id, attempt_no, started_at) '
523
+ 'VALUES (?, ?, ?, ?, ?, ?, ?)',
524
+ [
525
+ (
526
+ job_uid_from_snapshot(j),
527
+ pos,
528
+ dumps(j),
529
+ j.get("status", "pending"),
530
+ j.get("run_id"),
531
+ j.get("attempt_no"),
532
+ j.get("started_at"),
533
+ )
534
+ for j, pos in zip(fresh, queue_positions)
535
+ ],
651
536
  )
652
537
  return [job_uid_from_snapshot(j) for j in fresh]
653
538
  except Exception as e:
@@ -698,174 +583,200 @@ class SQLiteStateBackend(AbstractStateBackend):
698
583
  logger.critical(f"Failed to delete successes entries in {self.path.name}: {e}")
699
584
  raise
700
585
 
701
- def seed_successes(self, job_uids: list[str]) -> int:
702
- """把 job_uid 批量写入 successes(meta 空 dict)——存档迁移标记「已处理」。
703
-
704
- 幂等:已存在的 job_uid 被覆盖(meta 重置为空)。
705
- 不变式:successes/failed 全局互斥——已在 failed 的 job_uid 拒绝种子;
706
- 冲突检查与写入收敛进同一 ``BEGIN IMMEDIATE`` 写事务(先取写锁
707
- 再读,详见 _get_conn),冲突时零写入(整体拒绝),不静默清除
708
- 失败档案记录(失败历史须先经 delete_failed 显式清除)。
709
- """
710
- if not job_uids:
711
- return 0
712
- unique_uids = list(dict.fromkeys(job_uids))
713
- try:
714
- with self._get_conn() as conn:
715
- conn.execute('BEGIN IMMEDIATE')
716
- placeholders = ','.join('?' * len(unique_uids))
717
- conflict = sorted(
718
- row[0] for row in conn.execute(
719
- f'SELECT job_uid FROM failed WHERE job_uid IN ({placeholders})',
720
- unique_uids,
586
+ def apply_manual_status(
587
+ self,
588
+ updates: Sequence[tuple[str, str, dict[str, Any], dict[str, Any] | None]],
589
+ ) -> None:
590
+ """批量原子应用人工状态变更 (job_uid, status, snapshot, metadata)。"""
591
+ if not updates:
592
+ return
593
+ with self._get_conn() as conn:
594
+ conn.execute("BEGIN IMMEDIATE")
595
+ for job_uid, status, snapshot, metadata in updates:
596
+ if status == "pending":
597
+ conn.execute("DELETE FROM successes WHERE job_uid = ?", (job_uid,))
598
+ conn.execute("DELETE FROM failed WHERE job_uid = ?", (job_uid,))
599
+ row = conn.execute(
600
+ "SELECT queue_position FROM queue WHERE job_uid = ?", (job_uid,)
601
+ ).fetchone()
602
+ if row is not None:
603
+ conn.execute(
604
+ "UPDATE queue SET job_snapshot = ?, status = 'pending', run_id = NULL, attempt_no = NULL, started_at = NULL WHERE job_uid = ?",
605
+ (dumps(snapshot), job_uid),
606
+ )
607
+ else:
608
+ pos = self._queue_position_range(conn, 1, front=False)[0]
609
+ conn.execute(
610
+ "INSERT INTO queue (job_uid, queue_position, job_snapshot, status) VALUES (?, ?, ?, 'pending')",
611
+ (job_uid, pos, dumps(snapshot)),
612
+ )
613
+ elif status == "succeeded":
614
+ conn.execute("DELETE FROM queue WHERE job_uid = ?", (job_uid,))
615
+ conn.execute("DELETE FROM failed WHERE job_uid = ?", (job_uid,))
616
+ conn.execute(
617
+ "INSERT OR REPLACE INTO successes (job_uid, metadata) VALUES (?, ?)",
618
+ (job_uid, dumps(metadata or {})),
721
619
  )
722
- )
723
- if conflict:
724
- raise ValueError(
725
- f"seed_successes refuses job_uid(s) already in failed: {conflict}; "
726
- f"successes/failed must stay disjoint"
620
+ elif status == "failed":
621
+ conn.execute("DELETE FROM queue WHERE job_uid = ?", (job_uid,))
622
+ conn.execute("DELETE FROM successes WHERE job_uid = ?", (job_uid,))
623
+ payload = snapshot.get("payload") or {}
624
+ conn.execute(
625
+ "INSERT OR REPLACE INTO failed (job_uid, metadata, payload) VALUES (?, ?, ?)",
626
+ (job_uid, dumps(metadata or {}), dumps(payload)),
727
627
  )
728
- cur = conn.executemany(
729
- 'INSERT OR REPLACE INTO successes (job_uid, metadata) VALUES (?, ?)',
730
- [(u, dumps({})) for u in job_uids],
731
- )
732
- return cur.rowcount if cur.rowcount is not None else 0
733
- except Exception as e:
734
- logger.critical(f"Failed to seed successes in {self.path.name}: {e}")
735
- raise
628
+ else:
629
+ raise ValueError(f"Unsupported manual status: {status!r}")
736
630
 
737
- def seed_cursor(self, key: str, value: str) -> None:
738
- """预填一个 cursor(UPSERT,幂等);入口校验与 Memory 腿同契约 fail-loud。"""
631
+ @staticmethod
632
+ def _snapshot_from_metadata(raw: str | None) -> dict[str, Any] | None:
633
+ if not raw:
634
+ return None
635
+ metadata = loads(raw)
636
+ if not isinstance(metadata, dict):
637
+ return None
638
+ snapshot = metadata.get("job_snapshot")
639
+ return snapshot if isinstance(snapshot, dict) else None
640
+
641
+ def load_known_job_snapshot(self, uid: str) -> dict[str, Any] | None:
642
+ """按队列、成功、失败、Attempt 历史的优先级读取完整配置。"""
643
+ with self._get_conn() as conn:
644
+ row = conn.execute(
645
+ "SELECT job_snapshot FROM queue WHERE job_uid = ?", (uid,)
646
+ ).fetchone()
647
+ if row and row[0]:
648
+ snapshot = loads(row[0])
649
+ if isinstance(snapshot, dict):
650
+ return public_queue_snapshot(snapshot)
651
+
652
+ row = conn.execute(
653
+ "SELECT metadata FROM successes WHERE job_uid = ?", (uid,)
654
+ ).fetchone()
655
+ if row:
656
+ snapshot = self._snapshot_from_metadata(row[0])
657
+ if snapshot is not None:
658
+ return snapshot
659
+
660
+ row = conn.execute(
661
+ "SELECT metadata FROM failed WHERE job_uid = ?", (uid,)
662
+ ).fetchone()
663
+ if row:
664
+ snapshot = self._snapshot_from_metadata(row[0])
665
+ if snapshot is not None:
666
+ return snapshot
667
+
668
+ row = conn.execute(
669
+ "SELECT job_snapshot FROM attempts "
670
+ "WHERE job_uid = ? AND job_snapshot IS NOT NULL "
671
+ "ORDER BY attempt_id DESC LIMIT 1",
672
+ (uid,),
673
+ ).fetchone()
674
+ if row and row[0]:
675
+ snapshot = loads(row[0])
676
+ if isinstance(snapshot, dict):
677
+ return snapshot
678
+ return None
679
+
680
+ def load_known_job_snapshots(self) -> dict[str, dict[str, Any]]:
681
+ """读取全部已知 Job 的完整配置,低优先级来源先写入。"""
682
+ known: dict[str, dict[str, Any]] = {}
683
+ with self._get_conn() as conn:
684
+ for uid, raw in conn.execute(
685
+ "SELECT job_uid, job_snapshot FROM attempts "
686
+ "WHERE job_snapshot IS NOT NULL ORDER BY attempt_id ASC"
687
+ ):
688
+ snapshot = loads(raw) if raw else None
689
+ if isinstance(snapshot, dict):
690
+ known[uid] = snapshot
691
+
692
+ for uid, raw in conn.execute("SELECT job_uid, metadata FROM failed"):
693
+ snapshot = self._snapshot_from_metadata(raw)
694
+ if snapshot is not None:
695
+ known[uid] = snapshot
696
+
697
+ for uid, raw in conn.execute("SELECT job_uid, metadata FROM successes"):
698
+ snapshot = self._snapshot_from_metadata(raw)
699
+ if snapshot is not None:
700
+ known[uid] = snapshot
701
+
702
+ for uid, raw in conn.execute("SELECT job_uid, job_snapshot FROM queue"):
703
+ snapshot = loads(raw) if raw else None
704
+ if isinstance(snapshot, dict):
705
+ known[uid] = public_queue_snapshot(snapshot)
706
+ return known
707
+
708
+ def clear_history(self, uid: str, records: set[str]) -> int:
709
+ """从 successes/failed/attempts 清除指定 job_uid 的记录,返回删除条数。"""
710
+ if not self.path.exists():
711
+ return 0
712
+ total = 0
713
+ with self._get_conn() as conn:
714
+ conn.execute("BEGIN IMMEDIATE")
715
+ if "successes" in records:
716
+ cur = conn.execute("DELETE FROM successes WHERE job_uid = ?", (uid,))
717
+ total += cur.rowcount if cur.rowcount is not None else 0
718
+ if "failures" in records:
719
+ cur = conn.execute("DELETE FROM failed WHERE job_uid = ?", (uid,))
720
+ total += cur.rowcount if cur.rowcount is not None else 0
721
+ if "attempts" in records:
722
+ cur = conn.execute("DELETE FROM attempts WHERE job_uid = ?", (uid,))
723
+ total += cur.rowcount if cur.rowcount is not None else 0
724
+ return total
725
+
726
+ def get_cursor(self, key: str) -> str | None:
727
+ """查询单个游标的最新已提交值,不存在返回 None。"""
739
728
  if not isinstance(key, str) or not key:
740
729
  raise TypeError(f"cursor key must be a non-empty str, got {key!r}")
741
- if not isinstance(value, str):
742
- raise TypeError(f"cursor value must be str, got {type(value).__name__}")
743
- try:
744
- with self._get_conn() as conn:
745
- conn.execute(
746
- 'INSERT OR REPLACE INTO cursors (key, value) VALUES (?, ?)',
747
- (key, value),
748
- )
749
- except Exception as e:
750
- logger.critical(f"Failed to seed cursor '{key}' in {self.path.name}: {e}")
751
- raise
752
-
753
- # 尝试轨迹(append-only 旁路观测面)------------------------------------
754
-
755
- def append_attempt(self, record: AttemptRecord) -> int:
756
- """派发即插行:单语句 INSERT,自增 id 由 SQLite 原子分配(无读-改-写窗口)。"""
757
- validate_attempt_dispatch(record)
758
- try:
759
- with self._get_conn() as conn:
760
- cur = conn.execute(
761
- 'INSERT INTO attempts (job_uid, activation_no, attempt_no, '
762
- 'execution_id, run_id, started_at, finished_at, outcome, error_message) '
763
- 'VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
764
- (
765
- record.job_uid, record.activation_no, record.attempt_no,
766
- record.execution_id, record.run_id, record.started_at,
767
- record.finished_at, record.outcome, record.error_message,
768
- ),
769
- )
770
- return int(cur.lastrowid)
771
- except Exception as e:
772
- logger.critical(
773
- f"Failed to append attempt for {record.job_uid} in {self.path.name}: {e}"
774
- )
775
- raise
776
-
777
- def update_attempt(
778
- self,
779
- attempt_id: int,
780
- *,
781
- outcome: str,
782
- finished_at: str,
783
- error_message: str | None = None,
784
- ) -> bool:
785
- """收尾轨迹行:读-判-写在 ``BEGIN IMMEDIATE`` 写事务内串行完成。
730
+ if not self.path.exists():
731
+ return None
732
+ with self._get_conn() as conn:
733
+ row = conn.execute("SELECT value FROM cursors WHERE key = ?", (key,)).fetchone()
734
+ return row[0] if row is not None else None
786
735
 
787
- 目标 id 不存在返回 False(旁路观测面缺行不触发崩溃契约);对已
788
- 收尾行再次收尾抛 ValueError(双重终结是调用方协议缺陷,
789
- fail-loud)。只 UPDATE 收尾三列,身份列永不改写。
790
- """
791
- validate_attempt_finish(outcome, finished_at, error_message)
736
+ def set_cursor(self, key: str, value: str | None) -> None:
737
+ """设置或删除单个游标(None 为删除)。"""
738
+ if not isinstance(key, str) or not key:
739
+ raise TypeError(f"cursor key must be a non-empty str, got {key!r}")
740
+ if value is not None and not isinstance(value, str):
741
+ raise TypeError(f"cursor value must be str or None, got {type(value).__name__}")
792
742
  try:
793
743
  with self._get_conn() as conn:
794
- # 读 running 状态 → 判定 → UPDATE 是读-改-写:持写事务
795
- # 串行化,防并发双重收尾交错漏判(详见 _get_conn)。
796
- conn.execute('BEGIN IMMEDIATE')
797
- row = conn.execute(
798
- 'SELECT outcome FROM attempts WHERE attempt_id = ?', (attempt_id,)
799
- ).fetchone()
800
- if row is None:
801
- return False
802
- if row[0] != "running":
803
- raise ValueError(
804
- f"attempt {attempt_id} already finalized with outcome "
805
- f"{row[0]!r}; double finalization is a protocol violation"
744
+ conn.execute("BEGIN IMMEDIATE")
745
+ if value is None:
746
+ conn.execute("DELETE FROM cursors WHERE key = ?", (key,))
747
+ else:
748
+ conn.execute(
749
+ "INSERT OR REPLACE INTO cursors (key, value) VALUES (?, ?)",
750
+ (key, value),
806
751
  )
807
- conn.execute(
808
- 'UPDATE attempts SET outcome = ?, finished_at = ?, error_message = ? '
809
- 'WHERE attempt_id = ?',
810
- (outcome, finished_at, error_message, attempt_id),
811
- )
812
- return True
813
752
  except Exception as e:
814
- logger.critical(
815
- f"Failed to update attempt {attempt_id} in {self.path.name}: {e}"
816
- )
753
+ logger.critical(f"Failed to set cursor '{key}' in {self.path.name}: {e}")
817
754
  raise
818
755
 
819
- def load_attempts(self, job_uid: str) -> list[AttemptRecord]:
820
- if not self.path.exists():
821
- return []
822
- try:
823
- with self._get_conn() as conn:
824
- rows = conn.execute(
825
- 'SELECT job_uid, activation_no, attempt_no, execution_id, '
826
- 'run_id, started_at, finished_at, outcome, error_message '
827
- 'FROM attempts WHERE job_uid = ? ORDER BY attempt_id ASC',
828
- (job_uid,),
829
- ).fetchall()
830
- return [
831
- AttemptRecord.from_dict(dict(zip(_TABLE_COLUMNS["attempts"][1:], row)))
832
- for row in rows
833
- ]
834
- except (sqlite3.Error, OSError) as e:
835
- raise RuntimeError(
836
- f"Failed to load attempts for {job_uid!r} from {self.path.name}: {e}"
837
- ) from e
756
+ # 尝试轨迹(append-only 旁路观测面)------------------------------------
838
757
 
839
758
  def load_latest_succeeded_finished_at(self, job_uid: str) -> str | None:
840
759
  if not self.path.exists():
841
760
  return None
842
- try:
843
- with self._get_conn() as conn:
844
- row = conn.execute(
845
- "SELECT finished_at FROM attempts "
846
- "WHERE job_uid = ? AND outcome = 'succeeded' "
847
- "ORDER BY attempt_id DESC LIMIT 1",
848
- (job_uid,),
849
- ).fetchone()
850
- if row is None or not isinstance(row[0], str) or not row[0]:
851
- return None
852
- return row[0]
853
- except (sqlite3.Error, OSError) as e:
854
- raise RuntimeError(
855
- f"Failed to load latest succeeded finished_at for {job_uid!r} from {self.path.name}: {e}"
856
- ) from e
761
+ with self._get_conn() as conn:
762
+ row = conn.execute(
763
+ "SELECT settled_at FROM attempts "
764
+ "WHERE job_uid = ? AND outcome = 'success' "
765
+ "ORDER BY attempt_id DESC LIMIT 1",
766
+ (job_uid,),
767
+ ).fetchone()
768
+ if row is None or not isinstance(row[0], str) or not row[0]:
769
+ return None
770
+ return row[0]
857
771
 
858
772
  # 元数据 ---------------------------------------------------------------
859
773
 
860
774
  def get_engine_metadata(self, key: str) -> str | None:
861
775
  if not self.path.exists():
862
776
  return None
863
- try:
864
- with self._get_conn() as conn:
865
- row = conn.execute('SELECT value FROM engine_metadata WHERE key = ?', (key,)).fetchone()
866
- return row[0] if row else None
867
- except (sqlite3.Error, OSError) as e:
868
- raise RuntimeError(f"Failed to read engine_metadata '{key}' from {self.path.name}: {e}") from e
777
+ with self._get_conn() as conn:
778
+ row = conn.execute('SELECT value FROM engine_metadata WHERE key = ?', (key,)).fetchone()
779
+ return row[0] if row else None
869
780
 
870
781
  def set_engine_metadata(self, key: str, value: str) -> None:
871
782
  try:
@@ -878,5 +789,366 @@ class SQLiteStateBackend(AbstractStateBackend):
878
789
  logger.critical(f"Failed to write engine_metadata '{key}' in {self.path.name}: {e}")
879
790
  raise
880
791
 
792
+ # 状态事务与编号 -------------------------------------------------
793
+
794
+ def mark_job_running(
795
+ self, job_uid: str, *, execution_id: str, run_id: str, started_at: str
796
+ ) -> int:
797
+ if not isinstance(execution_id, str) or not execution_id:
798
+ raise ValueError("execution_id must be a non-empty str")
799
+ if not isinstance(run_id, str) or not run_id:
800
+ raise ValueError("run_id must be a non-empty str")
801
+ if not execution_id_matches_run(execution_id, run_id):
802
+ raise ValueError(f"execution_id {execution_id!r} does not belong to run {run_id!r}")
803
+ if not isinstance(started_at, str) or not started_at:
804
+ raise ValueError("started_at must be a non-empty str")
805
+ with self._get_conn() as conn:
806
+ conn.execute('BEGIN IMMEDIATE')
807
+ row = conn.execute(
808
+ 'SELECT status, job_snapshot FROM queue WHERE job_uid = ?',
809
+ (job_uid,),
810
+ ).fetchone()
811
+ if row is None:
812
+ raise ValueError(f"Job {job_uid} not found in queue")
813
+ if row[0] == "running":
814
+ raise ValueError(f"Job {job_uid} is already running")
815
+ job_snapshot = loads(row[1])
816
+ if not isinstance(job_snapshot, dict):
817
+ raise ValueError(f"Job {job_uid} has an invalid queue snapshot")
818
+
819
+ seq_row = conn.execute(
820
+ 'SELECT last_attempt_no FROM job_sequences WHERE job_uid = ?',
821
+ (job_uid,),
822
+ ).fetchone()
823
+ next_no = seq_row[0] + 1 if seq_row is not None else 1
824
+
825
+ conn.execute(
826
+ 'INSERT OR REPLACE INTO job_sequences (job_uid, last_attempt_no) VALUES (?, ?)',
827
+ (job_uid, next_no),
828
+ )
829
+ conn.execute(
830
+ 'UPDATE queue SET job_snapshot = ?, status = ?, run_id = ?, '
831
+ 'attempt_no = ?, started_at = ? WHERE job_uid = ?',
832
+ (
833
+ dumps(queue_snapshot_with_execution_id(job_snapshot, execution_id)),
834
+ "running",
835
+ run_id,
836
+ next_no,
837
+ started_at,
838
+ job_uid,
839
+ ),
840
+ )
841
+ return next_no
842
+
843
+ def get_attempt_sequence(self, job_uid: str) -> int:
844
+ if not self.path.exists():
845
+ return 0
846
+ with self._get_conn() as conn:
847
+ row = conn.execute(
848
+ 'SELECT last_attempt_no FROM job_sequences WHERE job_uid = ?',
849
+ (job_uid,),
850
+ ).fetchone()
851
+ return row[0] if row is not None else 0
852
+
853
+ def clear_attempts(self, job_uid: str) -> int:
854
+ if not self.path.exists():
855
+ return 0
856
+ with self._get_conn() as conn:
857
+ conn.execute('BEGIN IMMEDIATE')
858
+ cur = conn.execute('DELETE FROM attempts WHERE job_uid = ?', (job_uid,))
859
+ return cur.rowcount
860
+
861
+ def load_settled_attempts(self, job_uid: str) -> list[dict[str, Any]]:
862
+ if not self.path.exists():
863
+ return []
864
+ with self._get_conn() as conn:
865
+ cursor = conn.execute(
866
+ 'SELECT attempt_id, job_uid, attempt_no, run_id, outcome, started_at, settled_at, '
867
+ 'job_snapshot, files, result, error_message '
868
+ 'FROM attempts WHERE job_uid = ? ORDER BY attempt_no ASC',
869
+ (job_uid,),
870
+ )
871
+ results: list[dict[str, Any]] = []
872
+ for row in cursor:
873
+ results.append({
874
+ "attempt_id": row[0],
875
+ "job_uid": row[1],
876
+ "attempt_no": row[2],
877
+ "run_id": row[3],
878
+ "outcome": row[4],
879
+ "started_at": row[5],
880
+ "settled_at": row[6],
881
+ "job": loads(row[7]) if row[7] else None,
882
+ "files": loads(row[8]) if row[8] else None,
883
+ "result": loads(row[9]) if row[9] else None,
884
+ "error_message": row[10],
885
+ })
886
+ return results
887
+
888
+ def load_queue_jobs(self, *, status: str | None = None) -> list[dict[str, Any]]:
889
+ if not self.path.exists():
890
+ return []
891
+ with self._get_conn() as conn:
892
+ if status is not None:
893
+ cursor = conn.execute(
894
+ 'SELECT job_uid, queue_position, job_snapshot, status, run_id, attempt_no, started_at '
895
+ 'FROM queue WHERE status = ? ORDER BY queue_position ASC',
896
+ (status,),
897
+ )
898
+ else:
899
+ cursor = conn.execute(
900
+ 'SELECT job_uid, queue_position, job_snapshot, status, run_id, attempt_no, started_at '
901
+ 'FROM queue ORDER BY queue_position ASC'
902
+ )
903
+ results: list[dict[str, Any]] = []
904
+ for row in cursor:
905
+ stored_job = loads(row[2])
906
+ if not isinstance(stored_job, dict):
907
+ raise RuntimeError(f"Corrupted queue job_snapshot for {row[0]!r}")
908
+ results.append({
909
+ "job_uid": row[0],
910
+ "queue_position": row[1],
911
+ "job": public_queue_snapshot(stored_job),
912
+ "status": row[3],
913
+ "execution_id": queue_snapshot_execution_id(stored_job),
914
+ "run_id": row[4],
915
+ "attempt_no": row[5],
916
+ "started_at": row[6],
917
+ })
918
+ return results
919
+
920
+ def commit_job_settlement(
921
+ self,
922
+ *,
923
+ job_uid: str,
924
+ outcome: str,
925
+ attempt_no: int,
926
+ execution_id: str,
927
+ run_id: str,
928
+ settled_at: str,
929
+ started_at: str | None = None,
930
+ job_snapshot: dict[str, Any] | None = None,
931
+ files: dict[str, Any] | None = None,
932
+ result: dict[str, Any] | None = None,
933
+ error_message: str | None = None,
934
+ success_metadata: dict[str, Any] | None = None,
935
+ spawned_job_snapshots: Sequence[dict[str, Any]] = (),
936
+ cursor_updates: Mapping[str, str | None] | None = None,
937
+ failure_metadata: dict[str, Any] | None = None,
938
+ payload: dict[str, Any] | None = None,
939
+ requeued_job_snapshot: dict[str, Any] | None = None,
940
+ record_attempt: bool = True,
941
+ ) -> None:
942
+
943
+ if outcome not in ("success", "failure", "retry", "pending"):
944
+ raise ValueError(f"Invalid outcome: {outcome}")
945
+ if not isinstance(attempt_no, int) or isinstance(attempt_no, bool) or attempt_no < 1:
946
+ raise TypeError(f"attempt_no must be int >= 1, got {attempt_no!r}")
947
+ if not isinstance(execution_id, str) or not execution_id:
948
+ raise ValueError(f"execution_id must be non-empty str, got {execution_id!r}")
949
+ if not isinstance(run_id, str) or not run_id:
950
+ raise ValueError(f"run_id must be non-empty str, got {run_id!r}")
951
+ if not execution_id_matches_run(execution_id, run_id):
952
+ raise ValueError(f"execution_id {execution_id!r} does not belong to run {run_id!r}")
953
+ if not isinstance(settled_at, str) or not settled_at:
954
+ raise ValueError(f"settled_at must be non-empty str, got {settled_at!r}")
955
+ if started_at is not None and (not isinstance(started_at, str) or not started_at):
956
+ raise ValueError("started_at must be non-empty str or None")
957
+ if cursor_updates:
958
+ for k, v in cursor_updates.items():
959
+ if not isinstance(k, str) or not k:
960
+ raise ValueError(f"cursor key must be a non-empty str, got {k!r}")
961
+ if v is not None and not isinstance(v, str):
962
+ raise TypeError(f"cursor value must be str or None, got {type(v).__name__}")
963
+ if spawned_job_snapshots:
964
+ validate_queue_replacement(list(spawned_job_snapshots))
965
+
966
+ with self._get_conn() as conn:
967
+ conn.execute('BEGIN IMMEDIATE')
968
+
969
+ running = conn.execute(
970
+ "SELECT status, run_id, attempt_no, job_snapshot "
971
+ "FROM queue WHERE job_uid = ?",
972
+ (job_uid,),
973
+ ).fetchone()
974
+ if running is None:
975
+ raise TaskLiteError(f"Settlement does not match the running execution for {job_uid}")
976
+ stored_job = loads(running[3]) if running[3] else None
977
+ if not isinstance(stored_job, dict):
978
+ raise TaskLiteError(
979
+ f"Settlement does not match the running execution for {job_uid}"
980
+ )
981
+ if (
982
+ running[:3] != ("running", run_id, attempt_no)
983
+ or queue_snapshot_execution_id(stored_job) != execution_id
984
+ ):
985
+ raise TaskLiteError(
986
+ f"Settlement does not match the running execution for {job_uid}"
987
+ )
988
+ if conn.execute(
989
+ "SELECT 1 FROM attempts WHERE job_uid = ? AND attempt_no = ?", (job_uid, attempt_no)
990
+ ).fetchone():
991
+ raise TaskLiteError(f"Execution for {job_uid} attempt {attempt_no} is already settled")
992
+
993
+ if record_attempt:
994
+ attempt_outcome = (
995
+ outcome if outcome in ("success", "failure", "retry") else "failure"
996
+ )
997
+ conn.execute(
998
+ 'INSERT INTO attempts ('
999
+ 'job_uid, attempt_no, run_id, outcome, started_at, settled_at, '
1000
+ 'job_snapshot, files, result, error_message'
1001
+ ') VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
1002
+ (
1003
+ job_uid,
1004
+ attempt_no,
1005
+ run_id,
1006
+ attempt_outcome,
1007
+ started_at,
1008
+ settled_at,
1009
+ dumps(job_snapshot) if job_snapshot is not None else None,
1010
+ dumps(files) if files is not None else None,
1011
+ dumps(result) if result is not None else None,
1012
+ error_message,
1013
+ ),
1014
+ )
1015
+
1016
+ if outcome == "success":
1017
+ conn.execute(
1018
+ 'INSERT OR REPLACE INTO successes (job_uid, metadata) VALUES (?, ?)',
1019
+ (job_uid, dumps(success_metadata or {})),
1020
+ )
1021
+ conn.execute('DELETE FROM failed WHERE job_uid = ?', (job_uid,))
1022
+ conn.execute('DELETE FROM queue WHERE job_uid = ?', (job_uid,))
1023
+
1024
+ if spawned_job_snapshots:
1025
+ queue_positions = self._queue_position_range(conn, len(spawned_job_snapshots), front=True)
1026
+ rows = [
1027
+ (
1028
+ job_uid_from_snapshot(j),
1029
+ pos,
1030
+ dumps(j),
1031
+ "pending",
1032
+ None,
1033
+ None,
1034
+ None,
1035
+ )
1036
+ for j, pos in zip(spawned_job_snapshots, queue_positions)
1037
+ ]
1038
+ cur = conn.executemany(
1039
+ 'INSERT OR IGNORE INTO queue ('
1040
+ 'job_uid, queue_position, job_snapshot, status, run_id, attempt_no, started_at'
1041
+ ') VALUES (?, ?, ?, ?, ?, ?, ?)',
1042
+ rows,
1043
+ )
1044
+ if cur.rowcount is not None and cur.rowcount < len(spawned_job_snapshots):
1045
+ logger.critical(
1046
+ f"commit_job_settlement for {job_uid}: "
1047
+ f"{len(spawned_job_snapshots) - cur.rowcount} spawned job(s) "
1048
+ f"conflicted on disk. Rolling back."
1049
+ )
1050
+ raise TaskLiteError(f"Spawned job conflicts with queue for {job_uid}")
1051
+
1052
+ if cursor_updates:
1053
+ for k, v in cursor_updates.items():
1054
+ if v is None:
1055
+ conn.execute('DELETE FROM cursors WHERE key = ?', (k,))
1056
+ else:
1057
+ conn.execute(
1058
+ 'INSERT OR REPLACE INTO cursors (key, value) VALUES (?, ?)',
1059
+ (k, v),
1060
+ )
1061
+
1062
+ elif outcome == "failure":
1063
+ conn.execute(
1064
+ 'INSERT OR REPLACE INTO failed (job_uid, metadata, payload) VALUES (?, ?, ?)',
1065
+ (job_uid, dumps(failure_metadata or {}), dumps(payload) if payload is not None else None),
1066
+ )
1067
+ conn.execute('DELETE FROM successes WHERE job_uid = ?', (job_uid,))
1068
+ conn.execute('DELETE FROM queue WHERE job_uid = ?', (job_uid,))
1069
+
1070
+ elif outcome == "retry":
1071
+ if requeued_job_snapshot is not None:
1072
+ conn.execute(
1073
+ 'UPDATE queue SET job_snapshot = ?, status = ?, run_id = NULL, '
1074
+ 'attempt_no = NULL, started_at = NULL WHERE job_uid = ?',
1075
+ (
1076
+ dumps(public_queue_snapshot(requeued_job_snapshot)),
1077
+ "pending",
1078
+ job_uid,
1079
+ ),
1080
+ )
1081
+ else:
1082
+ conn.execute(
1083
+ 'UPDATE queue SET job_snapshot = ?, status = ?, run_id = NULL, '
1084
+ 'attempt_no = NULL, started_at = NULL WHERE job_uid = ?',
1085
+ (dumps(public_queue_snapshot(stored_job)), "pending", job_uid),
1086
+ )
1087
+
1088
+ elif outcome == "pending":
1089
+ conn.execute(
1090
+ 'UPDATE queue SET job_snapshot = ?, status = ?, run_id = NULL, '
1091
+ 'attempt_no = NULL, started_at = NULL WHERE job_uid = ?',
1092
+ (dumps(public_queue_snapshot(stored_job)), "pending", job_uid),
1093
+ )
1094
+
1095
+ def record_authorization(
1096
+ self,
1097
+ path: str,
1098
+ target_type: str,
1099
+ *,
1100
+ authorized_at: str | None = None,
1101
+ ) -> None:
1102
+ norm_path = os.path.normpath(os.fspath(path))
1103
+ if target_type not in ("file", "directory"):
1104
+ raise ValueError(f"target_type must be 'file' or 'directory', got {target_type!r}")
1105
+ ts = authorized_at if authorized_at is not None else utc_now_iso()
1106
+ with self._get_conn() as conn:
1107
+ conn.execute(
1108
+ 'INSERT OR REPLACE INTO authorizations (path, target_type, authorized_at) VALUES (?, ?, ?)',
1109
+ (norm_path, target_type, ts),
1110
+ )
1111
+
1112
+ def list_authorizations(self) -> list[dict[str, Any]]:
1113
+ with self._get_conn() as conn:
1114
+ cur = conn.execute(
1115
+ 'SELECT path, target_type, authorized_at FROM authorizations ORDER BY authorized_at ASC, path ASC'
1116
+ )
1117
+ return [
1118
+ {"path": row[0], "target_type": row[1], "authorized_at": row[2]}
1119
+ for row in cur.fetchall()
1120
+ ]
1121
+
1122
+ def revoke_authorization(self, path: str) -> bool:
1123
+ norm_path = os.path.normpath(os.fspath(path))
1124
+ with self._get_conn() as conn:
1125
+ cur = conn.execute('DELETE FROM authorizations WHERE path = ?', (norm_path,))
1126
+ return bool(cur.rowcount and cur.rowcount > 0)
1127
+
1128
+ def is_path_authorized(self, path: str, target_type: str) -> bool:
1129
+ norm_path = os.path.normpath(os.fspath(path))
1130
+ target_p = Path(norm_path)
1131
+ with self._get_conn() as conn:
1132
+ cur = conn.execute(
1133
+ 'SELECT 1 FROM authorizations WHERE path = ? AND target_type = ?',
1134
+ (norm_path, target_type),
1135
+ )
1136
+ if cur.fetchone() is not None:
1137
+ return True
1138
+ cur = conn.execute("SELECT path FROM authorizations WHERE target_type = 'directory'")
1139
+ for row in cur.fetchall():
1140
+ dir_path = Path(row[0])
1141
+ try:
1142
+ if target_p.is_relative_to(dir_path):
1143
+ return True
1144
+ except (ValueError, TypeError):
1145
+ pass
1146
+ return False
1147
+
1148
+ def close(self) -> None:
1149
+ """关闭后端并释放资源(幂等)。"""
1150
+ pass
1151
+
1152
+
1153
+ __all__ = ["SQLiteStateBackend", "TARGET_SCHEMA_VERSION"]
881
1154
 
882
- __all__ = ["SQLiteStateBackend"]