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
tasklite/backend/base.py CHANGED
@@ -1,22 +1,49 @@
1
- """v2 持久层抽象契约:AbstractStateBackend 与共享入口门卫。
2
-
3
- backend 只被单线程父进程调用;子进程 worker 不触碰持久层。契约按
4
- delta 语义组织:队列行的「弹出」从不单独落盘——被弹出的 uid 保留在
5
- 磁盘队列中,直到 commit_job_success / commit_job_failure /
6
- commit_retry / commit_skip 的事务内才删除(at-least-once 崩溃契约)。
7
-
8
- 失败档案(failed)术语:按 uid 唯一终态,successes/failed 全局互斥——
9
- 成功 commit 删 failed 同名行、失败 commit 删 successes 行,「最终状态唯一」
10
- 由此保证;失败历史与执行时间线由 attempts 旁路轨迹承接,本表不注入
11
- 计数字段。attempts 为 append-only 旁路观测面:不参与 successes/failed 的
12
- 互斥与 REPLACE 语义。
1
+ """当前持久层内部 Interface 与共享入口门卫。
2
+
3
+ 队列状态、追加式 Attempt、终态档案、派生 Job 和游标由一次结算原子提交。
4
+ successes 与 failed 按 UID 互斥;Attempt 仅作执行轨迹,编号独立于可清理历史。
13
5
  """
14
6
  from __future__ import annotations
15
7
 
8
+ import copy
16
9
  from abc import ABC, abstractmethod
17
10
  from typing import Any, Callable, Mapping, Sequence
18
11
 
19
- from ..models.attempt import ATTEMPT_OUTCOMES, AttemptRecord
12
+
13
+ QUEUE_EXECUTION_ID_KEY = "__tasklite_execution_id__"
14
+
15
+
16
+ def queue_snapshot_with_execution_id(
17
+ job_snapshot: Mapping[str, Any], execution_id: str
18
+ ) -> dict[str, Any]:
19
+ """返回带内部执行代号的队列快照。"""
20
+ stored = dict(job_snapshot)
21
+ stored[QUEUE_EXECUTION_ID_KEY] = execution_id
22
+ return stored
23
+
24
+
25
+ def queue_snapshot_execution_id(job_snapshot: Mapping[str, Any]) -> str | None:
26
+ """读取队列快照内部执行代号;缺失或非法值返回 None。"""
27
+ value = job_snapshot.get(QUEUE_EXECUTION_ID_KEY)
28
+ return value if isinstance(value, str) and value else None
29
+
30
+
31
+ def public_queue_snapshot(job_snapshot: Mapping[str, Any]) -> dict[str, Any]:
32
+ """返回剥离内部执行代号的业务快照副本。"""
33
+ public = copy.deepcopy(dict(job_snapshot))
34
+ public.pop(QUEUE_EXECUTION_ID_KEY, None)
35
+ return public
36
+
37
+
38
+ def execution_id_matches_run(execution_id: str, run_id: str) -> bool:
39
+ """执行代号必须由本 Run 与正派发序号组成。"""
40
+ prefix, separator, dispatch_no = execution_id.rpartition(".")
41
+ return (
42
+ bool(separator)
43
+ and prefix == run_id
44
+ and dispatch_no.isdigit()
45
+ and int(dispatch_no) > 0
46
+ )
20
47
 
21
48
 
22
49
  def validate_queue_replacement(job_snapshots: Any) -> None:
@@ -42,76 +69,15 @@ def validate_queue_replacement(job_snapshots: Any) -> None:
42
69
  )
43
70
 
44
71
 
45
- def validate_attempt_dispatch(record: Any) -> None:
46
- """尝试轨迹插入门卫:只接受「派发即插行」形态。
47
-
48
- 契约(attempts append-only 协议的插入侧):AttemptRecord 且
49
- outcome="running"、finished_at 与 error_message 均为 None——收尾字段由
50
- ``update_attempt`` 唯一写入;插入侧出现收尾字段说明调用方绕过了
51
- 派发点协议(终态行伪装成派发行,时间线出现空洞),fail-loud 拒绝。
52
- """
53
- if not isinstance(record, AttemptRecord):
54
- raise TypeError(
55
- f"attempt record must be an AttemptRecord, "
56
- f"got {type(record).__name__} ({record!r})"
57
- )
58
- if record.outcome != "running" or record.finished_at is not None or record.error_message is not None:
59
- raise ValueError(
60
- "dispatch append must be a fresh running row "
61
- "(outcome='running', finished_at=None, error_message=None), got "
62
- f"outcome={record.outcome!r} finished_at={record.finished_at!r} "
63
- f"error_message={record.error_message!r}"
64
- )
65
-
66
-
67
- def validate_attempt_finish(outcome: Any, finished_at: Any, error_message: Any) -> None:
68
- """尝试轨迹收尾门卫:outcome 属终态词汇、收尾时刻与错误形态合法。
72
+ class AbstractStateBackend(ABC):
73
+ """SQLite 与 Memory 共用的内部持久化 Interface。
69
74
 
70
- running 是插入侧专属形态——收尾接口把 running 写回会把已派发行
71
- 伪装成未派发,追溯链的起止时间语义被破坏,入口拒绝(与
72
- ``AttemptRecord`` 的词汇表校验同源、同口径)。
75
+ 当前执行只经 commit_job_settlement 追加结算;执行前失败、批量失败与
76
+ 候选移除各自原子提交。写入故障原样传播,调用方提交成功后才发布内存。
77
+ 整表读改写必须使用 replace_queue_atomic;历史清理不触碰编号进度。
73
78
  """
