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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasklite-engine
-Version: 1.2.0
+Version: 1.2.1
 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

{tasklite_engine-1.2.0 → tasklite_engine-1.2.1}/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.1"
 
 
 # Public API - Core

{tasklite_engine-1.2.0 → tasklite_engine-1.2.1}/tasklite/engine/inflight.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 from collections.abc import MutableMapping
 from dataclasses import dataclass, field
 from typing import (
-    Any, Dict, Iterator, List, Mapping, Optional, Tuple, Union, TYPE_CHECKING
+    Any, Dict, FrozenSet, Iterator, List, Mapping, Optional, Tuple, Union, TYPE_CHECKING
 )
 
 if TYPE_CHECKING:
@@ -144,7 +144,11 @@ class InFlightTracker(MutableMapping[str, InFlightJob]):
         """语义化结算接缝：注销在途任务并同步内存状态（单一真相源出口）。"""
         entry = self._entries.pop(uid, None)
         if state is not None and hasattr(state, "unregister_in_flight"):
-            state.unregister_in_flight(uid)
+            # 三态提交内部已注销 in-flight（retry 分支注销后立即 requeue 并
+            # 重建 rerun 豁免）；此处仅在 uid 仍在途索引时才兜底转发注销，
+            # 防止二次注销误删刚重建的豁免（安全网语义不变）。
+            if uid in state.in_flight_uids:
+                state.unregister_in_flight(uid)
         return entry
 
     def unregister(

{tasklite_engine-1.2.0 → tasklite_engine-1.2.1}/tasklite/engine/scheduler.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 import logging
 import time
 from dataclasses import dataclass, field
-from typing import Dict, FrozenSet, List, Optional, Tuple, Union, TYPE_CHECKING
+from typing import Any, Dict, FrozenSet, List, Optional, Tuple, Union, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from .types import HandlerEntry

{tasklite_engine-1.2.0 → tasklite_engine-1.2.1}/tasklite/engine/store.py

@@ -139,10 +139,6 @@ class StateStore:
     def stats(self) -> Any:
         return self._stats
 
-    @property
-    def backend(self) -> AbstractStateBackend:
-        return self._backend
-
     def set_stats(self, stats: Any) -> None:
         self._stats = stats
 
@@ -255,18 +251,22 @@ class StateStore:
 
     @property
     def wall_uids(self) -> FrozenSet[str]:
-        """已成功作业 UID 集合快照。"""
-        return self._state.wall_uids
+        """已成功作业 UID 集合快照。
+
+        不变式：对外只交不可变快照——PipelineState 内部活索引绝不被
+        调用方持有引用（误改会静默破坏 wall 去重一致性）。
+        """
+        return frozenset(self._state.wall_uids)
 
     @property
     def failed_uids(self) -> FrozenSet[str]:
-        """已失败作业 UID 集合快照。"""
-        return self._state.failed_uids
+        """已失败作业 UID 集合快照（不可变契约同 wall_uids）。"""
+        return frozenset(self._state.failed_uids)
 
     @property
     def queue_uids(self) -> FrozenSet[str]:
-        """排队作业 UID 集合快照。"""
-        return self._state.queue_uids
+        """排队作业 UID 集合快照（不可变契约同 wall_uids）。"""
+        return frozenset(self._state.queue_uids)
 
     def pop_job(self, idx: int) -> dict:
         """弹出指定位置作业并同步 UID 索引。"""

{tasklite_engine-1.2.0 → tasklite_engine-1.2.1}/tasklite/models/state.py

@@ -311,6 +311,14 @@ class PipelineState:
 
     # 内部 ---------------------------------------------------------
 
+    def _rerun_exempt_uids_from_queue(self) -> set:
+        """从 queue 事实源直接取重跑豁免集合，不依赖派生缓存
+        ``_rerun_active_uids``（缓存被瞬态路径误删时断言不得误报）。"""
+        return {
+            uid_from_job_dict(j) for j in self._queue
+            if j.get("rerun") in ("every_run", "on_failure", "on_input_change")
+        }
+
     def _assert_uids_consistent(self) -> None:
         """DEBUG 不变式：_queue_uids 与 _queue 完全一致。"""
         recomputed = {uid_from_job_dict(j) for j in self._queue}
@@ -334,17 +342,18 @@ class PipelineState:
             f"uid in both queue and in_flight: {overlap!r} "
             f"(queue={self._queue_uids!r} in_flight={self._in_flight_uids!r})"
         )
