tasklite-engine 1.0.0__py3-none-any.whl

tasklite/engine/scheduler.py

@@ -0,0 +1,346 @@
+"""Job scheduler for tasklite.
+
+The scheduler performs a read-only scan over the queue to find the next
+runnable job. It does NOT acquire resources (only ``can_acquire``); the
+actual acquisition happens in the pipeline after the job is popped.
+"""
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Dict, FrozenSet, List, Optional, Tuple
+
+from .runtime import RT_BACKOFF_UNTIL
+from ..models.job import Job
+
+logger = logging.getLogger("tasklite")
+
+
+@dataclass(frozen=True)
+class JobFacts:
+    """不可变调度投影（scheduler 缓存唯一持有的 Job 视图）。
+
+    调度扫描只读四个事实：uid / task_type / resources / depends_on。
+    frozen dataclass + tuple/tuple 让 `_job_cache` 命中返回的对象无法被
+    任何调用点原地改写——「缓存不透出可变对象」由类型直接保证。
+    """
+
+    uid: str
+    task_type: str
+    resources: Tuple[Tuple[str, float], ...]
+    depends_on: Tuple[str, ...]
+
+    @classmethod
+    def from_job_dict(cls, job_dict: dict) -> "JobFacts":
+        """完整走 Job.from_dict 校验，然后冻结调度所需字段。"""
+        job = Job.from_dict(job_dict)
+        return cls(
+            uid=job.uid,
+            task_type=job.task_type,
+            resources=tuple(sorted(job.resources.items())),
+            depends_on=tuple(job.depends_on),
+        )
+
+    def resource_map(self) -> Dict[str, float]:
+        """解冻 resources 供 can_acquire/merge 使用（只读消费）。"""
+        return dict(self.resources)
+
+
+@dataclass
+class ScheduleResult:
+    """Outcome of a read-only scan over the queue.
+
+    ``kind`` 显式表达 runnable_idx + pending_dep_failure + dep_failed_idx
+    的兜底关系：
+
+    - ``kind == "runnable"``：runnable_idx 指向真正可运行的 job；
+    - ``kind == "dep_failed"``：runnable_idx 指向 dep-failed 兜底位置
+      （pending_dep_failure 携带失败依赖，_dispatch_job 走依赖失败分支）；
+    - ``kind == "none"``：无可运行 job（本轮无 job 可派发）。
+    """
+    # 「无」用 None 而非 C 风格 -1 哨兵；kind 字段显式表达状态，
+    # 索引仅在 kind 为 "runnable"/"dep_failed" 时有意义。
+    runnable_idx: Optional[int] = None
+    pending_dep_failure: Optional[str] = None
+    min_wait: float = float('inf')
+    waiting_for_dependency: bool = False
+    # 结果类型（runnable / dep_failed / none）
+    kind: str = "none"
+    # 细粒度死锁分类：只失败肇事者，被阻断者走正常 cascade
+    unknown_resource_indices: List[int] = field(default_factory=list)
+    missing_dependency_indices: List[int] = field(default_factory=list)
+    # 畸形 job dict（无法反序列化）的索引，优先级最高
+    malformed_indices: List[int] = field(default_factory=list)
+    # 不可达资源（can_acquire 返回 inf）的索引，细粒度失败而非全部 cascade
+    impossible_resource_indices: List[int] = field(default_factory=list)
+
+
+class JobScheduler:
+    """Read-only scanner that locates the next runnable job in the queue."""
+
+    def __init__(self, resources: Dict[str, "Resource"], handlers: Optional[Dict[str, "HandlerEntry"]] = None):
+        self.resources = resources
+        # handler 注册表（task_type -> HandlerEntry）的引用，用于把
+        # handler 默认资源合并进扫描的资源检查（调度器必须看到
+        # 与 _dispatch_job 实际 acquire 完全一致的资源集，否则 handler 注册前
+        # 入队的作业会绕过限速/容量检查）。
+        # 不能写 `handlers or {}`——空 dict 是 falsy，or 会换成
+        # **新**空 dict，register_handler 的写入对 scheduler 不可见（handler
+        # 默认资源从扫描资源集消失）。
+        self.handlers = handlers if handlers is not None else {}
+        # Job 反序列化缓存——pop_next_runnable 每轮对每条 job_dict
+        # 全量 Job.from_dict（含全部字段校验），W 槽位填池 = W×N 次解析；
+        # 万级队列 + 高完成频率下纯烧 CPU。
+        # 缓存键为内容键 (task_type, job_id)——id(job_dict) 键有
+        # id-reuse-after-free 风险：dict 被 pop 释放后地址
+        # 可被新队列条目复用，cached_job 返回陈旧 Job → 调度决策错误；
+        # 内容键天然免疫地址复用。queue 中 uid 唯一（_queue_uids set），
+        # (task_type, job_id) 与 uid 一一对应，无碰撞。
+        # 缓存值为不可变 JobFacts（调度投影）——
+        # 缓存不透出、可变字段走活 dict、派发重解析三重约定中的前两重
+        # 由不可变类型直接保证。
+        self._job_cache: Dict[Tuple[str, str], JobFacts] = {}
+        self._JOB_CACHE_MAX = 100_000
+
+    def begin_round(self) -> None:
+        """清空调度缓存（**run 生命周期**，由 ``_run_body`` 加载期调用）。
+
+        内容键 + 只读字段（depends_on/task_type/resources/uid）
+        使缓存跨轮安全：retries/runtime/backoff 从 live job_dict 读取，
+        retry 路径用 retry_dict["resources"] 恢复原始资源与缓存一致，
+        spawn 去重防同 uid 冲突——阻塞/退避/慢 job 阶段主循环 ~20Hz 轮询
+        时避免每轮全量反序列化队列（N=10 万 ≈ 240ms/轮 CPU 空烧）。
+        跨 run 陈旧（clear_history + 重新 enqueue 同 uid 不同内容）由
+        加载期清空覆盖。
+        """
+        self._job_cache.clear()
+
+    def cached_job(self, job_dict: dict) -> JobFacts:
+        """返回 job_dict 的不可变调度投影（内容键缓存复用）。
+
+        公开方法：失败机器的依赖宽限路径跨模块复用同一缓存（免二次
+        全量反序列化），调度扫描本身也是唯一内部消费方。
+        """
+        key = (job_dict.get("task_type"), job_dict.get("job_id"))
+        if key[0] is None or key[1] is None:
+            # 畸形 dict（缺 task_type/job_id）无法用内容键——直接解析不缓存
+            return JobFacts.from_job_dict(job_dict)
+        facts = self._job_cache.get(key)
+        # 缓存一致性校验：缓存命中时校验「调度只读字段」一致——rerun="every_run"
+        # 的 job 在 wall 命中时被 spawn 去重豁免（文档化「每会话重扫」语义），
+        # 可在**同一 run 内**让同 uid 以不同 resources/depends_on 二次入队。
+        # 若直接返回陈旧缓存，调度器（缓存投影）与派发器（Job.from_dict 重新
+        # 解析的 fresh Job）看到不同字段 → 未知资源/依赖判定背离，以裸 KeyError
+        # 击穿整条 run。字段不一致视为 miss 重新解析；同 uid 同内容
+        # （retry/常规重跑/requeue）仍命中缓存，保留缓存复用的性能收益。
+        if facts is not None and self._sched_fields_match(facts, job_dict):
+            return facts
+        facts = JobFacts.from_job_dict(job_dict)
+        if len(self._job_cache) >= self._JOB_CACHE_MAX:
+            self._job_cache.clear()
+        self._job_cache[key] = facts
+        return facts
+
+    @staticmethod
+    def _sched_fields_match(job, job_dict: dict) -> bool:
+        """校验缓存投影（或 Job）与 job_dict 的调度只读字段一致。
+
+        ``job`` 接受 ``JobFacts``（生产缓存路径）或 ``Job``（测试直调）——
+        两者都只读 depends_on/resources；``dict(...)`` 归一化让
+        ``tuple[(k,v),...]``（JobFacts）与 ``dict``（Job）在此等价。
+
+        内容键 (task_type, job_id) 假设同 uid 内容不变；every_run 重 spawn 打破
+        该假设。仅 depends_on/resources 影响调度判定（unknown/missing/依赖/
+        can_acquire），比对二者即可判定能否安全复用缓存。
+
+        null 语义与 ``Job.from_dict`` 对齐：``resources=None``→``{}``、
+        ``depends_on=None``→``[]``（否则 ``dict(None)``/``list(None)`` 抛
+        TypeError，把**本可正常解析执行**的合法 job 误判为畸形进 DLQ——
+        避免将合法任务误判为畸形）。非 dict/非 list 的畸形值视为不一致，
+        返回 False（重新解析，``Job.from_dict`` 会对畸形正确抛错归位）。
+        """
+        raw_res = job_dict.get("resources")
+        raw_dep = job_dict.get("depends_on")
+        try:
+            job_res = dict(raw_res) if raw_res is not None else {}
+            job_dep = list(raw_dep) if raw_dep is not None else []
+        except (TypeError, ValueError):
+            return False  # 畸形值 → 不一致，重新解析（Job.from_dict 会拒）
+        cached_res = dict(job.resources) if not isinstance(job.resources, dict) else job.resources
+        return list(job.depends_on) == job_dep and cached_res == job_res
+
+    def _effective_resources(self, job) -> Dict[str, float]:
+        """job 实际会 acquire 的资源集 = handler 默认资源 ∪ job 自身 resources。
+
+        接受 ``JobFacts``（扫描路径）或 ``Job``（测试/兼容直调）——两者都有
+        ``task_type``/``resources`` 只读字段。
+        """
+        if isinstance(job, JobFacts):
+            job_resources = job.resource_map()
+        else:
+            job_resources = dict(job.resources)
+        entry = self.handlers.get(job.task_type)
+        defaults = entry.default_resources if entry is not None else {}
+        if not defaults:
+            return job_resources
+        return {**defaults, **job_resources}
+
+    def pop_next_runnable(
+        self,
+        state,
+        in_flight_uids: FrozenSet[str] = frozenset(),
+    ) -> ScheduleResult:
+        """Scan queue read-only. Returns index and wait info. Does NOT acquire resources.
+
+        ``state`` 是 PipelineState 实例（读取 queue/wall/failed/queue_uids——
+        ``queue_uids`` 返回活索引引用，提供 O(1) 索引，无 O(N) 拷贝）。
+
+        ``in_flight_uids`` 是当前正在子进程中执行（已 pop 但未 commit）的 job uid
+        集合。在 missing dependency 判定时，依赖正在运行的 job 不算 missing
+        （待其完成 commit 到 wall 后自然解锁），避免并发模型下误判死锁。
+        """
+        q_data = state.queue
+        wall_data = state.wall
+        failed_data = state.failed
+        queue_uids = state.queue_uids
+        pending_or_running = queue_uids | set(in_flight_uids)
+
+        runnable_idx = None
+        min_wait = float('inf')
+        waiting_for_dependency = False
+        pending_dep_failure: Optional[str] = None
+        dep_failed_idx: int = -1  # 首个 dep-failed job 的索引（兜底）
+        unknown_resource_indices: List[int] = []
+        missing_dependency_indices: List[int] = []
+        malformed_indices: List[int] = []
+        impossible_resource_indices: List[int] = []
+
+        now = time.monotonic()
+
+        for i, job_dict in enumerate(q_data):
+            # 捕获畸形 job dict（缺 task_type/job_id 等），记录索引避免整个扫描崩溃
+            try:
+                job = self.cached_job(job_dict)
+            except (KeyError, TypeError, ValueError) as e:
+                logger.error(f"Malformed job dict at index {i}: {e}")
+                malformed_indices.append(i)
+                continue
+            can_run = True
+            failed_dependency = None
+
+            # 1. Failed dependency: job is runnable (will be marked as dependency failure)
+            if job.depends_on:
+                for dep_uid in job.depends_on:
+                    if dep_uid in failed_data:
+                        failed_dependency = dep_uid
+                        can_run = False
+                        break
+
+            if failed_dependency:
+                # 不在此 break——排在 dep-failed job 后面的**可运行** job
+                # 本轮会失去调度机会（且 malformed/impossible 等归因信息收集
+                # 被截断）。记录首个 pending_dep_failure，继续扫描：优先把
+                # 可运行 job 挑出来；若整轮没有可运行 job，runnable_idx 落回
+                # 最后一个 dep-failed 位置（_dispatch_job 会处理它）。
+                if pending_dep_failure is None:
+                    pending_dep_failure = failed_dependency
+                    dep_failed_idx = i
+                continue
+
+            # 2. Unknown resource detection (permanent deadlock regardless of dependencies)
+            # 用合并后资源集检查（含 handler 默认资源），与 _dispatch_job 的 acquire 一致
+            eff_resources = self._effective_resources(job)
+            for res_name in eff_resources:
+                if res_name not in self.resources:
+                    logger.error(f"Job {job.uid} references unknown resource '{res_name}'.")
+                    unknown_resource_indices.append(i)
+                    min_wait = float('inf')  # Deadlock: Unknown resource
+                    can_run = False
+                    break
+
+            # 3. Missing dependency: not runnable
+            if job.depends_on:
+                for dep_uid in job.depends_on:
+                    if dep_uid not in wall_data:
+                        can_run = False
+                        waiting_for_dependency = True
+                        # 不在第一个缺失依赖处 break——排在前面
+                        # 的 pending 依赖会遮蔽后面真正缺失的依赖（死锁漏检
+                        # → 无限轮询）。逐个检查全部依赖，把「不在 wall 也
+                        # 不在 queue/in-flight」的依赖全部记录为 missing。
+                        if dep_uid not in pending_or_running:
+                            missing_dependency_indices.append(i)
+
+            if not can_run:
+                continue
+
+            # 4. Resource availability（必须在本轮检查，
+            # 不能因退避跳过——否则退避中的 job 引用的 unknown/impossible
+            # 资源死锁会被无限推迟到退避结束）
+            for res_name, amount in eff_resources.items():
+                ok, wait_time = self.resources[res_name].can_acquire(amount)
+                if ok:
+                    continue
+                can_run = False
+                if wait_time == float('inf'):
+                    # 不可达资源（amount > capacity）→ 永久死锁，细粒度记录
+                    impossible_resource_indices.append(i)
+                else:
+                    min_wait = min(min_wait, wait_time)
+
+            # 5. Backoff — 复用循环顶部的 now 值，避免双重 time.monotonic 调用。
+            # 类型防御：脏数据（字符串等非数值 _backoff_until）直接视为无退避，
+            # 避免加载期崩溃（_run_body 只清理数值脏数据）。
+            # 注意：退避只影响「本轮可运行」，不影响上述资源死锁归因。
+            raw_rt = job_dict.get("runtime")
+            _backoff = raw_rt.get(RT_BACKOFF_UNTIL) if isinstance(raw_rt, dict) else None
+            if isinstance(_backoff, (int, float)) and _backoff > now:
+                remaining = _backoff - now
+                min_wait = min(min_wait, max(0.0, remaining))
+                continue
+
+            if can_run:
+                runnable_idx = i
+                break
+
+        # 兜底：整轮没有可运行 job 但存在 dep-failed job →
+        # runnable_idx 落回首个 dep-failed 位置（_dispatch_job 会处理它）。
+        if runnable_idx is None and pending_dep_failure is not None:
+            runnable_idx = dep_failed_idx
+
+        # pending_dep_failure 只在 runnable_idx 落回 dep-failed 兜底位置时才有效。
+        # 若 runnable_idx 指向真正可运行的 job（排在 dep-failed job 之后扫描选出的），
+        # 必须清空 pending_dep_failure，防止将依赖失败误判给可运行作业。
+        if runnable_idx != dep_failed_idx:
+            pending_dep_failure = None
+
+        # 死锁归因类集合（impossible/unknown/missing/malformed）任一非空时
+        # 强制 min_wait=inf：这些类别的判定不依赖任何等待——impossible/
+        # unknown 是永久性死锁，missing 由宽限逻辑单独裁决，malformed 无法
+        # 反序列化、永远不可能变为可运行。若被队列中另一 job 的有限退避/
+        # 资源等待覆盖 min_wait，死锁判定被逐轮推迟到该等待终结（退避逐轮
+        # 放大时可拖数十分钟，管线表现为卡死无日志）。
+        if (impossible_resource_indices or unknown_resource_indices
+                or missing_dependency_indices or malformed_indices) and min_wait != float('inf'):
+            min_wait = float('inf')
+
+        # 显式表达结果类型——兜底后 runnable_idx 与 pending_dep_failure
+        # 的关系决定 kind。
+        if runnable_idx is not None and pending_dep_failure is not None:
+            kind = "dep_failed"
+        elif runnable_idx is not None:
+            kind = "runnable"
+        else:
+            kind = "none"
+
+        return ScheduleResult(
+            runnable_idx=runnable_idx,
+            pending_dep_failure=pending_dep_failure,
+            min_wait=min_wait,
+            waiting_for_dependency=waiting_for_dependency,
+            kind=kind,
+            unknown_resource_indices=unknown_resource_indices,
+            missing_dependency_indices=missing_dependency_indices,
+            malformed_indices=malformed_indices,
+            impossible_resource_indices=impossible_resource_indices,
+        )

