tasklite-engine 1.0.0__py3-none-any.whl

tasklite/models/context.py

@@ -0,0 +1,313 @@
+"""TaskContext for handler execution in tasklite."""
+
+import logging
+import math
+import os
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Union
+
+from .job import Job
+from ..utils.ipc import append_input, append_output, append_signal
+from ..utils.jsonutil import dumps
+
+logger = logging.getLogger("tasklite")
+
+
+class TaskContext:
+    """Context object passed to handlers, providing spawn, output, cursor, and resource APIs."""
+
+    def __init__(
+        self,
+        job: Job,
+        wall_keys: set,
+        failed_keys: set,
+        cursors: Dict[str, str],
+        output_root: Optional[Path] = None,
+        ipc_dir: Optional[str] = None,
+        incarnation: Optional[str] = None,
+        transient_registry: Tuple = (),
+        resource_names: Optional[Union[frozenset, set]] = None,
+    ):
+        self.job = job
+        self.new_jobs: List[Job] = []
+        self.resource_suspensions: List[Tuple[str, float]] = []
+        self._wall_keys = wall_keys
+        self._failed_keys = failed_keys
+        self._cursors = cursors
+        self.cursor_updates: Dict[str, str] = {}
+        # 已注册资源名快照——suspend_resource 据此 fail-loud。
+        # None（直接构造 ctx 的旧测试路径）表示不校验；生产派发路径必传。
+        self._resource_names: Optional[frozenset] = (
+            frozenset(resource_names) if resource_names is not None else None
+        )
+        # output_root 支持多根（跨盘输出场景）——list 时
+        # 路径属于**任一**根即通过沙盒校验。
+        self.output_root = output_root
+        # 注册表快照契约：瞬态异常注册表快照随 ctx pickle 下发子进程——
+        # spawn 子进程不继承父进程函数作用域的注册，分类决策在子进程发生，
+        # 快照在此携带、worker 入口重放（见 executor._mp_worker_wrapper）。
+        self.transient_registry = tuple(transient_registry)
+        # suspend 信号走落盘文件（{ipc_dir}/{uid}.signals.jsonl）——
+        # 进程被 kill 后文件仍在，信号不丢。
+        self.ipc_dir = ipc_dir
+        # fencing：当前执行代标识 {run_id}.{seq}，由 _dispatch_job
+        # 在 submit 前写入。worker 写结果文件时用它构造带 incarnation 的
+        # 文件名——崩溃后孤儿进程的旧 incarnation 文件不被新 run 看见。
+        self.incarnation = incarnation
+
+    def spawn(self, job: Job) -> None:
+        """Enqueue a child job.
+
+        在子进程内立即预检 JSON 可序列化性（与 enqueue 的序列化预检对齐）。
+        坏 payload 在此抛 ValueError → handler 异常 → 父作业进入 DLQ，
+        而不是在 commit 阶段才崩掉整个 run。
+        """
+        try:
+            # allow_nan=False —— 默认 allow_nan=True 会让
+            # float('inf')/float('nan') 通过预检，产出非标准 JSON "Infinity"。
+            dumps(job.to_dict())
+        except (TypeError, ValueError) as e:
+            raise ValueError(
+                f"Payload for spawned job {job.uid} is not JSON-serializable: {e}"
+            ) from e
+        self.new_jobs.append(job)
+
+    def declare_output(self, path: Union[str, Path], cleanup_on_fail: bool = True, *, sandbox: bool = True) -> str:
+        """Declare an output file. Validates path sandbox if output_root is set.
+
+        Automatically creates parent directories. On job failure (or retry),
+        declared outputs with ``cleanup_on_fail=True`` are deleted to prevent
+        half-written files from persisting.
+
+        ``sandbox=False`` 显式豁免路径沙盒（跨盘输出等
+        无法归入任何 output_root 的场景）——放弃越界保护，与
+        ``output_root=None`` 同语义，但逐路径声明而非全局关闭。
+
+        Returns:
+            The **resolved absolute path** that the framework will verify/clean —
+            handler 应用返回值写文件（而非原始参数），保证写入位置与校验/
+            清理位置一致（相对路径按 output_root 重定位，原始
+            相对字符串按 CWD 写会与校验脱节 → 误判 Missing output）。
+        """
+        return self._declare(path, cleanup_on_fail, sandbox, "output")
+
+    def declare_cache(self, path: Union[str, Path], *, sandbox: bool = True) -> str:
+        """Declare a **temporary/cache** file.
+
+        语义：任务结束时（无论成败）该文件**不应存在**。
+          - 成功路径：**跳过存在性校验**（原子产出的 ``.part`` 已被
+            ``os.replace`` 到最终路径，校验必然失败），并 best-effort 尝试
+            删除（rename 已发生则 no-op）；
+          - 失败/中止路径：删除半成品。
+
+        标准用法（原子产出模式）：``tmp = ctx.declare_cache("./v.mp4.part")``
+        写 tmp → 自校验 → ``os.replace(tmp, final)``；最终路径用
+        ``ctx.declare_output("./v.mp4")`` 声明（成功校验存在 + 失败清理）。
+
+        路径沙盒与 ``declare_output`` 相同：``sandbox=False`` 显式豁免
+        （跨盘缓存等无法归入任何 output_root 的场景）——放弃越界保护，
+        逐路径声明而非全局关闭。
+        返回解析后的规范绝对路径。
+        """
+        return self._declare(path, True, sandbox, "cache")
+
+    def _declare(self, path: Union[str, Path], cleanup_on_fail: bool, sandbox: bool, kind: str) -> str:
+        """declare_output/declare_cache 的共享实现（消除重复）。
+
+        kind 为 "output" 或 "cache"——仅影响 append_output 落盘的声明
+        kind（成功路径的校验/清理行为差异由 executor 侧按 kind 分发）。
+        """
+        raw = str(path)
+        if "\x00" in raw:
+            raise ValueError(f"Output path contains a null byte: {raw!r}")
+
+        resolved = self._resolve_path(raw, sandbox)
+        parent = Path(resolved).parent
+        parent.mkdir(parents=True, exist_ok=True)
+        # 输出声明立即落盘（{ipc_dir}/{uid}.outputs.jsonl）——主进程的
+        # 输出校验与失败清理从落盘文件读，不依赖 mp.Manager 共享 list
+        # （Manager 是独立 server 进程的隐性单点 + 每次声明一次 RPC 往返）。
+        # handler 崩溃/kill 后声明仍可读取（与 signals 同款语义）。
+        if self.ipc_dir is not None:
+            try:
+                append_output(self.ipc_dir, self.job.uid, resolved, cleanup_on_fail, kind=kind)
+            except OSError:
+                pass  # 落盘失败静默：声明丢失只影响失败清理，不影响执行
+        # 返回解析后的规范绝对路径，handler 应使用返回值写文件
+        return resolved
+
+    def declare_input(self, path: Union[str, Path]) -> str:
+        """声明一个**输入文件**——记录 + 采集指纹，返回规范绝对路径。
+
+        注意：本方法**没有** ``sandbox`` 参数，这是有意设计——输入声明只记录
+        路径与 stat 指纹，框架不写该文件，因此不存在输出沙盒/清理语义；
+        与 ``declare_output/declare_cache`` 的路径沙盒无关。
+
+        指纹 ``{path, size, mtime_ns}``（stat 调用，微秒级，不用内容 hash
+        避免大文件读盘）。任务成功时框架把输入清单写入 wall meta
+        （``meta["inputs"]``）——排障/审计/种子化脚本都能回答「这个任务
+        当时基于什么输入跑出来的」。
+
+        与 ``rerun="on_input_change"`` 联动：下次 enqueue 时框架对
+        wall 中的旧指纹重新 stat 比对，任一文件 size/mtime_ns 变化 → 重跑；
+        不变 → 跳过（on_input_change 的变更检测只针对文件输入；URI 默认
+        不检测，见 ``declare_input_uri``）。
+
+        指纹在**声明时**采集（handler 要读的输入此刻应已存在）；stat 失败
+        （文件不存在等）记录 path 但不带指纹（on_input_change 比对时视为
+        变化 → 重跑，避免误跳过）。
+        """
+        raw = str(path)
+        resolved = self._resolve_path(raw, sandbox=False)
+        entry: dict = {"path": resolved, "kind": "file"}
+        try:
+            st = os.stat(resolved)
+            entry["size"] = st.st_size
+            entry["mtime_ns"] = st.st_mtime_ns
+        except OSError:
+            pass  # 输入缺失：记录 path，指纹留空（on_input_change 视为变化）
+        if self.ipc_dir is not None:
+            try:
+                append_input(self.ipc_dir, self.job.uid, entry)
+            except OSError:
+                pass  # 只捕获 OSError：编程错误不静默吞
+        return resolved
+
+    def declare_input_uri(self, url: Union[str, Path], uri_fingerprint: Optional[str] = None) -> str:
+        """声明一个**输入 URI**——仅记录（可追溯），返回 url 字符串。
+
+        ``uri_fingerprint`` 可选：业务侧提供的指纹字符串（如 ETag/Last-
+        Modified），落盘供审计。**不参与 on_input_change 比对**——URI 的
+        内容是否变化需网络请求（ETag/Last-Modified），框架不在派发前免费
+        检查（文档注明：URI 变更检测留给业务，可把指纹拼进 job_id 或由
+        业务自建 checker）。
+        """
+        if uri_fingerprint is not None and not isinstance(uri_fingerprint, str):
+            raise TypeError(
+                f"uri_fingerprint must be a str or None, "
+                f"got {type(uri_fingerprint).__name__}"
+            )
+        url = str(url)
+        entry: dict = {"path": url, "kind": "uri"}
+        if uri_fingerprint is not None:
+            entry["uri_fingerprint"] = uri_fingerprint
+        if self.ipc_dir is not None:
+            try:
+                append_input(self.ipc_dir, self.job.uid, entry)
+            except OSError:
+                pass  # 只捕获 OSError：子进程内编程错误不静默吞
+        return url
+
+    def _resolve_path(self, raw: str, sandbox: bool) -> str:
+        """解析声明路径为规范绝对路径（沙盒校验 + 相对重定位共用逻辑）。"""
+        if self.output_root is not None and sandbox:
+            p = Path(raw)
+            roots = self.output_root if isinstance(self.output_root, (list, tuple)) else [self.output_root]
+            if not p.is_absolute():
+                # 相对路径按**第一个**根重定位（兼容语义）
+                p = roots[0] / p
+            # REQ-10: Path sandbox — reject paths outside every output_root
+            resolved_path = Path(os.path.abspath(str(p)))
+            try:
+                resolved_path = resolved_path.resolve()
+            except (OSError, RuntimeError):
+                logger.debug(f"Could not resolve output path '{raw}', using abspath fallback.")
+            if not any(resolved_path.is_relative_to(r) for r in roots):
+                raise ValueError(
+                    f"Output path '{raw}' resolves outside output_root "
+                    f"{roots!r}"
+                )
+            return str(resolved_path)
+        # Always resolve parent directory if possible, fall back to absolute
+        p = Path(raw)
+        try:
+            if p.parent.exists():
+                return str(p.resolve())
+            return os.path.abspath(str(p))  # 折叠 ..，存储规范路径
+        except (OSError, RuntimeError):
+            return os.path.abspath(str(p))
+
+    def is_completed(self, uid: str) -> bool:
+        """Check if a job is already in wall 快照（已成功完成过的内容）。
+
+        Snapshot semantics（文档对齐）：TaskContext 在**每个 job 派发时**
+        构造，快照 = 该 job 派发时刻的 wall 集合——同一 run 内后派发的 job 能
+        看到先前完成的任务（README 承诺语义）。不反映构造之后其他并发
+        in-flight job 的完成。
+        """
+        return uid in self._wall_keys
+
+    def is_failed(self, uid: str) -> bool:
+        """Check if a job has permanently failed (in the DLQ).
+
+        Snapshot semantics（文档对齐）：同 is_completed——派发时刻快照，
+        不反映构造之后其他并发 in-flight job 的失败。
+        """
+        return uid in self._failed_keys
+
+    def attempted_uids(self) -> frozenset:
+        """返回 wall∪failed 已见 uid 的只读快照。
+
+        discovery 的 on_missing（``wrappers/discovery.py``）需要「可迭代的已见
+        集合」——本方法是唯一公开入口，不暴露 ``_wall_keys`` 等私有字段
+        （跨模块私有耦合，字段名变更会静默失效）。返回**快照**（frozenset）
+        而非活引用：调用方改动
+        返回值不影响框架内部集合（身份判定基础不被业务 mutate）。
+        快照语义同 ``is_completed``/``is_failed``——构造时刻的 wall/failed 并集。
+        """
+        return frozenset(self._wall_keys) | frozenset(self._failed_keys)
+
+    def get_cursor(self, key: str) -> Optional[str]:
+        """Retrieve the value of a high-watermark cursor."""
+        return self._cursors.get(key)
+
+    def set_cursor(self, key: str, value: Optional[str]) -> None:
+        """Update a cursor. It will be committed atomically when the job succeeds.
+
+        Both key and value must be strings. Pass ``None`` as value to **delete**
+        the cursor（与后端 None-删除语义对齐）。
+        """
+        if not isinstance(key, str):
+            raise TypeError(f"cursor key must be str, got {type(key).__name__}")
+        if value is not None and not isinstance(value, str):
+            raise TypeError(f"cursor value must be str, got {type(value).__name__}")
+        self.cursor_updates[key] = value
+        if value is None:
+            self._cursors.pop(key, None)
+        else:
+            self._cursors[key] = value
+
+    def suspend_resource(self, resource_name: str, seconds: float) -> None:
+        """Request global suspension of a resource (e.g., for 429 rate limits).
+
+        API 边界即校验（与 set_cursor 的严格校验对称）——非数值/非有限/
+        非正值在入口拒绝，而非延迟到 Resource._sanitize_suspend 静默忽略，
+        避免调用方误以为 suspend 已生效。
+
+        信号立即追加到 ``{ipc_dir}/{uid}.signals.jsonl``
+        （落盘 flush），即使 handler 随后崩溃/超时，限流信息也不丢失。
+        同时保留 resource_suspensions list 供正常完成路径的结果文件携带
+        （去重由 suspend 的 max 语义保证）。
+        """
+        if not isinstance(resource_name, str) or not resource_name:
+            raise TypeError(f"resource_name must be a non-empty str, got {resource_name!r}")
+        # 未注册资源名 fail-loud——typo（如 "api_v1" vs
+        # "api"）会静默追加，消费端 apply_result/apply_pending_signals
+        # 按 `in resources` 静默跳过 → 用户以为限流已生效、管线继续猛打
+        # 目标 API。生产派发路径携带注册集快照，入口即拒绝。
+        if self._resource_names is not None and resource_name not in self._resource_names:
+            raise ValueError(
+                f"Unknown resource {resource_name!r} (registered: "
+                f"{sorted(self._resource_names)}); suspend request ignored"
+            )
+        if not isinstance(seconds, (int, float)) or isinstance(seconds, bool):
+            raise TypeError(f"seconds must be a number, got {type(seconds).__name__} ({seconds!r})")
+        if not math.isfinite(seconds) or seconds <= 0:
+            raise ValueError(f"seconds must be finite and > 0, got {seconds!r}")
+        self.resource_suspensions.append((resource_name, seconds))
+        if self.ipc_dir is not None:
+            try:
+                append_signal(self.ipc_dir, self.job.uid, resource_name, seconds)
+            except OSError:
+                pass  # 文件写失败静默丢弃，不影响 handler 执行
+        logger.info(f"Task requested global suspension of resource '{resource_name}' for {seconds}s.")