74
- if outcome == "running" or outcome not in ATTEMPT_OUTCOMES:
75
- raise ValueError(
76
- f"attempt finish outcome must be one of "
77
- f"{'/'.join(repr(v) for v in ATTEMPT_OUTCOMES if v != 'running')}, "
78
- f"got {outcome!r}"
79
- )
80
- if not isinstance(finished_at, str):
81
- raise TypeError(
82
- f"finished_at must be a str, got {type(finished_at).__name__} "
83
- f"({finished_at!r})"
84
- )
85
- if not finished_at:
86
- raise ValueError("finished_at must be a non-empty str")
87
- if error_message is not None and not isinstance(error_message, str):
88
- raise TypeError(
89
- f"error_message must be a str or None, got {type(error_message).__name__} ({error_message!r})"
90
- )
91
- if error_message == "":
92
- raise ValueError("error_message must be a non-empty str or None")
93
-
94
79
 
95
- class AbstractStateBackend(ABC):
96
- """管线状态持久化抽象契约(SQLite / Memory 双腿共同口径)。
97
-
98
- 语义分组:
99
- - 全量加载(load_successes / load_failed / load_failure_payloads /
100
- load_cursors / load_queue):仅启动装配与测试装配使用;
101
- - 整表重写(save_queue / replace_queue_atomic):读-改-写必须经
102
- ``replace_queue_atomic`` 收敛进单个写事务;
103
- - delta 提交(commit_job_success / commit_job_failure /
104
- commit_retry / commit_job_failures / commit_skip):逐 job 单事务
105
- 碎片化,禁止多 job 混合长事务;返回 False 表示持久化失败且后端
106
- 保持调用前状态,调用方不得推进内存镜像并走崩溃契约;
107
- - 增量入队(enqueue_jobs):不做全量覆盖,与运行中 delta 提交并发
108
- 安全(写入侧不覆盖);
109
- - 定向删除与种子(delete_queue_uids / delete_failed / delete_successes /
110
- seed_successes / seed_cursor):加载期 repair 差量落盘与运维接缝;
111
- - 尝试轨迹(append_attempt / update_attempt / load_attempts):
112
- append-only 旁路观测面;
113
- - 元数据(get_engine_metadata / set_engine_metadata):框架级键值(fencing 的 last_run_id 等)。
114
- """
80
+ _exec_lock: Any = None
115
81
 
116
82
  # 全量加载 -------------------------------------------------------
117
83
 
@@ -135,6 +101,22 @@ class AbstractStateBackend(ABC):
135
101
  def load_queue(self) -> list[dict[str, Any]]:
136
102
  """按 queue_position 升序加载磁盘队列真相。"""
137
103
 
104
+ @abstractmethod
105
+ def load_known_job_snapshot(self, uid: str) -> dict[str, Any] | None:
106
+ """读取单个已知 Job 的完整配置快照。
107
+
108
+ 优先级固定为队列(含 running)、successes、failed、Attempt 历史。
109
+ 找不到时返回 None;读取或解码故障必须原样传播。
110
+ """
111
+
112
+ @abstractmethod
113
+ def load_known_job_snapshots(self) -> dict[str, dict[str, Any]]:
114
+ """读取全部已知 Job 的完整配置快照映射。
115
+
116
+ 同一 UID 按队列(含 running)、successes、failed、Attempt 历史的
117
+ 优先级选取。读取或解码故障必须原样传播。
118
+ """
119
+
138
120
  # 整表重写 -------------------------------------------------------
139
121
 
140
122
  @abstractmethod
@@ -173,34 +155,6 @@ class AbstractStateBackend(ABC):
173
155
 
