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

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

@@ -1,8 +1,21 @@
 Metadata-Version: 2.4
 Name: tasklite-engine
-Version: 1.0.0
+Version: 1.2.0
 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
+Project-URL: Repository, https://github.com/CaptainLi321/tasklite
+Keywords: task-queue,task-orchestration,background-jobs,subprocess,process-isolation,acid,workflow
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -125,8 +138,15 @@ flowchart TD
 - `ctx.declare_output()` 声明产出文件，内置路径遍历防御 (`../` 拒绝)；
 - 任务成功时校验物理产出完整性，任务失败时自动清理半成品文件，避免残留。
 
+### 7. 🌐 组合式 HTTP 网络工具与快照守卫 (HTTP Wrappers)
+- 开放 Callable 设计，支持原生 `urllib`、`requests`、`httpx` 或平台自定义签名 SDK；
+- `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线退避，收敛异常三分类；
+- `SQLiteSnapshotStore` 提供单射键原始响应快照持久化，支持全离线幂等重放；
+- 内置标准 Netscape `cookies.txt` 解析工具。
+
 ---
 
+
 ## 🚀 快速上手 (Quickstart)
 
 ### 安装
@@ -273,8 +293,31 @@ pipeline.enqueue([
 pipeline.run()
 ```
 
+### Recipe 5: 官方 HTTP 守卫与原始响应快照重放 (HTTP Wrappers)
+
+```python
+from tasklite import TaskLite, RateLimitResource
+from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard, fetch_urllib
+
+pipeline = TaskLite("crawler", state_dir="./states")
+pipeline.add_resource(RateLimitResource("api", interval_seconds=1.0))
+
+# 原始 HTTP 响应持久化快照（独立 snapshots.db，支持全离线重放与反爬保护）
+snapshot_store = SQLiteSnapshotStore("./snapshots.db")
+cached_fetch = snapshot_store.cached(fetch_urllib)
+
+def crawler_handler(job, ctx):
+    # 429 时自动挂起 api 资源、5xx 瞬态重试、4xx 直接 DLQ
+    with http_guard(ctx=ctx, resource="api", default_suspend_ttl=60.0):
+        resp = cached_fetch(job.payload["url"])
+        return resp.json()
+
+pipeline.register_handler("fetch", crawler_handler, default_resources={"api": 1.0})
+```
+
 ---
 
+
 ## 🛠️ 死信队列与运维 (DLQ & Ops)
 
 当任务重试超限或发生致命错误时，任务进入持久化死信队列 (DLQ)。可以通过标准 API 检查与清理：
@@ -297,21 +340,27 @@ pipeline.clear_history("download::")
 
 ```
 tasklite/
-├── pipeline.py          # TaskLite / TaskLite 核心门面与配置
+├── pipeline.py          # TaskLite 核心门面与配置
+├── hooks.py             # 用户工具函数（job_ref / progress_hook / slice_list）
 ├── engine/              # 核心执行机器群
-│   ├── loop.py          # 主调度事件循环 (LoopRunner)
+│   ├── runtime.py       # 核心运行期深模块、主循环事件泵 (EngineRuntime)
+│   ├── config.py        # RunConfig 静态装配快照、默认值唯一解析点
+│   ├── session.py       # RunSession 单次 run 生命周期状态与钩子单一出口
+│   ├── pacing.py        # 事件泵等待/空闲决策纯函数（decide_wait）
+│   ├── types.py         # 引擎公共值对象单一真相源
+│   ├── store.py         # 状态事务、3-strike 崩溃与死锁归因 (StateStore)
+│   ├── console.py       # OpsConsole：run() 外纯运维接缝（管理 API 委托目标）
 │   ├── dispatch.py      # 任务派发状态机 (DispatchMachine)
 │   ├── completion.py    # 任务完成与提交 (CompletionMachine)
 │   ├── recovery.py      # 崩溃检测与恢复 (RecoveryMachine)
-│   ├── failure.py       # 失败收敛与死信归因 (FailureMachine)
+│   ├── channel.py       # IPC 与子进程执行通道 (ExecutionChannel / WorkerLaunchSpec)
 │   ├── scheduler.py     # 资源调度与 DAG 依赖 (JobScheduler)
-│   ├── executor.py      # 子进程隔离执行器与看门狗
 │   └── resource.py      # 令牌桶限速与并发容量资源
 ├── backend/             # SQLite WAL 强一致事务持久化后端
 ├── models/              # Job / TaskContext / PipelineState 数据模型
-├── wrappers/            # discovery.py（增量扫描封装）
-├── pipeline_util.py     # 通用脚手架（任务指纹 / 进度钩子 / 瞬态错误注册）
-└── utils/               # jsonutil (禁NaN) / lockfile / validation
+├── taxonomy.py          # 错误分类法与校验分类深模块 (ErrorTaxonomy)
+├── wrappers/            # discovery.py（增量扫描）/ http.py（网络守卫与快照）
+└── utils/               # jsonutil (禁NaN) / lockfile
 ```
 
 ---