tasklite/models/job.py

@@ -0,0 +1,304 @@
+"""Job data model for tasklite."""
+
+from dataclasses import dataclass
+import math
+from typing import Any, Dict, List, Optional
+
+from ..utils.lockfile import safe_uid_filename
+from ..utils.validation import validate_resource_amounts
+
+# uid 派生的 IPC 文件名（锁 / result / signals / outputs）
+# 无截断——job_id/task_type 超长时文件名超 255 字节（EXT4 单文件名字节
+# 上限）→ os.open ENAMETOOLONG → 派发侧异常未分类 → requeue + 退避/崩溃
+# 重启 → livelock（job 永远无法执行且不进 DLQ）。入口按 safe_uid_filename
+# 实际字节数（含转义膨胀）拒绝，fail-fast。
+# 255 - 56 = 199：56 为最坏结果文件后缀 ``.{32-hex run_id}.{seq}.result.json``。
+_MAX_SAFE_UID_BYTES = 199
+
+
+@dataclass
+class JobRuntimeState:
+    """Job 运行期内部边带状态（强类型结构化存储，替代散装字典）。"""
+
+    backoff_until: Optional[float] = None
+    backoff_wall_deadline: Optional[float] = None
+    commit_failures: int = 0
+    dispatch_failures: int = 0
+    last_retry_error: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {}
+        if self.backoff_until is not None:
+            d["_backoff_until"] = self.backoff_until
+        if self.backoff_wall_deadline is not None:
+            d["_backoff_wall_deadline"] = self.backoff_wall_deadline
+        if self.commit_failures:
+            d["_commit_failures"] = self.commit_failures
+        if self.dispatch_failures:
+            d["_dispatch_failures"] = self.dispatch_failures
+        if self.last_retry_error:
+            d["_last_retry_error"] = self.last_retry_error
+        return d
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "JobRuntimeState":
+        if not isinstance(data, dict):
+            return cls()
+        return cls(
+            backoff_until=data.get("_backoff_until") or data.get("backoff_until"),
+            backoff_wall_deadline=data.get("_backoff_wall_deadline") or data.get("backoff_wall_deadline"),
+            commit_failures=int(data.get("_commit_failures") or data.get("commit_failures") or 0),
+            dispatch_failures=int(data.get("_dispatch_failures") or data.get("dispatch_failures") or 0),
+            last_retry_error=str(data.get("_last_retry_error") or data.get("last_retry_error") or ""),
+        )
+
+
+class Job:
+    """Represents a discrete unit of work in the pipeline."""
+
+    def __init__(
+        self,
+        task_type: str,
+        job_id: str,
+        payload: Optional[Dict[str, Any]] = None,
+        resources: Optional[Dict[str, float]] = None,
+        retries: int = 0,
+        max_retries: int = 3,
+        depends_on: Optional[List[str]] = None,
+        timeout: int = 3600,
+        backoff_base: float = 2.0,
+        backoff_max: float = 300.0,
+        timeout_is_transient: bool = False,
+        rerun: Optional[str] = None,
+        runtime: Optional[Dict[str, Any]] = None,
+    ):
+        """Initialize a Job.
+
+        Args:
+            task_type: Task type name (must match a registered handler). Must not
+                contain ``::`` (used as uid separator).
+            job_id: Unique job identifier within the task type. Must not contain ``::``.
+            payload: Business data dict passed to handler. Must be JSON-serializable.
+            resources: Resource amounts to acquire (overrides handler defaults).
+            retries: Current retry count (internal, managed by framework).
+            max_retries: Max retry attempts before DLQ. Must be >= 0.
+            depends_on: List of upstream job UIDs (``task_type::job_id``). Failed
+                parents cascade-block this job.
+            timeout: Execution timeout in seconds. Must be > 0.
+            backoff_base: Exponential backoff base in seconds. Must be finite and >= 0.
+            backoff_max: Backoff cap in seconds. Must be finite and >= 0.
+            timeout_is_transient: 超时是否视为瞬态失败（默认 False 保持
+                保守语义）。True 时看门狗 TIMEOUT 按 retry 处理（指数退避重试，
+                达 max_retries 才 DLQ），而非直接 Unknown → DLQ。适用于设计上
+                可能长跑的 job 类型（如 discovery 的整页扫描）——「超时」的
+                语义是「没跑完」，不等于「确定性失败」。
+            rerun: 跨会话重跑策略——「成功进 wall 是否算
+                数」由它决定（**不改变 job_id 派生**，身份仍是 uid）：
+                - None（默认，未指定哨兵）：**未指定**——discovery
+                  任务注入 ``set_discovery_rerun`` 登记的默认策略；普通任务
+                  按 "never" 处理。与显式 "never" 的区别：显式值一律尊重，
+                  不再被 discovery 默认覆盖（保持 enqueue 与 spawn 行为一致）。
+                - "never"：wall/failed 命中即跳过（现状语义）；
+                - "on_failure"：wall 命中跳过，failed 命中**重跑**
+                  （网络误失败可自愈；成功即自动清 DLQ 残行）；
+                - "every_run"：wall/failed 命中都**重跑**（成功 REPLACE
+                  wall 行、run_count+1）——discovery 扫描/orchestrator；
+                - "on_input_change"：wall 命中比对输入指纹，failed 命中重跑。
+                策略只作用于「wall/failed 拦截点」；queue/in-flight 永远
+                算数（同一轮内不重复派发/并发双跑）。随 job_dict 持久化。
+        """
+        self.task_type = task_type
+        # 非 str task_type：下方 "::" in task_type 会抛原始 TypeError，且与 job_id 的
+        # str 归一化不对称，入口显式拒绝。
+        if not isinstance(task_type, str):
+            raise TypeError(
+                f"task_type must be a str, got {type(task_type).__name__} ({task_type!r})"
+            )
+        # job_id 拒绝非 str——str 强转会使数值与字符串
+        # 字面量静默碰撞（Job("t",1.0).uid == Job("t","1.0").uid == "t::1.0"），
+        # 混合数值/字符串 job_id 的管线静默合并不同任务（wall 去重吞掉后者）。
+        # 入口显式拒绝，与 task_type 对称。
+        if not isinstance(job_id, str):
+            raise TypeError(
+                f"job_id must be a str, got {type(job_id).__name__} ({job_id!r})"
+            )
+        self.job_id = job_id
+        # 校验 task_type/job_id 非空且不含 '::'，避免 uid 的 'task::id' 分隔符碰撞
+        if not task_type:
+            raise ValueError(f"task_type must be a non-empty str, got {task_type!r}")
+        if not self.job_id:
+            raise ValueError(f"job_id must be a non-empty str, got {job_id!r}")
+        if "::" in task_type:
+            raise ValueError(f"task_type must not contain '::', got {task_type!r}")
+        if "::" in self.job_id:
+            raise ValueError(f"job_id must not contain '::', got {job_id!r}")
+        # uid 派生 IPC 文件名超 255 字节 → ENAMETOOLONG livelock，入口拒绝。
+        if len(safe_uid_filename(f"{task_type}::{job_id}").encode("utf-8")) > _MAX_SAFE_UID_BYTES:
+            raise ValueError(
+                f"task_type+job_id too long: uid-derived IPC filename would exceed "
+                f"filesystem name limit ({_MAX_SAFE_UID_BYTES} bytes max); got "
+                f"{task_type!r}::{job_id!r} — shorten to avoid ENAMETOOLONG livelock"
+            )
+        # 非 dict payload：to_dict/enqueue 预检均放行、直到子进程才崩，入口拒绝。
+        if payload is not None and not isinstance(payload, dict):
+            raise TypeError(
+                f"payload must be a dict or None, got {type(payload).__name__} ({payload!r})"
+            )
+        self.payload = dict(payload) if payload else {}
+        # resources 必须为 dict——str 等可迭代类型在下方
+        # ``for res_name, amount in self.resources.items`` 抛原始
+        # AttributeError（不可读），None 被 or {} 兜底但其他类型漏过。
+        # 与 payload 的 dict 校验对称，入口显式拒绝。
+        if resources is not None and not isinstance(resources, dict):
+            raise TypeError(
+                f"resources must be a dict or None, got {type(resources).__name__} ({resources!r})"
+            )
+        self.resources = resources or {}
+        # 数值校验单点化（与 pipeline.register_handler 的默认资源
+        # 校验共用 utils.validation.validate_resource_amounts）——负值/NaN/Inf
+        # 会在调度器 acquire 时抛 ValueError（若抛在 try 之外，部分资源
+        # 永久泄漏），且 NaN 会毒化 CapacityResource 的 used 账目导致 livelock。
+        # 构造时即拒绝（bool 是 int 子类，isinstance(True,(int,float)) 为
+        # True 会放行，故显式拒绝 bool）。
+        validate_resource_amounts(self.resources, "resources")
+        self.retries = retries
+        # retries 必须为 int——字符串等脏数据会在 _complete_job 的
+        # `job.retries >= job.max_retries` 比较处抛 TypeError，导致无限
+        # 崩溃重启循环（job 从磁盘恢复 → 再跑再崩，且无 DLQ 兜底）。
+        if not isinstance(retries, int) or isinstance(retries, bool):
+            raise TypeError(f"retries must be an int, got {type(retries).__name__} ({retries!r})")
+        # retries 下界校验：防止负数导致退避比较异常与无延迟重试，入口即拒绝。
+        if retries < 0:
+            raise ValueError(f"retries must be >= 0, got {retries}")
+        # max_retries 的 isinstance 检查必须在 < 0 之前——字符串脏数据
+        # 会先触发 "abc" < 0 的原始 TypeError，友好报错失效。
+        if not isinstance(max_retries, int) or isinstance(max_retries, bool):
+            raise TypeError(
+                f"max_retries must be an int, got {type(max_retries).__name__} ({max_retries!r})"
+            )
+        if max_retries < 0:
+            raise ValueError(f"max_retries must be >= 0, got {max_retries}")
+        self.max_retries = max_retries
+        # 先校验外层类型再迭代——str 可迭代出 str，若直接 all(isinstance) 检查
+        # 会把 "parent::id" 静默肢解为字符列表，作业以 DEPENDENCY_DEADLOCK 死亡。
+        if depends_on is not None and not isinstance(depends_on, (list, tuple)):
+            raise TypeError(
+                f"depends_on must be a list of strings, got {type(depends_on).__name__}"
+            )
+        self.depends_on = list(depends_on) if depends_on is not None else []
+        if not all(isinstance(d, str) for d in self.depends_on):
+            raise TypeError(
+                f"depends_on must contain only strings, got {self.depends_on!r}"
+            )
+        self.timeout = timeout
+        # timeout 必须为有限正数——NaN 使 timeout <= 0 校验恒
+        # False 而漏过（NaN <= 0 为 False），deadline = monotonic + NaN = NaN，
+        # now > NaN 恒 False → 看门狗永不触发，挂死 job 永不 kill。
+        # bool 是 int 子类，同样拒绝（timeout=True 被接受为 1 秒）。
+        if not isinstance(timeout, (int, float)) or isinstance(timeout, bool):
+            raise TypeError(
+                f"timeout must be a number, got {type(timeout).__name__} ({timeout!r})"
+            )
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError(f"timeout must be finite and > 0, got {timeout}")
+        # backoff_base/backoff_max 与 timeout 的校验对称——
+        # 仅 math.isfinite + < 0 不够：字符串 "2.0" 抛原始 TypeError
+        # （math.isfinite 不接收 str），True 被接受为 1.0（bool 是 int 子类）。
+        if not isinstance(backoff_base, (int, float)) or isinstance(backoff_base, bool):
+            raise TypeError(
+                f"backoff_base must be a number, got {type(backoff_base).__name__} ({backoff_base!r})"
+            )
+        if not math.isfinite(backoff_base) or backoff_base < 0:
+            raise ValueError(
+                f"backoff_base must be finite and non-negative, got {backoff_base}"
+            )
+        if not isinstance(backoff_max, (int, float)) or isinstance(backoff_max, bool):
+            raise TypeError(
+                f"backoff_max must be a number, got {type(backoff_max).__name__} ({backoff_max!r})"
+            )
+        if not math.isfinite(backoff_max) or backoff_max < 0:
+            raise ValueError(
+                f"backoff_max must be finite and non-negative, got {backoff_max}"
+            )
+        self.backoff_base = backoff_base
+        self.backoff_max = backoff_max
+        # 超时归类可配置。bool 类型校验——非 bool 值（如字符串）在
+        # executor 的 ``handle.job.timeout_is_transient`` 判断时被当作真值，
+        # 静默改变归类语义，入口拒绝。
+        if not isinstance(timeout_is_transient, bool):
+            raise TypeError(
+                f"timeout_is_transient must be a bool, got "
+                f"{type(timeout_is_transient).__name__} ({timeout_is_transient!r})"
+            )
+        self.timeout_is_transient = timeout_is_transient
+        # rerun 策略入口校验（fail-loud）——非法值会被静默当 "never" 处理。
+        # None 是「未指定」哨兵（可被 discovery 默认注入），
+        # 显式字符串一律尊重；仅拒绝未知字符串值。
+        if rerun is not None and rerun not in (
+            "never", "on_failure", "every_run", "on_input_change",
+        ):
+            raise ValueError(
+                f"rerun must be None (unspecified) or one of "
+                f"'never'/'on_failure'/'every_run'/'on_input_change', got {rerun!r}"
+            )
+        self.rerun = rerun
+        # 运行时边带状态（退避截止/3-strike 计数/最近重试错误）收敛到
+        # `runtime` 单一命名空间，随 job_dict 落盘持久化——序列化只此
+        # 一处，新增状态不会因散装下划线键漏写 to_dict 而丢失。
+        self.runtime = dict(runtime) if runtime else {}
+
+    def to_dict(self) -> dict:
+        """Serialize job to dictionary.
+
+        Returns shallow copies of payload/resources/depends_on to prevent
+        external mutation of internal state. ``runtime`` 子 dict 显式保留
+        ——边带状态集中序列化，不散装丢失。
+        """
+        return {
+            "task_type": self.task_type,
+            "job_id": self.job_id,
+            "payload": dict(self.payload),
+            "resources": dict(self.resources),
+            "retries": self.retries,
+            "max_retries": self.max_retries,
+            "depends_on": list(self.depends_on),
+            "timeout": self.timeout,
+            "backoff_base": self.backoff_base,
+            "backoff_max": self.backoff_max,
+            "timeout_is_transient": self.timeout_is_transient,
+            "rerun": self.rerun,
+            "runtime": dict(self.runtime),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Job":
+        """Deserialize job from dictionary."""
+        return cls(
+            data["task_type"],
+            data["job_id"],
+            data.get("payload", {}),
+            data.get("resources", {}),
+            data.get("retries", 0),
+            data.get("max_retries", 3),
+            data.get("depends_on", []),
+            data.get("timeout", 3600),
+            data.get("backoff_base", 2.0),
+            data.get("backoff_max", 300.0),
+            data.get("timeout_is_transient", False),
+            data.get("rerun"), # 缺键/None = 未指定哨兵
+            # runtime 子 dict 显式保留——边带状态只存这一处。
+            data.get("runtime", {}),
+        )
+
+    @property
+    def uid(self) -> str:
+        """Return unique identifier for this job."""
+        return f"{self.task_type}::{self.job_id}"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Job):
+            return NotImplemented
+        return self.uid == other.uid
+
+    def __hash__(self) -> int:
+        return hash(self.uid)