+        exempt = self._rerun_active_uids | self._rerun_exempt_uids_from_queue()
         done_overlap = (set(self._wall) | set(self._failed)) & self._in_flight_uids
-        assert not (done_overlap - self._rerun_active_uids), (
-            f"uid in wall/failed and in_flight: {done_overlap - self._rerun_active_uids!r}"
+        assert not (done_overlap - exempt), (
+            f"uid in wall/failed and in_flight: {done_overlap - exempt!r}"
         )
         wall_failed = set(self._wall) & set(self._failed)
         assert not wall_failed, (
             f"uid in both wall and failed: {wall_failed!r}"
         )
         done_queue = (set(self._wall) | set(self._failed)) & self._queue_uids
-        assert not (done_queue - self._rerun_active_uids), (
-            f"uid in wall/failed and queue: {done_queue - self._rerun_active_uids!r}"
+        assert not (done_queue - exempt), (
+            f"uid in wall/failed and queue: {done_queue - exempt!r}"
         )
         self._assert_uids_consistent()
         self._assert_terminal_uids_consistent()

{tasklite_engine-1.2.0 → tasklite_engine-1.2.1}/tasklite/utils/injective.py

@@ -5,7 +5,12 @@
    任何非单射净化（如丢弃字符、简单多对一替换）在拼装 UID 或文件路径时会导致碰撞，
    进而导致 wall 去重静默吞任务或锁竞争错乱。
 2. 转义符优先转义：% 必须首先转义为 %25，因此输出中的 % 唯一且确定地引导一个 %XX 序列。
-3. 超长截断单射兜底：截断时附加 SHA-256 摘要（8 字符），保证同前缀不同尾部的长字符串不碰撞。
+   推论：含孤立 %（% 后不跟两位大写 hex）的串不在像集中——哨兵与截断标记均利用此性质
+   选取「任何输入都映射不出」的形态。
+3. 超长截断兜底：截断输出 = 前缀 + "%_" + 64 位 SHA-256 指纹。标记 "%_" 使截断输出
+   落在转义像集之外，与「转义后 ≤ max_len 直通域」结构性不相交（无定点自碰撞）；
+   同前缀长输入之间依赖 64 位指纹概率防撞（生日界约 2^32 条）。有界输出对无限定义域
+   的全域单射数学上不可能，此处为工程实用界而非数学保证。
 """
 from __future__ import annotations
 
@@ -21,6 +26,23 @@ DEFAULT_FORBIDDEN = "/\\:%"
 # 内容 ID 允许字符集（仅字母、数字、短横线、下划线、点）
 CONTENT_ID_ALLOWED = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_."
 
+# 空值哨兵：含孤立 %（% 后不跟两位大写 hex）。不变式：单射转义的像集中 % 只以
+# %XX 成对出现，故任何非空输入都不可能映射出该形态——空值与真实输入（含字面
+# "untitled"）零碰撞。哨兵为固定最短安全形态，不随 max_len 收缩。
+EMPTY_SENTINEL = "%untitled"
+
+# 截断指纹宽度：64 位 hex。同前缀长输入之间为概率防撞，生日界约 2^32 条（50% 碰撞
+# 概率所需的同前缀长 ID 量级），工程上视为实用安全界而非数学保证。
+_TRUNC_DIGEST_HEX = 16
+
+# 截断标记：含孤立 %（_ 非 hex 位），处于转义像集之外。不变式：直通域输出继承
+# escape_injective 的「% 只以 %XX 成对出现」形态，故截断输出与直通域结构性不相交，
+# 杜绝「截断输出自身作为输入再次净化」时的定点自碰撞。
+_TRUNC_MARKER = "%_"
+
+# 截断形态的固定开销（标记 + 指纹），max_len 低于此值时截断无法在不破上限的前提下完成
+_TRUNC_FIXED_LEN = len(_TRUNC_MARKER) + _TRUNC_DIGEST_HEX
+
 # 文件系统危险字符映射（POSIX /、Windows \、NUL、glob *?[]、冒号 :）
 FS_ESCAPE_CHARS: Dict[str, str] = {
     "/": "%2F",
@@ -71,13 +93,20 @@ def sanitize_identifier(
     max_len: int = 120,
     forbidden: Union[str, Sequence[str], None] = DEFAULT_FORBIDDEN,
     allowed: Union[str, Sequence[str], None] = None,
-    fallback: str = "untitled",
+    fallback: str = EMPTY_SENTINEL,
 ) -> str:
-    """净化任意值为确定性、单射安全的标识符（如 job_id 或 content_id）。
-
-    - 空值返回 fallback（默认 "untitled"）；
-    - 禁止字符与不可打印字符可逆单射转义；
-    - 超长输入（转义后 > max_len）：截断 + 8 位 SHA-256 指纹后缀。
+    """净化任意值为确定性、单射安全的标识符（如 job_id 或 content_id）。单射契约分级：
+
+    - 空值（None/""）返回 fallback；默认哨兵 EMPTY_SENTINEL 处于单射转义像集之外，
+      任何非空输入都映射不出该值（零碰撞）。自定义 fallback 必须同样选用像集外
+      形态（含孤立 %），否则与字面输入的碰撞由调用方自负；哨兵形态固定，不随
+      max_len 收缩；
+    - 转义后 ≤ max_len 的输入：直通输出，全域单射（继承 escape_injective）；
+    - 转义后 > max_len 的输入：截断 + "%_" + 64 位 SHA-256 全文指纹。输出带像集外
+      标记，与直通域结构性不相交；同前缀长输入之间为概率防撞（生日界约 2^32 条
+      同前缀长 ID），非数学全域保证；
+    - 需截断而 max_len < _TRUNC_FIXED_LEN 时抛 ValueError（截断形态无法压入上限，
+      fail-loud）；直通输入对任意 max_len 均可用。
     """
     text = str(value) if value is not None else ""
     if not text:
@@ -85,29 +114,39 @@ def sanitize_identifier(
     escaped = escape_injective(text, forbidden=forbidden, allowed=allowed)
     if len(escaped) <= max_len:
         return escaped
-    digest = hashlib.sha256(text.encode("utf-8")).hexdigest()[:8]
-    base_limit = max(max_len - 9, 0)
+    # 指纹覆盖全文（非截断前缀），同前缀不同尾部的长输入由此区分
+    digest = hashlib.sha256(text.encode("utf-8")).hexdigest()[:_TRUNC_DIGEST_HEX]
+    base_limit = max_len - _TRUNC_FIXED_LEN
+    if base_limit < 0:
+        raise ValueError(
+            f"max_len={max_len} 不足以容纳截断指纹形态"
+            f"（标记与指纹固定占 {_TRUNC_FIXED_LEN} 字符），拒绝静默突破长度上限"
+        )
     prefix = escaped[:base_limit]
     if prefix.endswith("%"):
         prefix = prefix[:-1]
     elif len(prefix) >= 2 and prefix[-2] == "%":
         prefix = prefix[:-2]
-    return f"{prefix}_{digest}"
+    return f"{prefix}{_TRUNC_MARKER}{digest}"
 
 
 def sanitize_job_component(value: Any, *, max_len: int = 120) -> str:
-    r"""把任意字符串**转义**净化为可作 job_id 成分的串（单射，不删字符）。
+    r"""把任意字符串**转义**净化为可作 job_id 成分的串（不删字符）。
 
-    单射转义与长度截断统一委托底层 sanitize_identifier。
+    单射契约分级见 sanitize_identifier：直通域全域单射；截断输出带像集外标记，
+    与直通域结构性不相交，截断域内为 64 位指纹概率防撞。
     """
     return sanitize_identifier(value, max_len=max_len)
 
 
 def sanitize_content_id(content_id: str, *, max_len: int = 120) -> str:
-    """按严密 allowlist 净化 content_id（如用于 discovery 子任务派发）。"""
+    """按严密 allowlist 净化 content_id（如用于 discovery 子任务派发）。
+
+    空值返回像集外哨兵；单射契约分级与截断行为同 sanitize_identifier。
+    """
     text = str(content_id)
     if not text:
-        return "untitled"
+        return EMPTY_SENTINEL
     # 若全部是 clean 字符且未超长，直接返回
     if all(c in CONTENT_ID_ALLOWED for c in text) and len(text) <= max_len:
         return text

{tasklite_engine-1.2.0 → tasklite_engine-1.2.1}/tasklite_engine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasklite-engine
-Version: 1.2.0
+Version: 1.2.1
 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