tasklite/error_codes.py

@@ -0,0 +1,66 @@
+"""框架错误码 —— DLQ error 字段与 error_type 分类的单一事实来源。
+``pipeline.py``（构造 DLQ meta）与 ``backend/base.py``（error_type 分类）
+共同引用，避免两处字符串字面量漂移。错误码是公开契约（README/AGENTS
+文档化）：任何新增的 DLQ 写入路径必须先在此登记错误码，再决定分类。
+"""
+# DLQ meta["error"] 字段值（框架写入的错误码） -------------------------
+ERR_DEPENDENCY_DEADLOCK = "DEPENDENCY_DEADLOCK"
+ERR_JOB_DEPENDENCY = "JOB_DEPENDENCY"
+ERR_PAYLOAD_VALIDATION = "PAYLOAD_VALIDATION_FAILED"
+ERR_MAX_RETRIES = "MAX_RETRIES_EXCEEDED"
+ERR_NO_HANDLER = "NO_HANDLER"
+ERR_RESOURCE_DEADLOCK = "RESOURCE_DEADLOCK"
+ERR_MALFORMED_JOB = "MALFORMED_JOB"
+ERR_COMMIT_FAILURE_DLQ = "COMMIT_FAILURE_DLQ"
+# dispatch 阶段失败（submit 的 pickle/启动报错、资源
+# acquire 校验失败）连续达阈值转 DLQ 的错误码——不可 pickle 的 lambda
+# handler 会触发无限崩溃重启循环（无 3-strike 兜底）
+ERR_DISPATCH_FAILURE = "DISPATCH_FAILURE"
+# 死锁分类缺口（环检测空 / 不可归因）连续多轮未分类 →
+# 升级为整队列 DLQ 时的专属错误码（区别于正常归因的 DEPENDENCY/RESOURCE_DEADLOCK）
+ERR_DEADLOCK_GAP = "DEADLOCK_CLASSIFICATION_GAP"
+# DLQ error_type 分类值（list_dlq 查询与 _write_dlq_row 落库共用） --------
+ERROR_TYPE_FATAL = "fatal"
+ERROR_TYPE_TRANSIENT_EXHAUSTED = "transient_exhausted"
+ERROR_TYPE_DEPENDENCY = "dependency"
+ERROR_TYPE_DEADLOCK = "deadlock"
+ERROR_TYPE_NO_HANDLER = "no_handler"
+ERROR_TYPE_VALIDATION = "validation"
+ERROR_TYPE_COMMIT_FAILURE = "commit_failure"
+# dispatch 失败（submit pickle/启动报错、资源 acquire 校验
+# 失败）的专属 error_type——list_dlq 查询可按「派发失败」过滤，与
+# 错误码集中登记的精神一致。
+ERROR_TYPE_DISPATCH = "dispatch"
+ERROR_TYPE_UNKNOWN = "unknown"
+
+
+def classify_error_type(meta: dict) -> str:
+    """从 DLQ meta 推导结构化 error_type（list_dlq() 查询与 _write_dlq_row 落库共用）。
+
+    分类优先级：fatal 标志最高（FatalError 确定性失败）；其次按 error 错误码
+    精确/前缀匹配；其余归 unknown。error 字段是自由字符串，前缀匹配只对框架错误码生效。
+    """
+    if not isinstance(meta, dict):
+        return ERROR_TYPE_UNKNOWN
+    if meta.get("fatal"):
+        return ERROR_TYPE_FATAL
+    error = str(meta.get("error", ""))
+    mapping = (
+        (ERR_DEPENDENCY_DEADLOCK, ERROR_TYPE_DEADLOCK),
+        (ERR_RESOURCE_DEADLOCK, ERROR_TYPE_DEADLOCK),
+        (ERR_MALFORMED_JOB, ERROR_TYPE_DEADLOCK),
+        (ERR_DEADLOCK_GAP, ERROR_TYPE_DEADLOCK),
+        (ERR_JOB_DEPENDENCY, ERROR_TYPE_DEPENDENCY),
+        (ERR_MAX_RETRIES, ERROR_TYPE_TRANSIENT_EXHAUSTED),
+        (ERR_NO_HANDLER, ERROR_TYPE_NO_HANDLER),
+        (ERR_PAYLOAD_VALIDATION, ERROR_TYPE_VALIDATION),
+    )
+    for code, etype in mapping:
+        if error == code or error.startswith(code):
+            return etype
+    if error.startswith(ERR_COMMIT_FAILURE_DLQ):
+        return ERROR_TYPE_COMMIT_FAILURE
+    if error.startswith(ERR_DISPATCH_FAILURE):
+        return ERROR_TYPE_DISPATCH
+    return ERROR_TYPE_UNKNOWN
+