174
156
  # delta 提交 -----------------------------------------------------
175
157
 
176
- @abstractmethod
177
- def commit_job_success(
178
- self,
179
- job_uid: str,
180
- result_metadata: dict,
181
- *,
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]] = (),
186
- cursor_updates: Mapping[str, str | None] | None = None,
187
- ) -> bool:
188
- """原子持久化一个成功 job 的 delta,并在同一事务中校验与终结对应 attempts 行。
189
-
190
- 单事务效果:
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;
195
- - queue:DELETE 被弹出的 uid;
196
- - queue:spawned_job_snapshots 队头插入(保序);
197
- - failed:DELETE 同名残行(成功终态唯一,防 successes∩failed 并存);
198
- - cursors:合并 cursor_updates(None 值表示删除游标)。
199
-
200
- 返回 True 成功;返回 False 表示 attempts 校验失败或任一步持久化失败且
201
- 后端保持调用前状态(被弹出的 uid 仍在磁盘队列,attempts 仍保持原状),
202
- 调用方不得更新内存 successes/cursor 状态,并自行决定是否重入队(崩溃契约)。
203
- """
204
158
 
205
159
  @abstractmethod
206
160
  def commit_job_failure(
@@ -216,53 +170,29 @@ class AbstractStateBackend(ABC):
216
170
  记录作废(最终状态唯一),否则磁盘 successes∩failed 并存破坏互斥。
217
171
  ``payload`` 是原始业务输入快照(补跑自足,无需外部反查);
218
172
  None 表示本路径无可存快照,保留既有快照不覆盖。
219
- 返回语义与 ``commit_job_success`` 一致:False ⇒ 后端未变、崩溃契约。
173
+ 成功返回 True;写入故障原样传播,失败时后端保持调用前状态。
220
174
  """
221
175
 
222
- @abstractmethod
223
- def commit_retry(
224
- self,
225
- popped_job_uid: str,
226
- requeued_job_snapshot: dict[str, Any],
227
- *,
228
- front: bool = False,
229
- ) -> bool:
230
- """原子持久化一次重入队 delta:DELETE popped_job_uid + 按 front 插入 requeued_job_snapshot。
231
-
232
- 不写 successes/failed。同 uid 重试是 DELETE+INSERT(一次执行没有独立
233
- 持久身份,身份仍是 uid)。重插不得静默丢弃:requeued uid 撞上删除
234
- popped 后的既有行冲突时返回 False 走崩溃契约,绝不产出重复队列
235
- 条目却报成功。
236
- """
237
176
 
238
177
  @abstractmethod
239
- def commit_job_failures(self, job_uids_metadata: list[tuple[str, dict]]) -> bool:
178
+ def commit_job_failures(self, job_uids_metadata: list[tuple[str, dict]]) -> None:
240
179
  """原子批量写失败档案(死锁/级联场景)的 delta。
241
180
 
242
181
  单事务效果:failed INSERT/REPLACE 每个 uid → metadata;
243
182
  queue 按 uid 精准 DELETE(剩余条目保持原顺序);
244
183
  successes 批量 DELETE 同名行(与 commit_job_failure 对称的最终状态唯一)。
245
- 任一行失败 ⇒ 整体回滚、返回 False,绝不留下「队列已删、档案未落」
184
+ 任一行失败 ⇒ 整体回滚并原样抛出异常,绝不留下「队列已删、档案未落」
246
185
  的半成品失败态。
247
186
  """
248
187
 
249
188
  @abstractmethod
250
- def commit_skip(self, job_uid: str) -> bool:
251
- """delta 删除队列中已终态(重复)的 uid。
189
+ def commit_skip(self, job_uid: str) -> None:
190
+ """移除 Trigger False 或已终态重复候选的队列行。
252
191
 
253
- 去重命中(uid 已在 successes/failed)时调用——磁盘队列中该 uid 是残留
254
- 条目,直接删除以同步内存/磁盘(内存 = 磁盘 − in-flight)。
255
- 不写 successes/failed(重复条目不改变任何状态,只是清理)。
256
- 返回 True 成功;False 时 on-disk 队列不变,调用方走崩溃契约。
192
+ 不写 successes/failed,不生成 Attempt。
193
+ 成功无返回值;失败时队列不变,原始异常继续传播。
257
194
  """
258
195
 
259
- @abstractmethod
260
- def append_failed(self, job_uid: str, metadata: dict[str, Any] | None = None) -> None:
261
- """绕过队列直接写一条失败档案记录(带外登记面)。
262
-
263
- 按 uid REPLACE(幂等);不触碰 queue/successes/cursors。持久化失败
264
- 抛异常(不吞)。
265
- """
266
196
 
267
197
  # 增量入队 -------------------------------------------------------
268
198
 
@@ -313,79 +243,121 @@ class AbstractStateBackend(ABC):
313
243
  """
314
244
 
315
245
  @abstractmethod
316
- def seed_successes(self, job_uids: list[str]) -> int:
317
- """把 uid 批量写入 successes(meta 为空 dict)——存档迁移标记「已处理」。
246
+ def apply_manual_status(
247
+ self,
248
+ updates: Sequence[tuple[str, str, dict[str, Any], dict[str, Any] | None]],
249
+ ) -> None:
250
+ """批量原子应用人工状态变更 (job_uid, status, snapshot, metadata)。"""
318
251
 
319
- 幂等:已存在的 uid 被覆盖(meta 重置为空)。返回实际写入行数。
320
- 不变式(successes/failed 全局互斥):已在 failed 的 uid 拒绝种子——
321
- 冲突整体拒绝(零写入、抛 ValueError),不静默清除失败档案记录;
322
- 持久层与管理 API(OpsConsole.seed_successes)两层同契约。
323
- """
252
+ @abstractmethod
253
+ def clear_history(self, uid: str, records: set[str]) -> int:
254
+ """从 successes/failed/attempts 清除指定 job_uid 的记录,返回删除条数。"""
324
255
 
325
256
  @abstractmethod
326
- def seed_cursor(self, key: str, value: str) -> None:
327
- """预填一个 cursor(UPSERT 语义,幂等)——存档迁移/进度书签恢复。
257
+ def get_cursor(self, key: str) -> str | None:
258
+ """查询单个游标的最新已提交值,不存在返回 None。"""
328
259
 
329
- 入口校验 fail-loud:key 非空 str、value 必须 str——静默 str() 强转
330
- 会让同一非法入参在 sqlite 腿抛异常、memory 腿写数字串(跨后端行为
331
- 分歧),且与内存镜像值型漂移。discovery 的已见判定走 successes/failed,
332
- 「已见预填」请用 ``seed_successes``;本方法服务通用业务 cursor。
333
- """
260
+ @abstractmethod
261
+ def set_cursor(self, key: str, value: str | None) -> None:
262
+ """设置或删除单个游标(None 为删除)。"""
334
263
 
335
264
  # 尝试轨迹(append-only 旁路观测面)--------------------------------
336
265
 
266
+
337
267
  @abstractmethod
338
- def append_attempt(self, record: AttemptRecord) -> int:
339
- """派发时追加一条 running 尝试轨迹行,返回自增轨迹 id。
268
+ def load_latest_succeeded_finished_at(self, job_uid: str) -> str | None:
269
+ """读取指定 Job 最新一条 success Attempt 的 settled_at;无则返回 None。"""
340
270
 
341
- 协议:仅在派发点调用,record 必须是 outcome="running"、无收尾
342
- 时刻/错误的派发即插行(``validate_attempt_dispatch`` 门卫),随行
343
- 落盘 started_at / execution_id / run_id。attempts 不参与 successes/failed
344
- 的互斥与 REPLACE 语义,本方法不触碰 queue/successes/failed/cursors;
345
- 持久化失败抛异常(fail-loud,不吞)。
346
- """
271
+ # 元数据 ---------------------------------------------------------
272
+
273
+ @abstractmethod
274
+ def get_engine_metadata(self, key: str) -> str | None:
275
+ """读取一条框架级元数据(如 fencing 的 last_run_id)。无则返回 None。"""
276
+
277
+ @abstractmethod
278
+ def set_engine_metadata(self, key: str, value: str) -> None:
279
+ """写入一条框架级元数据(UPSERT 语义)。失败抛异常(不吞)。"""
280
+
281
+ # 状态事务与编号 -------------------------------------------------
282
+
283
+ @abstractmethod
284
+ def mark_job_running(
285
+ self, job_uid: str, *, execution_id: str, run_id: str, started_at: str
286
+ ) -> int:
287
+ """原子将 pending job 转为 running,持久化完整执行身份并递增 attempt_no。"""
347
288
 
348
289
  @abstractmethod
349
- def update_attempt(
290
+ def commit_job_settlement(
350
291
  self,
351
- attempt_id: int,
352
292
  *,
293
+ job_uid: str,
353
294
  outcome: str,
354
- finished_at: str,
295
+ attempt_no: int,
296
+ execution_id: str,
297
+ run_id: str,
298
+ settled_at: str,
299
+ started_at: str | None = None,
300
+ job_snapshot: dict[str, Any] | None = None,
301
+ files: dict[str, Any] | None = None,
302
+ result: dict[str, Any] | None = None,
355
303
  error_message: str | None = None,
356
- ) -> bool:
357
- """终态/重试时收尾轨迹行:写 finished_at / outcome / error_message。
358
-
359
- 收尾词汇与 ``AttemptRecord`` 一致(succeeded / failed / requeued /
360
- skipped),running 是插入侧专属形态(``validate_attempt_finish``
361
- 门卫)。每个轨迹行只允许一次收尾:目标 id 不存在返回 False
362
- (旁路观测面缺行不触发崩溃契约);对已收尾行再次收尾抛
363
- ValueError(引擎侧双重终结属于协议缺陷,fail-loud)。持久化故障
364
- 抛异常。除本方法的收尾三列外无任何 UPDATE 路径——历史行只增不改。
304
+ success_metadata: dict[str, Any] | None = None,
305
+ spawned_job_snapshots: Sequence[dict[str, Any]] = (),
306
+ cursor_updates: Mapping[str, str | None] | None = None,
307
+ failure_metadata: dict[str, Any] | None = None,
308
+ payload: dict[str, Any] | None = None,
309
+ requeued_job_snapshot: dict[str, Any] | None = None,
310
+ record_attempt: bool = True,
311
+ ) -> None:
312
+ """原子执行结算:校验完整执行身份后写入 Attempt、Job 去向、档案与派生数据。
313
+
314
+ 成功无返回值;执行身份与 running 不匹配或已结算时抛 TaskLiteError。
315
+ 写入故障原样传播,失败时后端不变。
365
316
  """