tasklite_engine-1.0.0/tasklite_engine.egg-info/PKG-INFO → tasklite_engine-1.2.0/README.md

@@ -1,19 +1,3 @@
-Metadata-Version: 2.4
-Name: tasklite-engine
-Version: 1.0.0
-Summary: A lightweight task orchestration engine with zero external dependencies, process isolation, and ACID persistence
-License-Expression: MIT
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: hypothesis>=6.0; extra == "dev"
-Requires-Dist: mutmut>=3.0; extra == "dev"
-Requires-Dist: pytest-timeout>=2.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Dynamic: license-file
-
 # ⚡ TaskLite — 零依赖、进程隔离的轻量任务编排引擎
 
 > **A Lightweight Task Orchestration Engine for Agent & Batch Pipelines.**  
@@ -125,8 +109,15 @@ flowchart TD
 - `ctx.declare_output()` 声明产出文件，内置路径遍历防御 (`../` 拒绝)；
 - 任务成功时校验物理产出完整性，任务失败时自动清理半成品文件，避免残留。
 
+### 7. 🌐 组合式 HTTP 网络工具与快照守卫 (HTTP Wrappers)
+- 开放 Callable 设计，支持原生 `urllib`、`requests`、`httpx` 或平台自定义签名 SDK；
+- `http_guard` 自动捕获 429、解析 `Retry-After` 并触发 `ctx.suspend_resource` 全管线退避，收敛异常三分类；
+- `SQLiteSnapshotStore` 提供单射键原始响应快照持久化，支持全离线幂等重放；
+- 内置标准 Netscape `cookies.txt` 解析工具。
+
 ---
 
+
 ## 🚀 快速上手 (Quickstart)
 
 ### 安装
