tasklite-engine 1.2.0__tar.gz → 1.2.2__tar.gz

{tasklite_engine-1.2.0 → tasklite_engine-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasklite-engine
-Version: 1.2.0
+Version: 1.2.2
 Summary: A lightweight task orchestration engine with zero external dependencies, process isolation, and ACID persistence
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/CaptainLi321/tasklite
@@ -269,6 +269,7 @@ def fetch_handler(job, ctx):
 
 ```python
 import json
+from pathlib import Path
 from tasklite import TaskLite, Job, RateLimitResource
 
 def agent_worker(job: Job, ctx):
@@ -276,9 +277,10 @@ def agent_worker(job: Job, ctx):
     prompt = job.payload["prompt"]
     result = call_llm(prompt)
     
-    # 声明产物，失败时自动清理
-    out_file = ctx.declare_output(f"./results/{job.job_id}.json", cleanup_on_fail=True)
-    out_file.write_text(json.dumps(result, ensure_ascii=False))
+    # declare_output 返回解析后的绝对路径字符串（str），用 Path 包装后写文件，
+    # 保证写入位置与框架校验/清理位置一致
+    out_path = Path(ctx.declare_output(f"./results/{job.job_id}.json", cleanup_on_fail=True))
+    out_path.write_text(json.dumps(result, ensure_ascii=False))
     return True, {"tokens": result.get("usage", 0)}
 
 pipeline = TaskLite(name="agent_batch", state_dir="./agent_state", max_workers=8)

{tasklite_engine-1.2.0 → tasklite_engine-1.2.2}/README.md

@@ -240,6 +240,7 @@ def fetch_handler(job, ctx):
 
 ```python
 import json
+from pathlib import Path
 from tasklite import TaskLite, Job, RateLimitResource
 
 def agent_worker(job: Job, ctx):
@@ -247,9 +248,10 @@ def agent_worker(job: Job, ctx):
     prompt = job.payload["prompt"]
     result = call_llm(prompt)
     
-    # 声明产物，失败时自动清理
-    out_file = ctx.declare_output(f"./results/{job.job_id}.json", cleanup_on_fail=True)
-    out_file.write_text(json.dumps(result, ensure_ascii=False))
+    # declare_output 返回解析后的绝对路径字符串（str），用 Path 包装后写文件，
+    # 保证写入位置与框架校验/清理位置一致
+    out_path = Path(ctx.declare_output(f"./results/{job.job_id}.json", cleanup_on_fail=True))
+    out_path.write_text(json.dumps(result, ensure_ascii=False))
     return True, {"tokens": result.get("usage", 0)}
 
 pipeline = TaskLite(name="agent_batch", state_dir="./agent_state", max_workers=8)

{tasklite_engine-1.2.0 → tasklite_engine-1.2.2}/tasklite/__init__.py

@@ -4,7 +4,7 @@ A lightweight, battle-hardened task orchestration engine with zero external
 dependencies, process isolation, and ACID persistence.
 """
 
-__version__ = "1.2.0"
+__version__ = "1.2.2"
 
 
 # Public API - Core

{tasklite_engine-1.2.0 → tasklite_engine-1.2.2}/tasklite/backend/base.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from ..taxonomy import (
     ERR_COMMIT_FAILURE_DLQ,
@@ -28,6 +28,29 @@ from ..taxonomy import (
 )
 
 
+def validate_queue_replacement(jobs: Any) -> None:
+    """整表替换集统一形状校验（save_queue / replace_queue_atomic 共用）。
+
+    契约：替换集必须是 job dict 的 list/tuple（与 load_queue 行形态一致）；
+    None（compute 漏写 return 的笔误形态）或非序列、元素非 dict 均属契约
+    违约，fail-loud 抛 TypeError。
+    不变式：双腿必须在任何写变（DELETE / 赋值）之前调用本校验——None 若
+    混过校验，SQLite 腿「DELETE 全表成功 + INSERT 全跳过」会静默清空整条
+    队列且事务正常提交，与 Memory 腿抛 TypeError 且队列原状形成行为分叉。
+    """
+    if not isinstance(jobs, (list, tuple)):
+        raise TypeError(
+            f"queue replacement must be a list of job dicts, "
+            f"got {type(jobs).__name__}"
+        )
+    for i, job in enumerate(jobs):
+        if not isinstance(job, dict):
+            raise TypeError(
+                f"queue replacement item #{i} must be a job dict, "
+                f"got {type(job).__name__}"
+            )
+
+
 
 class AbstractStateBackend(ABC):
     """Abstract interface for pipeline state persistence.
@@ -49,7 +72,38 @@ class AbstractStateBackend(ABC):
     def load_queue(self) -> List[Dict[str, Any]]: ...
 
     @abstractmethod
-    def save_queue(self, jobs: List[Dict[str, Any]]) -> None: ...
+    def save_queue(self, jobs: List[Dict[str, Any]]) -> None:
+        """整表重写队列（测试装配 / replace_queue_atomic 的事务内步骤）。
+
+        红线：这是「无读基准的整表覆盖」——跨进程并发的 enqueue/commit
+        若提交在本方法执行前的任意时刻，其已落盘行会被无条件抹除。进程内
+        任何「先读磁盘真相再决定写什么」的合并保存（崩溃恢复路径）严禁
+        直接调用本方法，必须走 ``replace_queue_atomic`` 把读-改-写收敛进
+        单个写事务。
+
+        替换集经 ``validate_queue_replacement`` 在写变前校验：None / 非序列 /
+        元素非 dict 抛 TypeError，队列保持调用前状态（双腿一致）。
+        """
+
+    @abstractmethod
+    def replace_queue_atomic(
+        self,
+        compute: Callable[[List[Dict[str, Any]]], List[Dict[str, Any]]],
+    ) -> None:
+        """读-改-写收敛的整表替换：磁盘真相读取与写回在单个写事务内完成。
+
+        ``compute`` 在写锁内接收按序排列的磁盘队列快照，返回替换后的完整
+        队列。不变式：并发方（跨进程 enqueue / delta commit）要么先于本
+        事务提交（其行进入磁盘真相、参与合并，绝不丢失），要么排队等本
+        事务提交后再落盘——「读真相 → 计算 → 写回」之间不存在无锁窗口，
+        陈旧快照永远无法覆盖窗口期他进程已应答的新写入。
+
+        ``compute`` 必须是纯计算（锁内执行，不得调用任何后端写方法，否则
+        跨连接写请求会以写锁互斥死等）。单事务原子：``compute`` 抛异常或
+        写失败时整体回滚，磁盘保持调用前状态，异常向外传播。``compute``
+        返回的替换集经 ``validate_queue_replacement`` 在写变前校验（None /
+        非序列 / 元素非 dict 抛 TypeError，双腿一致，磁盘保持原状）。
+        """
 
     @abstractmethod
     def commit_job_success(
@@ -138,6 +192,17 @@ class AbstractStateBackend(ABC):
         返回 True 成功；False 时 on-disk 队列不变，调用方走崩溃契约。
         """
 
+    @abstractmethod
+    def delete_queue_uids(self, uids: List[str]) -> int:
+        """按 uid 定向批量删除队列行（加载期 repair 的差量落盘唯一出口）。
+
+        与 save_queue 的全表重写相对：只 DELETE 指定 uid 的行，其余行原样
+        保留。不变式：删除集在调用前确定，不在删除集内的行（含并发进程
+        刚入队的新行）无论与本事务先后提交都必然存活——陈旧加载快照永远
+        不会覆盖他进程的新写入。单事务原子；失败抛异常（不吞），磁盘保持
+        调用前状态（残留行由下次加载重新判定，天然幂等）。返回实际删除行数。
+        """
+
     @abstractmethod
     def get_meta(self, key: str) -> Optional[str]:
         """读取一条框架级元数据（如 fencing 的 last_run_id）。无则返回 None。"""
@@ -189,6 +254,9 @@ class AbstractStateBackend(ABC):
         用途：媒体/数据资产项目的存档迁移（硬链接 + wall 种子），
         不必裸 SQL INSERT 框架内部表。返回实际写入行数。
         幂等：已存在的 uid 被覆盖（meta 重置为空）。
+        不变式（wall/failed 全局互斥）：已在 failed 的 uid 拒绝种子——
+        冲突整体拒绝（零写入、抛 ValueError），不静默清除 DLQ 记录；
+        持久层与管理 API（OpsConsole.seed_wall）两层同契约。
         """
 
     @abstractmethod

tasklite_engine-1.2.2/tasklite/backend/memory.py

@@ -0,0 +1,333 @@
+"""纯内存状态后端适配器（InMemoryStateBackend）。
+
+实现 AbstractStateBackend 完整契约，提供零文件系统 IO 的纯内存状态存储。
+适用于瞬态管线、单元测试、沙盒执行与 CI 矩阵测试。
+"""
+from __future__ import annotations
+
+import copy
+import logging
+import threading
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from .base import (
+    AbstractStateBackend,
+    classify_error_type,
+    validate_queue_replacement,
+)
+from ..models.state import uid_from_job_dict
+
+logger = logging.getLogger("tasklite")
+
+
+class InMemoryStateBackend(AbstractStateBackend):
+    """纯内存状态后端。提供快照隔离的 delta 事务语义，与 SQLite 后端行为完全对齐。"""
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._wall: Dict[str, Dict[str, Any]] = {}
+        self._failed: Dict[str, Dict[str, Any]] = {}
+        self._cursors: Dict[str, str] = {}
+        self._queue: List[Dict[str, Any]] = []
+        self._meta: Dict[str, str] = {}
+
+    def load_wall(self) -> Dict[str, Dict[str, Any]]:
+        with self._lock:
+            return copy.deepcopy(self._wall)
+
+    def load_failed(self) -> Dict[str, Dict[str, Any]]:
+        with self._lock:
+            return copy.deepcopy(self._failed)
+
+    def load_cursors(self) -> Dict[str, str]:
+        with self._lock:
+            return dict(self._cursors)
+
+    def load_queue(self) -> List[Dict[str, Any]]:
+        with self._lock:
+            return copy.deepcopy(self._queue)
+
+    def _dedup_copy(self, jobs: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """整表替换行的单一出口（save_queue 与 replace_queue_atomic 共用）。
+
+        替换集先经 ``validate_queue_replacement`` 校验（与 SQLite 腿同一出口、
+        同一时机——赋值之前 fail-loud，`_queue` 保持调用前状态）。
+        保存兜底去重：重复 uid 保留首条 + 告警，与 SQLite 腿
+        _rewrite_queue_rows 同语义；条目一律 deepcopy，杜绝外部可变别名
+        穿透快照隔离。
+        """
+        validate_queue_replacement(jobs)
+        seen = set()
+        clean = []
+        for j in jobs:
+            u = uid_from_job_dict(j)
+            if u in seen:
+                logger.warning(f"save_queue: duplicate uid {u} dropped (kept first).")
+                continue
+            seen.add(u)
+            clean.append(copy.deepcopy(j))
+        return clean
+
+    def save_queue(self, jobs: List[Dict[str, Any]]) -> None:
+        with self._lock:
+            self._queue = self._dedup_copy(jobs)
+
+    def replace_queue_atomic(
+        self,
+        compute: Callable[[List[Dict[str, Any]]], List[Dict[str, Any]]],
+    ) -> None:
+        with self._lock:
+            # 锁内读真相 → 纯计算 → 替换：compute 抛异常时 _queue 赋值
+            # 未发生，队列保持调用前状态（对齐 SQLite 腿事务回滚）。
+            self._queue = self._dedup_copy(compute(copy.deepcopy(self._queue)))
+
+    def _build_dlq_meta(self, meta: Optional[dict], prev: Any) -> Dict[str, Any]:
+        """计算 DLQ 行终值（纯函数，不变更任何状态）：_attempt 计数 + error_type + failed_at。
+
+        不变式：``_attempt`` 是写入事件计数而非逻辑失败次数；既有计数损坏
+        （非 dict 记录或非 int 计数）时静默重置为 1 并照常提交，绝不因脏计数
+        抛 TypeError——与 SQLite 后端「损坏行重置计数、写入成功」行为对齐。
+        ``merged`` 已显式携带 ``_attempt`` 时保留调用方值（计数由最先 DLQ
+        该 uid 的路径权威给定）。
+        """
+        merged = copy.deepcopy(meta or {})
+        if "error_type" not in merged:
+            merged["error_type"] = classify_error_type(merged)
+        if "failed_at" not in merged:
+            merged["failed_at"] = datetime.now(timezone.utc).isoformat()
+        if not isinstance(prev, dict):
+            merged["_attempt"] = 1
+            return merged
+        prev_attempt = prev.get("_attempt")
+        if isinstance(prev_attempt, int):
+            merged["_attempt"] = prev_attempt + 1
+        elif "_attempt" not in merged:
+            merged["_attempt"] = 1
+        return merged
+
+    def _write_dlq_entry(self, uid: str, meta: Optional[dict]) -> None:
+        """DLQ 写入单一出口：终值经 _build_dlq_meta 计算后落变。"""
+        self._failed[uid] = self._build_dlq_meta(meta, self._failed.get(uid))
+
+    def commit_job_success(
+        self,
+        uid: str,
+        result_meta: dict,
+        *,
+        spawned_jobs: List[Dict[str, Any]] = (),
+        cursor_updates: Optional[Dict[str, str]] = None,
+    ) -> bool:
+        with self._lock:
+            try:
+                # 校验先行：全部 deepcopy 与冲突判定在任何变更前完成。
+                # 不变式：返回 False / 抛异常 ⇒ wall/queue/failed/cursors 与
+                # 调用前完全一致（对齐 SQLite 事务回滚；store 的 3-strike
+                # 崩溃契约以「后端未变」为前提做重启重建）。
+                wall_meta = copy.deepcopy(result_meta or {})
+                spawned_copy = [copy.deepcopy(j) for j in spawned_jobs]
+                remaining = [j for j in self._queue if uid_from_job_dict(j) != uid]
+                if spawned_copy:
+                    remaining_uids = {uid_from_job_dict(j) for j in remaining}
+                    seen: set = set()
+                    for sj in spawned_copy:
+                        suid = uid_from_job_dict(sj)
+                        # spawned uid 撞上删除 popped 后的队列既有条目，或
+                        # 批内自相重复，均判定内存/磁盘漂移 → False 走崩溃
+                        # 契约，绝不产出重复队列条目（对齐 SQLite
+                        # INSERT OR IGNORE + rowcount 漂移检测）。
+                        if suid in remaining_uids or suid in seen:
+                            logger.critical(
+                                f"commit_job_success for {uid}: spawned job {suid} "
+                                f"conflicts with queue (drift). Returning False."
+                            )
+                            return False
+                        seen.add(suid)
+                cursor_sets: Dict[str, str] = {}
+                cursor_dels: set = set()
+                if cursor_updates:
+                    for k, v in cursor_updates.items():
+                        if v is None:
+                            cursor_dels.add(k)
+                        else:
+                            cursor_sets[k] = str(v)
+                # 校验全部通过，统一落变（落变段不再调用任何可失败操作）
+                self._wall[uid] = wall_meta
+                self._queue = spawned_copy + remaining  # 队首插入 spawned 并保序
+                # 成功 commit 清理 failed 同名残行：与「job 最终状态唯一」
+                # 语义一致，防 wall∩failed 并存污染 _attempt 计数。
+                self._failed.pop(uid, None)
+                self._cursors.update(cursor_sets)
+                for k in cursor_dels:
+                    self._cursors.pop(k, None)
+                return True
+            except Exception as e:
+                logger.critical(f"Failed to commit job success for {uid}: {e}")
+                return False
+
+    def commit_job_failure(self, uid: str, result_meta: dict) -> bool:
+        with self._lock:
+            try:
+                # 校验先行：DLQ 终值计算与队列 uid 提取全部在变更前完成，
+                # 任一步失败 ⇒ failed/queue/wall 整体不变（对齐 SQLite 回滚）。
+                new_meta = self._build_dlq_meta(result_meta, self._failed.get(uid))
+                remaining = [j for j in self._queue if uid_from_job_dict(j) != uid]
+                self._failed[uid] = new_meta
+                self._queue = remaining
+                # 同一事务语义内清理 wall 旧记录：rerun 任务重跑失败时旧成功
+                # 记录作废（最终状态唯一），防 wall∩failed 并存。
+                self._wall.pop(uid, None)
+                return True
+            except Exception as e:
+                logger.critical(f"Failed to commit job failure for {uid}: {e}")
+                return False
+
+    def commit_retry(
+        self,
+        popped_uid: str,
+        requeued_job: Dict[str, Any],
+        *,
+        front: bool = False,
+    ) -> bool:
+        with self._lock:
+            try:
+                requeued_copy = copy.deepcopy(requeued_job)
+                ruid = uid_from_job_dict(requeued_copy)
+                remaining = [j for j in self._queue if uid_from_job_dict(j) != popped_uid]
+                # 对齐 SQLite 普通 INSERT 冲突回滚：requeued uid 撞上删除
+                # popped 后的既有条目 → False 走崩溃契约，绝不产出重复条目；
+                # uid == popped_uid 属同 job 重插，安全放行。
+                if ruid != popped_uid and any(uid_from_job_dict(j) == ruid for j in remaining):
+                    logger.critical(
+                        f"commit_retry for {popped_uid}: requeued uid {ruid} "
+                        f"conflicts with existing queue entry. Returning False."
+                    )
+                    return False
+                if front:
+                    self._queue = [requeued_copy] + remaining
+                else:
+                    self._queue = remaining + [requeued_copy]
+                return True
+            except Exception as e:
+                logger.critical(f"Failed to commit retry for {popped_uid}: {e}")
+                return False
+
+    def commit_bulk_failure(self, uids_metas: List[Tuple[str, dict]]) -> bool:
+        with self._lock:
+            try:
+                # 校验先行：全部 DLQ 行计算在任何变更前完成——任一行失败则
+                # queue/wall/failed 整体不变（对齐 SQLite 事务回滚，杜绝
+                # 「队列已整体删除、DLQ 未落」的半成品失败态）。
+                new_entries: List[Tuple[str, Dict[str, Any]]] = []
+                overlay: Dict[str, Any] = {}
+                for uid, meta in uids_metas:
+                    # 批内同 uid 多次出现时模拟 SQLite 同事务顺序写：
+                    # 后一行读取前一行结果，_attempt 连续递增。
+                    prev = overlay.get(uid, self._failed.get(uid))
+                    entry = self._build_dlq_meta(meta, prev)
+                    overlay[uid] = entry
+                    new_entries.append((uid, entry))
+                fail_uids = {u for u, _ in uids_metas}
+                remaining = [j for j in self._queue if uid_from_job_dict(j) not in fail_uids]
+                for uid, entry in new_entries:
+                    self._failed[uid] = entry
+                    # rerun 任务被级联/死锁批量 DLQ 时 wall 旧成功记录作废
+                    # （最终状态唯一），与 commit_job_failure 对称。
+                    self._wall.pop(uid, None)
+                self._queue = remaining
+                return True
+            except Exception as e:
+                logger.critical(f"Failed to commit bulk failure: {e}")
+                return False
+
+    def append_failed(self, uid: str, payload: Optional[Dict[str, Any]] = None) -> None:
+        with self._lock:
+            self._write_dlq_entry(uid, payload or {})
+
+    def commit_skip(self, uid: str) -> bool:
+        with self._lock:
+            self._queue = [j for j in self._queue if uid_from_job_dict(j) != uid]
+            return True
+
+    def delete_queue_uids(self, uids: List[str]) -> int:
+        """按 uid 定向批量删除队列条目，与 SQLite 腿同语义：不触碰其余条目。"""
+        if not uids:
+            return 0
+        with self._lock:
+            del_set = set(uids)
+            kept = [j for j in self._queue if uid_from_job_dict(j) not in del_set]
+            removed = len(self._queue) - len(kept)
+            self._queue = kept
+            return removed
+
+    def get_meta(self, key: str) -> Optional[str]:
+        with self._lock:
+            return self._meta.get(key)
+
+    def set_meta(self, key: str, value: str) -> None:
+        with self._lock:
+            self._meta[key] = str(value)
+
+    def enqueue_jobs(self, jobs: List[Dict[str, Any]], *, front: bool = False) -> List[str]:
+        if not jobs:
+            return []
+        with self._lock:
+            existing = {uid_from_job_dict(j) for j in self._queue}
+            fresh: List[Dict[str, Any]] = []
+            batch_seen = set()
+            for j in jobs:
+                u = uid_from_job_dict(j)
+                if u in existing or u in batch_seen:
+                    continue
+                batch_seen.add(u)
+                fresh.append(copy.deepcopy(j))
+            if not fresh:
+                return []
+            if front:
+                self._queue[0:0] = fresh
+            else:
+                self._queue.extend(fresh)
+            return [uid_from_job_dict(j) for j in fresh]
+
+    def delete_failed(self, uids: List[str]) -> int:
+        with self._lock:
+            del_set = set(uids)
+            count = 0
+            for u in del_set:
+                if u in self._failed:
+                    del self._failed[u]
+                    count += 1
+            return count
+
+    def delete_wall(self, uids: List[str]) -> int:
+        with self._lock:
+            del_set = set(uids)
+            count = 0
+            for u in del_set:
+                if u in self._wall:
+                    del self._wall[u]
+                    count += 1
+            return count
+
+    def seed_wall(self, uids: List[str]) -> int:
+        """把 uid 批量写入 wall（meta 空 dict）。
+
+        不变式：wall/failed 全局互斥——已在 failed 的 uid 拒绝种子；
+        先查后写（同锁内），冲突整体拒绝、零写入，不静默清除 DLQ 记录。
+        """
+        with self._lock:
+            conflict = sorted({u for u in uids if u in self._failed})
+            if conflict:
+                raise ValueError(
+                    f"seed_wall refuses uid(s) already in failed: {conflict}; "
+                    f"wall/failed must stay disjoint"
+                )
+            count = 0
+            for u in uids:
+                self._wall[u] = {}
+                count += 1
+            return count
+
+    def seed_cursor(self, key: str, value: str) -> None:
+        with self._lock:
+            self._cursors[key] = str(value)

{tasklite_engine-1.2.0 → tasklite_engine-1.2.2}/tasklite/backend/sqlite_backend.py

@@ -6,9 +6,13 @@ import sqlite3
 from contextlib import contextmanager
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Dict, Any, List, Optional, Tuple, Union
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
-from .base import AbstractStateBackend, classify_error_type
+from .base import (
+    AbstractStateBackend,
+    classify_error_type,
+    validate_queue_replacement,
+)
 from ..models.state import uid_from_job_dict
 from ..utils.jsonutil import dumps, loads
 
@@ -237,36 +241,71 @@ class SQLiteStateBackend(AbstractStateBackend):
         except json.JSONDecodeError as e:
             raise RuntimeError(f"Corrupted queue payload in {self.path.name}: {e}") from e
 
-    def save_queue(self, jobs: List[Dict[str, Any]]) -> None:
-        """全量重写队列（bootstrap / 崩溃恢复用，罕见 O(N)）。
+    def _rewrite_queue_rows(self, conn, jobs: List[Dict[str, Any]]) -> None:
+        """queue 表整表重写的单一出口（save_queue 与 replace_queue_atomic 共用）。
+
+        写变前先经 ``validate_queue_replacement`` 校验替换集（None/非法形状
+        fail-loud 抛 TypeError，不触发 DELETE）——否则 None 会让「DELETE
+        全表 + INSERT 全跳」静默清空队列且事务正常提交。
 
         保存兜底去重：传入重复 uid 时保留首条 + 告警（而非 REPLACE 静默
         覆盖为最后一条）——与加载期去重策略一致，杜绝 `_queue_uids` set 与
-        queue list 的漂移。
+        queue list 的漂移。调用方必须已持写事务（显式或隐式）。
+        """
+        validate_queue_replacement(jobs)
+        conn.execute('DELETE FROM queue')
+        if jobs:
+            seen: set = set()
+            rows = []
+            for i, j in enumerate(jobs):
+                u = uid_from_job_dict(j)
+                if u in seen:
+                    logger.warning(
+                        f"save_queue: duplicate uid {u} dropped (kept first)."
+                    )
+                    continue
+                seen.add(u)
+                rows.append((u, len(rows), dumps(j)))
+            conn.executemany(
+                'INSERT OR REPLACE INTO queue (uid, seq, job_data) VALUES (?, ?, ?)',
+                rows,
+            )
+
+    def save_queue(self, jobs: List[Dict[str, Any]]) -> None:
+        """全量重写队列（测试装配 / replace_queue_atomic 事务内步骤，罕见 O(N)）。
+
+        红线：无读基准的整表覆盖——崩溃恢复路径的「合并保存」严禁直接
+        调用本方法（读-改-写窗口会抹除窗口期他进程已应答的入队），
+        必须经 replace_queue_atomic 收敛进单个写事务。
         """
         try:
             with self._get_conn() as conn:
-                conn.execute('DELETE FROM queue')
-                if jobs:
-                    seen: set = set()
-                    rows = []
-                    for i, j in enumerate(jobs):
-                        u = uid_from_job_dict(j)
-                        if u in seen:
-                            logger.warning(
-                                f"save_queue: duplicate uid {u} dropped (kept first)."
-                            )
-                            continue
-                        seen.add(u)
-                        rows.append((u, len(rows), dumps(j)))
-                    conn.executemany(
-                        'INSERT OR REPLACE INTO queue (uid, seq, job_data) VALUES (?, ?, ?)',
-                        rows,
-                    )
+                self._rewrite_queue_rows(conn, jobs)
         except Exception as e:
             logger.critical(f"Failed to save queue to {self.path.name}: {e}")
             raise
 
+    def replace_queue_atomic(
+        self,
+        compute: Callable[[List[Dict[str, Any]]], List[Dict[str, Any]]],
+    ) -> None:
+        try:
+            with self._get_conn() as conn:
+                # 读-改-写事务纪律：先取写锁再读磁盘真相，compute 与写回
+                # 同事务——并发 enqueue 要么先于本事务提交（进入磁盘真相、
+                # 参与合并），要么等本事务提交后再落盘，绝无中间态覆盖。
+                conn.execute('BEGIN IMMEDIATE')
+                disk_q = [
+                    loads(row[0])
+                    for row in conn.execute(
+                        'SELECT job_data FROM queue ORDER BY seq ASC'
+                    )
+                ]
+                self._rewrite_queue_rows(conn, compute(disk_q))
+        except Exception as e:
+            logger.critical(f"Failed to replace queue atomically in {self.path.name}: {e}")
+            raise
+
     def enqueue_jobs(self, jobs: List[Dict[str, Any]], *, front: bool = False) -> List[str]:
         """批量增量入队：单事务原子插入，跳过重复 uid。
 
@@ -459,6 +498,20 @@ class SQLiteStateBackend(AbstractStateBackend):
             return False
         return True
 
+    def delete_queue_uids(self, uids: List[str]) -> int:
+        """按 uid 定向批量删除队列行（repair 差量落盘），不触碰其余行。"""
+        if not uids:
+            return 0
+        try:
+            with self._get_conn() as conn:
+                cur = conn.executemany(
+                    'DELETE FROM queue WHERE uid = ?', [(u,) for u in uids]
+                )
+                return cur.rowcount if cur.rowcount is not None else 0
+        except Exception as e:
+            logger.critical(f"Failed to delete queue uids in {self.path.name}: {e}")
+            raise
+
     def commit_retry(self, popped_uid: str, requeued_job: Dict[str, Any], *, front: bool = False) -> bool:
         """原子 delta：删除 popped_uid + 按 front 插入 requeued_job。不写 wall/DLQ。
 
@@ -541,11 +594,28 @@ class SQLiteStateBackend(AbstractStateBackend):
         """把 uid 批量写入 wall（meta 空 dict）——存档迁移标记「已处理」。
 
         幂等：已存在的 uid 被覆盖（meta 重置为空）。
+        不变式：wall/failed 全局互斥——已在 failed_dlq 的 uid 拒绝种子；
+        冲突检查与写入收敛进同一 ``BEGIN IMMEDIATE`` 写事务（先取写锁再读，
+        详见 _get_conn），冲突时零写入（整体拒绝），不静默清除 DLQ 记录。
         """
         if not uids:
             return 0
+        unique_uids = list(dict.fromkeys(uids))
         try:
             with self._get_conn() as conn:
+                conn.execute('BEGIN IMMEDIATE')
+                placeholders = ','.join('?' * len(unique_uids))
+                conflict = sorted(
+                    row[0] for row in conn.execute(
+                        f'SELECT uid FROM failed_dlq WHERE uid IN ({placeholders})',
+                        unique_uids,
+                    )
+                )
+                if conflict:
+                    raise ValueError(
+                        f"seed_wall refuses uid(s) already in failed: {conflict}; "
+                        f"wall/failed must stay disjoint"
+                    )
                 cur = conn.executemany(
                     'INSERT OR REPLACE INTO wall (uid, payload) VALUES (?, ?)',
                     [(u, dumps({})) for u in uids],