366
317
 
367
318
  @abstractmethod
368
- def load_attempts(self, job_uid: str) -> list[AttemptRecord]:
369
- """按 job_uid 读取全部尝试轨迹(按轨迹 id 升序);无轨迹返回空列表。"""
319
+ def get_attempt_sequence(self, job_uid: str) -> int:
320
+ """读取指定 job_uid 的最新 attempt_no 编号进度(未派发过返回 0)。"""
370
321
 
371
322
  @abstractmethod
372
- def load_latest_succeeded_finished_at(self, job_uid: str) -> str | None:
373
- """窄查询指定 job_uid 最新一条 outcome == 'succeeded' 轨迹行的 finished_at;无则返回 None。"""
323
+ def load_settled_attempts(self, job_uid: str) -> list[dict[str, Any]]:
324
+ """按 attempt_no 升序读取指定 job_uid 的全部已结算 Attempt 记录。"""
374
325
 
375
- # 元数据 ---------------------------------------------------------
326
+ @abstractmethod
327
+ def clear_attempts(self, job_uid: str) -> int:
328
+ """删除指定 job_uid 的 Attempt 历史(不影响 job_sequences 编号进度)。"""
376
329
 
377
330
  @abstractmethod
378
- def get_engine_metadata(self, key: str) -> str | None:
379
- """读取一条框架级元数据(如 fencing 的 last_run_id)。无则返回 None。"""
331
+ def load_queue_jobs(self, *, status: str | None = None) -> list[dict[str, Any]]:
332
+ """按 queue_position 升序加载队列行的完整信息,可选按 status 过滤。"""
380
333
 