@@ -273,8 +264,31 @@ pipeline.enqueue([
 pipeline.run()
 ```
 
+### Recipe 5: 官方 HTTP 守卫与原始响应快照重放 (HTTP Wrappers)
+
+```python
+from tasklite import TaskLite, RateLimitResource
+from tasklite.wrappers.http import SQLiteSnapshotStore, http_guard, fetch_urllib
+
+pipeline = TaskLite("crawler", state_dir="./states")
+pipeline.add_resource(RateLimitResource("api", interval_seconds=1.0))
+
+# 原始 HTTP 响应持久化快照（独立 snapshots.db，支持全离线重放与反爬保护）
+snapshot_store = SQLiteSnapshotStore("./snapshots.db")
+cached_fetch = snapshot_store.cached(fetch_urllib)
+
+def crawler_handler(job, ctx):
+    # 429 时自动挂起 api 资源、5xx 瞬态重试、4xx 直接 DLQ
+    with http_guard(ctx=ctx, resource="api", default_suspend_ttl=60.0):
+        resp = cached_fetch(job.payload["url"])
+        return resp.json()
+
+pipeline.register_handler("fetch", crawler_handler, default_resources={"api": 1.0})
+```
+
 ---
 
+
 ## 🛠️ 死信队列与运维 (DLQ & Ops)
 
 当任务重试超限或发生致命错误时，任务进入持久化死信队列 (DLQ)。可以通过标准 API 检查与清理：
@@ -297,21 +311,27 @@ pipeline.clear_history("download::")
 
 ```
 tasklite/
-├── pipeline.py          # TaskLite / TaskLite 核心门面与配置
+├── pipeline.py          # TaskLite 核心门面与配置
+├── hooks.py             # 用户工具函数（job_ref / progress_hook / slice_list）
 ├── engine/              # 核心执行机器群
-│   ├── loop.py          # 主调度事件循环 (LoopRunner)
+│   ├── runtime.py       # 核心运行期深模块、主循环事件泵 (EngineRuntime)
+│   ├── config.py        # RunConfig 静态装配快照、默认值唯一解析点
+│   ├── session.py       # RunSession 单次 run 生命周期状态与钩子单一出口
+│   ├── pacing.py        # 事件泵等待/空闲决策纯函数（decide_wait）
+│   ├── types.py         # 引擎公共值对象单一真相源
+│   ├── store.py         # 状态事务、3-strike 崩溃与死锁归因 (StateStore)
+│   ├── console.py       # OpsConsole：run() 外纯运维接缝（管理 API 委托目标）
 │   ├── dispatch.py      # 任务派发状态机 (DispatchMachine)
 │   ├── completion.py    # 任务完成与提交 (CompletionMachine)
 │   ├── recovery.py      # 崩溃检测与恢复 (RecoveryMachine)
-│   ├── failure.py       # 失败收敛与死信归因 (FailureMachine)
+│   ├── channel.py       # IPC 与子进程执行通道 (ExecutionChannel / WorkerLaunchSpec)
 │   ├── scheduler.py     # 资源调度与 DAG 依赖 (JobScheduler)
-│   ├── executor.py      # 子进程隔离执行器与看门狗
 │   └── resource.py      # 令牌桶限速与并发容量资源
 ├── backend/             # SQLite WAL 强一致事务持久化后端
 ├── models/              # Job / TaskContext / PipelineState 数据模型
-├── wrappers/            # discovery.py（增量扫描封装）
-├── pipeline_util.py     # 通用脚手架（任务指纹 / 进度钩子 / 瞬态错误注册）
-└── utils/               # jsonutil (禁NaN) / lockfile / validation
+├── taxonomy.py          # 错误分类法与校验分类深模块 (ErrorTaxonomy)
+├── wrappers/            # discovery.py（增量扫描）/ http.py（网络守卫与快照）
+└── utils/               # jsonutil (禁NaN) / lockfile
 ```
 
 ---

{tasklite_engine-1.0.0 → tasklite_engine-1.2.0}/pyproject.toml

@@ -1,15 +1,35 @@
 [build-system]
-requires = ["setuptools"]
+requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "tasklite-engine"
-version = "1.0.0"
+dynamic = ["version"]
+
 description = "A lightweight task orchestration engine with zero external dependencies, process isolation, and ACID persistence"
 requires-python = ">=3.9"
 license = "MIT"
 readme = "README.md"
 
+# PEP 639：license 以 SPDX 表达式声明，与 License 分类器互斥，不得再列 MIT classifier
+keywords = ["task-queue", "task-orchestration", "background-jobs", "subprocess", "process-isolation", "acid", "workflow"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/CaptainLi321/tasklite"
+Repository = "https://github.com/CaptainLi321/tasklite"
+
 [project.optional-dependencies]
 dev = ["pytest", "hypothesis>=6.0", "mutmut>=3.0", "pytest-timeout>=2.0", "pytest-cov>=4.0"]
 
@@ -17,6 +37,10 @@ dev = ["pytest", "hypothesis>=6.0", "mutmut>=3.0", "pytest-timeout>=2.0", "pytes
 include = ["tasklite", "tasklite.*"]
 exclude = ["tests"]
 
+# 版本单一事实源：tasklite/__init__.py 的 __version__，构建时动态读取
+[tool.setuptools.dynamic]
+version = { attr = "tasklite.__version__" }
+
 # PEP 561：py.typed 标记随包分发，下游 mypy/pyright 可消费内联类型注解
 [tool.setuptools.package-data]
 tasklite = ["py.typed"]
@@ -47,7 +71,6 @@ source_paths = [
     "tasklite/wrappers/",
     "tasklite/exceptions.py",
     "tasklite/pipeline.py",
-    "tasklite/pipeline_util.py",
 ]
 also_copy = ["tasklite/"]
 pytest_add_cli_args = ["--import-mode=importlib"]

tasklite_engine-1.2.0/tasklite/__init__.py

@@ -0,0 +1,134 @@
+"""TaskLite — 零外部依赖、物理进程隔离的轻量高可靠任务编排引擎。
+
+A lightweight, battle-hardened task orchestration engine with zero external
+dependencies, process isolation, and ACID persistence.
+"""
+
+__version__ = "1.2.0"
+
+
+# Public API - Core
+from .models.context import TaskContext
+from .exceptions import (
+    FatalError, PipelineError, RateLimitHit, RetryError,
+)
+from .models.job import Job, JobRuntimeState
+from .hooks import job_ref, progress_hook, slice_list
+from .pipeline import DLQEntry, TaskLite, WORKER_RESOURCE
+from .utils.injective import (
+    content_fingerprint,
+    escape_injective,
+    safe_uid_filename,
+    sanitize_content_id,
+    sanitize_identifier,
+    sanitize_job_component,
+)
+
+# Public API - Taxonomy & Validation
+from .taxonomy import (
+    ERR_COMMIT_FAILURE_DLQ,
+    ERR_DEADLOCK_GAP,
+    ERR_DEPENDENCY_DEADLOCK,
+    ERR_DISPATCH_FAILURE,
+    ERR_JOB_DEPENDENCY,
+    ERR_MALFORMED_JOB,
+    ERR_MAX_RETRIES,
+    ERR_NO_HANDLER,
+    ERR_PAYLOAD_VALIDATION,
+    ERR_RESOURCE_DEADLOCK,
+    ERROR_TYPE_COMMIT_FAILURE,
+    ERROR_TYPE_DEADLOCK,
+    ERROR_TYPE_DEPENDENCY,
+    ERROR_TYPE_DISPATCH,
+    ERROR_TYPE_FATAL,
+    ERROR_TYPE_NO_HANDLER,
+    ERROR_TYPE_TRANSIENT_EXHAUSTED,
+    ERROR_TYPE_UNKNOWN,
+    ERROR_TYPE_VALIDATION,
+    FATAL_EXCEPTIONS,
+    TRANSIENT_EXCEPTIONS,
+    ErrorCategory,
+    ErrorClassification,
+    ErrorTaxonomy,
+    TransientRegistry,
+    ValidationErrorItem,
+    ValidationResult,
+    classify_error_type,
+    classify_exception,
+    is_transient_exception,
+    validate_payload,
+    validate_resource_amounts,
+)
+
+# Public API - Contrib ecosystem
+from . import contrib
+
+# Public API - Resources
+from .engine.resource import CapacityResource, RateLimitResource, Resource
+
+__all__ = [
+    # Core
+    "TaskLite",
+    "Job",
+    "JobRuntimeState",
+    "TaskContext",
+    "RetryError",
+    "FatalError",
+    "PipelineError",
+    "RateLimitHit",
+    "FATAL_EXCEPTIONS",
+    "TRANSIENT_EXCEPTIONS",
+    "TransientRegistry",
+    "classify_exception",
+    "is_transient_exception",
+    "WORKER_RESOURCE",
+    "DLQEntry",
+    "job_ref",
+    "progress_hook",
+    "slice_list",
+    # Taxonomy, Errors & Validation
+    "ErrorTaxonomy",
+    "ErrorCategory",
+    "ErrorClassification",
+    "ValidationErrorItem",
+    "ValidationResult",
+    "classify_error_type",
+    "validate_payload",
+    "validate_resource_amounts",
+    "ERR_DEPENDENCY_DEADLOCK",
+    "ERR_JOB_DEPENDENCY",
+    "ERR_PAYLOAD_VALIDATION",
+    "ERR_MAX_RETRIES",
+    "ERR_NO_HANDLER",
+    "ERR_RESOURCE_DEADLOCK",
+    "ERR_MALFORMED_JOB",
+    "ERR_COMMIT_FAILURE_DLQ",
+    "ERR_DISPATCH_FAILURE",
+    "ERR_DEADLOCK_GAP",
+    "ERROR_TYPE_FATAL",
+    "ERROR_TYPE_TRANSIENT_EXHAUSTED",
+    "ERROR_TYPE_DEPENDENCY",
+    "ERROR_TYPE_DEADLOCK",
+    "ERROR_TYPE_NO_HANDLER",
+    "ERROR_TYPE_VALIDATION",
+    "ERROR_TYPE_COMMIT_FAILURE",
+    "ERROR_TYPE_DISPATCH",
+    "ERROR_TYPE_UNKNOWN",
+    # Injective & Fingerprint
+    "content_fingerprint",
+    "escape_injective",
+    "sanitize_identifier",
+    "sanitize_job_component",
+    "sanitize_content_id",
+    "safe_uid_filename",
+    # Contrib
+    "contrib",
+    # Resources
+    "Resource",
+    "RateLimitResource",
+    "CapacityResource",
+    # Version
+    "__version__",
+]
+
+

tasklite_engine-1.2.0/tasklite/backend/__init__.py

@@ -0,0 +1,12 @@
+"""State persistence backends for tasklite."""
+
+from .base import AbstractStateBackend, classify_error_type
+from .memory import InMemoryStateBackend
+from .sqlite_backend import SQLiteStateBackend
+
+__all__ = [
+    "AbstractStateBackend",
+    "InMemoryStateBackend",
+    "SQLiteStateBackend",
+    "classify_error_type",
+]

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

@@ -1,8 +1,10 @@
 """Abstract state backend interface for tasklite."""
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from typing import Any, Dict, List, Optional, Tuple
 
-from ..error_codes import (
+from ..taxonomy import (
     ERR_COMMIT_FAILURE_DLQ,
     ERR_DEADLOCK_GAP,
     ERR_DEPENDENCY_DEADLOCK,

tasklite_engine-1.2.0/tasklite/backend/memory.py

@@ -0,0 +1,224 @@
+"""纯内存状态后端适配器（InMemoryStateBackend）。
+
+实现 AbstractStateBackend 完整契约，提供零文件系统 IO 的纯内存状态存储。
+适用于瞬态管线、单元测试、沙盒执行与 CI 矩阵测试。
+"""
+from __future__ import annotations
+
+import copy
+import logging
+import threading
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+from .base import AbstractStateBackend, classify_error_type
+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 save_queue(self, jobs: List[Dict[str, Any]]) -> None:
+        with self._lock:
+            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))
+            self._queue = clean
+
+    def _write_dlq_entry(self, uid: str, meta: dict) -> None:
+        """DLQ 写入单一出口：维护 _attempt 计数、error_type 与 failed_at。"""
+        new_meta = copy.deepcopy(meta or {})
+        prev = self._failed.get(uid, {})
+        prev_attempts = prev.get("_attempt", 0) if isinstance(prev, dict) else 0
+        new_meta["_attempt"] = prev_attempts + 1
+
+        if "error_type" not in new_meta:
+            new_meta["error_type"] = classify_error_type(new_meta)
+
+        if "failed_at" not in new_meta:
+            new_meta["failed_at"] = datetime.now(timezone.utc).isoformat()
+
+        self._failed[uid] = new_meta
+
+    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:
+                self._wall[uid] = copy.deepcopy(result_meta or {})
+                self._queue = [j for j in self._queue if uid_from_job_dict(j) != uid]
+                self._failed.pop(uid, None)
+
+                if spawned_jobs:
+                    existing_uids = {uid_from_job_dict(j) for j in self._queue}
+                    for sj in spawned_jobs:
+                        suid = uid_from_job_dict(sj)
+                        if suid in existing_uids:
+                            logger.critical(
+                                f"commit_job_success for {uid}: spawned job {suid} "
+                                f"conflicts with queue (drift). Returning False."
+                            )
+                            return False
+                    # 队首插入 spawned_jobs 并保序
+                    self._queue[0:0] = [copy.deepcopy(j) for j in spawned_jobs]
+
+                if cursor_updates:
+                    for k, v in cursor_updates.items():
+                        if v is None:
+                            self._cursors.pop(k, None)
+                        else:
+                            self._cursors[k] = str(v)
+                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:
+                self._write_dlq_entry(uid, result_meta)
+                self._queue = [j for j in self._queue if uid_from_job_dict(j) != uid]
+                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:
+                self._queue = [j for j in self._queue if uid_from_job_dict(j) != popped_uid]
+                if front:
+                    self._queue.insert(0, copy.deepcopy(requeued_job))
+                else:
+                    self._queue.append(copy.deepcopy(requeued_job))
+                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:
+                fail_uids = {u for u, _ in uids_metas}
+                self._queue = [j for j in self._queue if uid_from_job_dict(j) not in fail_uids]
+                for uid, meta in uids_metas:
+                    self._write_dlq_entry(uid, meta)
+                    self._wall.pop(uid, None)
+                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 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:
+        with self._lock:
+            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.0.0 → tasklite_engine-1.2.0}/tasklite/backend/sqlite_backend.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import json
 import logging
 import sqlite3

tasklite_engine-1.2.0/tasklite/engine/__init__.py

@@ -0,0 +1,20 @@
+"""Engine subpackage for tasklite.
+
+核心执行与深模块架构：
+- ``types``: 引擎公共值对象单一真相源（StepOutcome / RunSummary / TaskStats / StopMode 等）；
+- ``config``: RunConfig 静态装配快照与 resolve_tuning 默认值唯一解析点；
+- ``runtime``: 核心运行期深模块与主循环事件泵 (EngineRuntime)；
+- ``session``: 单次 run 生命周期状态与钩子单一出口 (RunSession)；
+- ``pacing``: 等待/空闲决策纯函数 (decide_wait / LoopFacts)；
+- ``store``: 统一状态事务、3-strike 崩溃与死锁归因深模块 (StateStore)；
+- ``dispatch``: 派发预检关与子进程派发编排 (DispatchMachine)；
+- ``completion``: 结果提交、清理、释放与恢复收尾 (CompletionMachine)；
+- ``recovery``: 崩溃恢复、TOCTOU 闭环 abort 与信号排空 (RecoveryMachine)；
+- ``channel``: 子进程生命周期、阶梯看门狗、IPC 通道与产物清理 (ExecutionChannel)；
+- ``scheduler``: 队列只读扫描与不可变投影缓存 (JobScheduler)；
+- ``resource``: 限速与容量资源抽象与挂起语义 (ResourceManager / Resource)；
+- ``governor``: 死锁归因与依赖宽限治理 (DeadlockGovernor)；
+- ``policy``: Rerun 决策、指纹缓存与退避状态机 (ExecutionPolicy)；
+- ``inflight``: 在途作业生命周期跟踪与资源租约 (InFlightTracker)；
+- ``console``: run() 外管理 API 运维接缝 (OpsConsole)。
+"""