tasklite/exceptions.py

@@ -0,0 +1,215 @@
+"""Exception types for tasklite.
+
+错误分类模型：
+
+三类异常在 handler 中的处理待遇完全不同：
+
+| 类别 | 包含 | 处理 |
+|------|------|------|
+| **Fatal** | `FatalError` + `FATAL_EXCEPTIONS` | 直接 DLQ，不消耗重试次数（确定性 bug） |
+| **Transient** | `RetryError` + `TRANSIENT_EXCEPTIONS` + 用户注册的瞬态类 | 自动重试（退避等待），达上限进 DLQ |
+| **Unknown** | 其余 `Exception` | 永久失败进 DLQ（与 Fatal 同路径，但元数据标记未知） |
+
+设计决策：
+- `RetryError` 是 Transient 的显式入口（业务主动声明「这次是瞬态」）。
+- `TRANSIENT_EXCEPTIONS` 覆盖常见瞬时故障（网络连接/超时/远端错误）——
+  业务无需手包 RetryError 即可让这些异常自动重试。
+- `pipeline.register_transient_exception(cls)`（per-pipeline 注册表）允许
+  业务把自有库的异常（如 requests.exceptions.ConnectionError）注册为瞬态。
+- 三分类 + 可配置白名单使网络抖动/超时这类天然瞬态错误自动重试而非
+  直接判死；`ValueError` 不入 FATAL_EXCEPTIONS——它含 JSONDecodeError
+  等可能瞬态的子类，直接判死会误杀可重试失败。
+"""
+
+from typing import Optional
+
+
+class PipelineError(Exception):
+    """Base class for all tasklite framework exceptions."""
+    pass
+
+
+class RetryError(PipelineError):
+    """Raise this in a handler to signal a transient failure. The job will be pushed back to the queue."""
+    pass
+
+
+class FatalError(PipelineError):
+    """Non-retryable error. Goes directly to DLQ without consuming retries.
+
+    Raise this for code-level bugs (invalid config, missing files that will
+    never appear, logic errors).
+    """
+    pass
+
+
+class RateLimitHit(RetryError):
+    """HTTP 429 信号。
+
+    ``RateLimitHit`` 是 ``RetryError`` 子类：裸抛即按瞬态退避重试。
+    裸抛降级语义——handler 忘记在重试前挂起资源时，不会因「未匹配任何
+    分类」按 Unknown 判死进 DLQ + 级联下游，仍走退避重试（代价是限流
+    资源在重试间隔内未被挂起）。需要在重试前挂起资源时，由调用方自行
+    调用资源挂起逻辑后抛 ``RetryError``。
+    """
+    pass
+
+
+# 确定性 bug 类：直接 DLQ，不重试。不含 ValueError——它包含 JSONDecodeError
+# 等可能瞬态的子类（由 TRANSIENT_EXCEPTIONS / register_transient_exception
+# 另行归类）。
+FATAL_EXCEPTIONS = (TypeError, KeyError, AttributeError,
+                    IndexError, StopIteration, ArithmeticError,
+                    ImportError, NotImplementedError, RecursionError)
+
+
+# 常见瞬态故障：自动重试（与 RetryError 同等待遇）。
+# ConnectionError/TimeoutError 是 OSError 子类；RemoteDisconnected 等
+# 网络断开异常在此被自动归类为可重试，业务无需手包 RetryError。
+TRANSIENT_EXCEPTIONS = (
+    ConnectionError,
+    TimeoutError,
+    ConnectionRefusedError,
+    ConnectionResetError,
+    ConnectionAbortedError,
+    BrokenPipeError,
+)
+
+def _validate_transient_class(exception_cls: type) -> None:
+    """注册入口校验（fail-loud）——per-pipeline 注册表与外部直调共用。"""
+    if not isinstance(exception_cls, type) or not issubclass(exception_cls, Exception):
+        raise TypeError(
+            f"register_transient_exception requires an Exception subclass, got {exception_cls!r}"
+        )
+    if issubclass(exception_cls, (RetryError, FatalError)):
+        # 专用 except 分支优先于注册表，注册必然静默无效，入口直接拒绝
+        raise TypeError(
+            f"register_transient_exception cannot register a "
+            f"{'RetryError' if issubclass(exception_cls, RetryError) else 'FatalError'} "
+            f"subclass ({exception_cls!r}) — these have dedicated except branches "
+            f"that bypass the registry; registration would silently no-op."
+        )
+    try:
+        import pickle
+        pickle.dumps(exception_cls)
+    except (pickle.PicklingError, AttributeError, TypeError) as e:
+        # 函数作用域定义的类无法被 spawn 子进程 import → 注册必然失效。
+        # 在此 fail-loud，把「子进程静默判死」提前为「注册时显式报错」。
+        raise TypeError(
+            f"register_transient_exception requires a module-level (picklable) "
+            f"Exception class for spawn-subprocess propagation, got {exception_cls!r}: {e}"
+        ) from e
+
+
+class TransientRegistry:
+    """**per-pipeline** 瞬态异常注册表。
+
+    注册在父进程、分类在子进程：注册表归 ``TaskLite`` 实例所有，
+    子进程分类只消费 ``TaskContext`` 携带的 ``snapshot()``（不可变
+    tuple）——无模块级可变注册表参与子进程决策，杜绝跨 pipeline
+    累积与跨 run 泄漏。
+    """
+
+    def __init__(self) -> None:
+        self._classes: list = []
+
+    def register(self, exception_cls: type) -> None:
+        """把业务自有异常类注册为瞬态（自动重试），幂等。
+
+        用于第三方库的异常（如 ``requests.exceptions.ConnectionError``）。
+        模块级类才可通过 pickle 预检（spawn 子进程分类依赖 ctx 快照）。
+        """
+        _validate_transient_class(exception_cls)
+        if exception_cls not in self._classes:
+            self._classes.append(exception_cls)
+
+    def snapshot(self) -> tuple:
+        """返回不可变注册表快照（随 ctx 显式下发子进程）。"""
+        return tuple(self._classes)
+
+    def matches(self, exc: BaseException) -> bool:
+        """exc 是否命中本注册表（父进程侧测试/诊断用）。"""
+        return any(isinstance(exc, cls) for cls in self._classes)
+
+
+def _matches_registry(exc: BaseException, registry) -> bool:
+    """纯判定：exc 是否命中给定注册表快照（tuple/TransientRegistry 皆可）。"""
+    classes = registry.snapshot() if isinstance(registry, TransientRegistry) else tuple(registry or ())
+    return any(isinstance(exc, cls) for cls in classes)
+
+
+def classify_exception(
+    exc: BaseException,
+    registry=(),
+    *,
+    fatal_exceptions: Optional[tuple] = None,
+    transient_exceptions: Optional[tuple] = None,
+) -> str:
+    """异常三分类的**唯一生产语义**，返回 retry/fatal/error。
+
+    分类顺序：RetryError → FatalError → 注册表（用户显式声明）→
+    FATAL_EXCEPTIONS（内置启发式）→ TRANSIENT_EXCEPTIONS → Unknown。
+    注册表判定必须在 FATAL_EXCEPTIONS 之前——用户显式声明永远优先于内置
+    启发式（否则注册 FATAL 子类会被 FATAL 分支短路）。
+
+    ``registry`` 是 ``ctx.transient_registry`` 下发的快照（不可变 tuple）；
+    子进程调用本函数**不读任何模块级可变状态**。
+
+    ``fatal_exceptions``/``transient_exceptions``：per-pipeline 覆盖——
+    与瞬态注册表同纪律，确定性/瞬态内置启发式的成员集合也可按 pipeline
+    定制（None=用模块默认元组）。快照随 ctx 下发子进程（可 pickle 的
+    tuple），分类决策不读模块级可变全局。
+    """
+    if isinstance(exc, RetryError):
+        return "retry"
+    if isinstance(exc, FatalError):
+        return "fatal"
+    if _matches_registry(exc, registry):
+        return "retry"
+    # is not None 判定（非真值判定）：空元组 = 显式「本 pipeline 无内置
+    # 判死/瞬态成员」，必须与 None（用模块默认）区分。
+    _fatal = FATAL_EXCEPTIONS if fatal_exceptions is None else tuple(fatal_exceptions)
+    _transient = TRANSIENT_EXCEPTIONS if transient_exceptions is None else tuple(transient_exceptions)
+    if isinstance(exc, _fatal):
+        return "fatal"
+    if isinstance(exc, _transient):
+        return "retry"
+    return "error"
+
+
+def is_transient_exception(exc: BaseException, registry=()) -> bool:
+    """判断异常是否属于瞬态（应自动重试）——分类语义的公开只读助手。
+
+    ``registry`` 缺省为空快照；测试/文档调用方如需包含注册表项，应传入
+    ``pipeline.transient_registry.snapshot()`` 或 ``TransientRegistry``。
+    生产侧分类一律走 ``classify_exception``（executor 子进程入口）。
+    """
+    return classify_exception(exc, registry) == "retry"
+
+
+class _CommitCrashSignal(BaseException):
+    """内部信号：commit 失败后已 requeue，需立即崩溃。
+
+    继承 ``BaseException``（而非 Exception）——从调用纪律变成结构保证：
+    任何 ``except Exception`` 兜底在类型系统层面捕不到它，无需依赖「except 顺序」约定。
+    它穿透一切 ``except Exception`` 直到 ``_run_loop`` 的显式分支（commit 失败需崩溃语义），
+    中途不会被误吞。不导出为公共 API（内部信号）。
+    """
+    pass
+
+
+class _JobTerminated(BaseException):
+    """内部信号：当前 job 已终结（DLQ 阈值命中），需立即停止处理。
+
+    继承 ``BaseException``——理由同 ``_CommitCrashSignal``：``except
+    Exception`` 在类型系统层面捕不到它，漏捕调用点不会被静默 requeue
+    （那是复发）。捕获点**必须**在 ``_dispatch_job``/``_complete_job``/
+    ``_restore_stale_result`` 内层（语义是「当前 job 停止处理」→ 返回 None），
+    **绝不应逃逸到 _run_loop**——若逃逸说明有调用点漏捕，应上抛暴露
+    而非静默吞掉（否则未来类漏洞被掩盖）。
+
+    与 _CommitCrashSignal 的区别：前者表达「commit 失败、系统需崩溃重启」
+    （on-disk 队列保留，at-least-once 重跑）；本异常表达「job 已被判定为
+    确定性坏输入、正常终结」（不崩溃、不重跑）。语义不同，分开捕获。
+    """
+    pass

tasklite/models/__init__.py

@@ -0,0 +1,6 @@
+"""Data models for tasklite."""
+from .job import Job, JobRuntimeState
+from .context import TaskContext
+from .state import PipelineState
+
+__all__ = ["Job", "JobRuntimeState", "TaskContext", "PipelineState"]