381
334
  @abstractmethod
382
- def set_engine_metadata(self, key: str, value: str) -> None:
383
- """写入一条框架级元数据(UPSERT 语义)。失败抛异常(不吞)。"""
335
+ def record_authorization(
336
+ self,
337
+ path: str,
338
+ target_type: str,
339
+ *,
340
+ authorized_at: str | None = None,
341
+ ) -> None:
342
+ """持久化记录一条文件系统路径授权(target_type 为 'file' 或 'directory')。"""
343
+
344
+ @abstractmethod
345
+ def list_authorizations(self) -> list[dict[str, Any]]:
346
+ """查询全部已持久化的授权记录。"""
347
+
348
+ @abstractmethod
349
+ def revoke_authorization(self, path: str) -> bool:
350
+ """按规范绝对路径精确撤销授权,存在并删除返回 True,不存在返回 False。"""
351
+
352
+ @abstractmethod
353
+ def is_path_authorized(self, path: str, target_type: str) -> bool:
354
+ """按实际目标类型检查规范绝对路径授权;文件精确匹配,目录覆盖整树。"""
355
+
356
+ def close(self) -> None:
357
+ """关闭后端并释放资源(幂等)。"""
384
358
 
385
359
 
386
360
  __all__ = [
387
361
  "AbstractStateBackend",
388
- "validate_attempt_dispatch",
389
- "validate_attempt_finish",
390
362
  "validate_queue_replacement",
391
363
  ]