DeepSWE 式长程软件工程任务

Terra Draw 的 snapping 选项已经支持吸附到坐标、线、要素、角度（toDegree）和自定义位置。在做平面图编辑器时，我一直用 toCustom 手写网格，而矩形模式根本无法吸附，所以我希望有一个声明式的网格吸附策略。

请在 terra-draw 中紧挨着 SnapToDegree 导出一个 SnapToGrid 类型：{ size: number; units?: "degrees" | "meters"; origin?: Position }。其中 units 默认为 "degrees"，origin 默认为 [0, 0]（lng/lat）。在 OneDimensionalSnapping（因而也包括 Snapping）中添加 toGrid?: SnapToGrid。TerraDrawPointMode、TerraDrawMarkerMode、TerraDrawLineStringMode、TerraDrawPolyLineMode 和 TerraDrawPolygonMode 都要遵循该选项，无论它是在构造函数中设置，还是通过 draw.updateModeOptions(mode, { snapping }) 设置。规则如下：

• 度（degrees）：lng 吸附到 origin[0] + Math.round((lng - origin[0]) / size) * size，lat 同理使用 origin[1]（恰好处于一半时向 +∞ 取整）。
• 米（meters）：将位置和 origin 投影为球面 Web Mercator 的 x/y（EPSG:3857，R = 6378137，与库中 web-mercator 转换的做法一致）。以 origin 的 x/y 为基准，用同一公式分别吸附 x 和 y，再转换回 lng/lat。
• 吸附后的位置随后按 adapter 的坐标精度取整。
• 如果吸附后的 lng 超出 [-180, 180] 或 lat 超出 [-90, 90]，则该次指针事件不应用网格。
• 无效配置会静默禁用网格（不报错）：size 不是大于 0 的有限数、units 取值未知，或 origin 不是两个有限数。
• 最低优先级：只有当其他已启用的策略（toCustom、toFeature、toCoordinate、toLine、toDegree）都没有为该事件给出坐标时，才使用网格。

在 point 和 marker 模式中，左键点击创建的点，以及在 editable: true 下被拖动的点，都落在吸附后的位置。在 linestring、polyline 和 polygon 模式中，每个已提交的顶点（包括第一次点击）以及鼠标移动时的临时顶点都使用吸附后的位置。鼠标移动时若网格生效，会在该处显示一个 snappingPoint: true 的引导 Point，其管理方式与其他策略的吸附点相同。闭合/结束检测仍使用指针的屏幕位置。如果一次点击吸附到上一个已提交的顶点上，这次点击会被忽略，与目前对相同坐标的处理一致。

TerraDrawRectangleMode 新增 snapping?: { toGrid?: SnapToGrid } 选项（构造函数和 updateModeOptions 均可设置）。启用后，在 click-move 和 click-drag 两种交互中，起始角和对角都会被吸附（对角在每次指针更新时以及结束时都会吸附），使完成后矩形的四个角都位于网格上。不会创建 snappingPoint 引导要素。

在 TerraDrawSelectMode 中，flags[mode].feature.coordinates.snappable 可以是包含 toGrid 的 Snapping 对象。当 coordinates.draggable: true 时，拖动所选要素的某个顶点会把它放到吸附后的位置（若是多边形的首/尾顶点，则两个位置都如此）。只有顶点拖动会吸附；整体拖动要素、中点（midpoints）、调整大小（resize）、旋转（rotate）和缩放（scale）都不吸附。

updateModeOptions 必须能在运行时启用、修改或移除 toGrid，并像现在一样整体替换 snapping 对象。没有 toGrid（或矩形模式没有 snapping 选项）时，每个模式的行为都必须与之前完全一致，所有新增的类型字段都保持可选。

重要：请从 main 新建一个分支来完成这项工作，完成后提交所有改动。

diff --git a/packages/terra-draw/src/modes/grid-snapping.behavior.ts b/packages/terra-draw/src/modes/grid-snapping.behavior.ts
new file mode 100644
--- /dev/null
+++ b/packages/terra-draw/src/modes/grid-snapping.behavior.ts
@@ -0,0 +1,142 @@
+import { Position } from "geojson";
+import { SnapToGrid, TerraDrawMouseEvent } from "../common";
+import { isNonNullObject } from "../common/checks";
+import {
+	validLatitude,
+	validLongitude,
+} from "../geometry/boolean/is-valid-coordinate";
+import { limitPrecision } from "../geometry/limit-decimal-precision";
+import {
+	lngLatToWebMercatorXY,
+	webMercatorXYToLngLat,
+} from "../geometry/project/web-mercator";
+import { BehaviorConfig, TerraDrawModeBehavior } from "./base.behavior";
+
+type GridUnits = NonNullable<SnapToGrid["units"]>;
+
+type ValidGrid = {
+	size: number;
+	units: GridUnits;
+	origin: [number, number];
+};
+
+const DEFAULT_UNITS: GridUnits = "degrees";
+
+const isFiniteNumber = (value: unknown): value is number =>
+	typeof value === "number" && Number.isFinite(value);
+
+/**
+ * Snaps positions to a regular grid (lattice), either in degrees of
+ * longitude/latitude or in meters on the spherical Web Mercator plane.
+ */
+export class GridSnappingBehavior extends TerraDrawModeBehavior {
+	constructor(readonly config: BehaviorConfig) {
+		super(config);
+	}
+
+	/**
+	 * Returns the grid position nearest to the event, rounded to the coordinate
+	 * precision. Returns undefined if the grid options are invalid, or if the
+	 * snapped position falls outside of valid longitude/latitude bounds, in which
+	 * case the grid does not apply to the event.
+	 */
+	public getSnappableCoordinate(
+		event: Pick<TerraDrawMouseEvent, "lng" | "lat">,
+		options: SnapToGrid | undefined,
+	): Position | undefined {
+		const grid = this.getValidGrid(options);
+
+		if (!grid) {
+			return undefined;
+		}
+
+		const [snappedLng, snappedLat] =
+			grid.units === "meters"
+				? this.snapMeters(event, grid)
+				: this.snapDegrees(event, grid);
+
+		const lng = this.limitPrecision(snappedLng);
+		const lat = this.limitPrecision(snappedLat);
+
+		if (!validLongitude(lng) || !validLatitude(lat)) {
+			return undefined;
+		}
+
+		return [lng, lat];
+	}
+
+	private snapDegrees(
+		{ lng, lat }: Pick<TerraDrawMouseEvent, "lng" | "lat">,
+		{ size, origin }: ValidGrid,
+	): Position {
+		return [
+			this.snapValue(lng, origin[0], size),
+			this.snapValue(lat, origin[1], size),
+		];
+	}
+
+	private snapMeters(
+		{ lng, lat }: Pick<TerraDrawMouseEvent, "lng" | "lat">,
+		{ size, origin }: ValidGrid,
+	): Position {
+		const { x, y } = lngLatToWebMercatorXY(lng, lat);
+		const { x: originX, y: originY } = lngLatToWebMercatorXY(
+			origin[0],
+			origin[1],
+		);
+
+		const snapped = webMercatorXYToLngLat(
+			this.snapValue(x, originX, size),
+			this.snapValue(y, originY, size),
+		);
+
+		return [snapped.lng, snapped.lat];
+	}
+
+	/**
+	 * Snaps a single value to the nearest grid line. Math.round means
+	 * that exact halves round towards +infinity.
+	 */
+	private snapValue(value: number, origin: number, size: number) {
+		return origin + Math.round((value - origin) / size) * size;
+	}
+
+	private limitPrecision(value: number) {
+		const limited = limitPrecision(value, this.coordinatePrecision);
+
+		// Normalise negative zero, which can result from rounding
+		// tiny negative values, so that coordinates are always [0, 0]
+		return limited === 0 ? 0 : limited;
+	}
+
+	/**
+	 * Validates the grid options, applying defaults. Invalid options
+	 * return undefined which silently disables grid snapping.
+	 */
+	private getValidGrid(options: unknown): ValidGrid | undefined {
+		if (!isNonNullObject(options)) {
+			return undefined;
+		}
+
+		const { size, units = DEFAULT_UNITS, origin = [0, 0] } = options;
+
+		if (!isFiniteNumber(size) || size <= 0) {
+			return undefined;
+		}
…… 其余 3,133 行从略（共改动 29 个文件）

rdflib 在各处都能处理 "x"@ar，但不支持 RDF 1.2 的基础方向（"x"@ar--rtl，rdf:dirLangString）：这类数据甚至无法加载。请端到端地加上这项支持。

Literal 新增第五个参数 direction=None 和只读属性 .direction；Literal('x', lang='ar', direction='rtl') 的 .language 为 'ar'，.datatype 为 None。

解析器 nt/ntriples/nt11、nquads、turtle/ttl、trig 和 n3 都要接受这种语法（包括带子标签的 @en-US--ltr）。它可以跟在 Turtle/TriG 的每一种字符串形式之后，也可以跟在 N3 的双引号字符串形式之后。序列化器 nt、nt11、nquads、turtle、longturtle、trig 和 n3 要能写出它（N-Triples 行：<http://e/s> <http://e/p> "x"@ar--rtl .），并能往返（round-trip）。SPARQL 在任何可以出现字面量的位置都要接受它，适用于 Graph.query / Graph.update 以及 prepareQuery / prepareUpdate。

• direction 只能是 None、'ltr' 或 'rtl'（否则抛出 ValueError，'' 也不例外）；有方向但没有语言标签时抛出 TypeError。
• ==、哈希和 eq()（因而 SPARQL 的 =、!=、IN、sameTerm）都要区分 "x"@ar、"x"@ar--ltr 和 "x"@ar--rtl；一个 Graph 可以同时容纳这三者。
• repr() 为 rdflib.term.Literal('x', lang='ar', direction='rtl')；n3() 为 "x"@ar--rtl（传入 namespace_manager 或使用三引号时也是如此），并且 rdflib.util.from_n3 能把它解析回来。pickle、copy、deepcopy 和 Literal(lit) 都要保留方向。
• -- 之后只允许小写的 ltr / rtl。其他任何内容，或没有语言标签的 --rtl，都要抛出 rdflib.exceptions.ParserError（nt、nquads）或 rdflib.plugins.parsers.notation3.BadSyntax（turtle、trig、n3）。
• LANGDIR 返回 "ltr" / "rtl"，对其他字面量返回 ""，对 IRI/空白节点报错（与 LANG 相同）。hasLANG / hasLANGDIR 返回 xsd:boolean，当且仅当参数分别是带语言标签/带方向的字面量时为 true（从不报错）。STRLANGDIR("abc", "ar", "rtl") 返回 "abc"@ar--rtl；方向非法，或第一个参数带标签/带类型时报错。
• DATATYPE("x"@ar--rtl) 返回 rdf:dirLangString，形式为普通 URIRef（不要加入 rdflib.RDF）；LANG 只返回标签本身。
• UCASE、LCASE、SUBSTR、STRBEFORE、STRAFTER 和 REPLACE 在保留标签的地方同样保留方向。CONCAT 仅当所有参数的标签和方向都相同时才保留两者，否则两者都不保留。

Result.serialize 在 json 中于 "xml:lang" 旁加上 "its:dir": "rtl"，在 xml 中给 <literal> 加上命名空间为 http://www.w3.org/2005/11/its 的 dir 属性。Result.parse 能把这两者读回，并接受 tsv 单元格中的 "x"@ar--rtl；txt 输出 --rtl。Memory 和 BerkeleyDB 存储在重新打开后仍保留方向。

不带方向的字面量，其行为和序列化结果必须与现在完全一致；JSON-LD 继续丢弃 @direction。

重要：请从 main 新建一个分支进行开发，完成后提交所有改动。

diff --git a/rdflib/term.py b/rdflib/term.py
--- a/rdflib/term.py
+++ b/rdflib/term.py
@@ -110,6 +110,17 @@ def _is_valid_langtag(tag: str) -> bool:
     return bool(_lang_tag_regex.match(tag))
 
 
+# RDF 1.2 base directions of directional language-tagged strings, see
+# https://www.w3.org/TR/rdf12-concepts/#dfn-base-direction
+_VALID_DIRECTIONS = frozenset(("ltr", "rtl"))
+
+
+def _is_valid_direction(direction: Any) -> bool:
+    """Is `direction` a valid RDF 1.2 base direction (exactly `ltr` or `rtl`)?"""
+    # str() so that str subclasses (e.g. a Literal "rtl") are judged by value
+    return isinstance(direction, str) and str(direction) in _VALID_DIRECTIONS
+
+
 def _is_valid_unicode(value: Union[str, bytes]) -> bool:
     """
     Verify that the provided value can be converted into a Python
@@ -532,6 +543,24 @@ class Literal(Identifier):
 
     A literal is a language-tagged string if the third element is present. Lexical representations of language tags MAY be converted to lower case. The value space of language tags is always in lower case.
 
+    RDF 1.2 adds an optional fourth element to language-tagged strings, a
+    [base direction](https://www.w3.org/TR/rdf12-concepts/#dfn-base-direction)
+    which is either `ltr` or `rtl`. Such a *directional language-tagged
+    string* has the datatype `rdf:dirLangString`, it is written as
+    `"..."@ar--rtl` in N-Triples, Turtle, SPARQL etc. and is created with the
+    `direction` parameter:
+
+    ```python
+    >>> lit = Literal("hello", lang="ar", direction="rtl")
+    >>> lit.language, lit.direction, lit.datatype
+    ('ar', 'rtl', None)
+    >>> lit.n3()
+    '"hello"@ar--rtl'
+    >>> lit == Literal("hello", lang="ar")
+    False
+
+    ```
+
     ---
 
     For valid XSD datatypes, the lexical form is optionally normalized
@@ -631,7 +660,8 @@ class Literal(Identifier):
     # NOTE: _datatype should maybe be of type URIRef, and not optional.
     _datatype: Optional[URIRef]
     _ill_typed: Optional[bool]
-    __slots__ = ("_language", "_datatype", "_value", "_ill_typed")
+    _direction: Optional[str]
+    __slots__ = ("_language", "_datatype", "_value", "_ill_typed", "_direction")
 
     def __new__(
         cls,
@@ -639,8 +669,26 @@ class Literal(Identifier):
         lang: Optional[str] = None,
         datatype: Optional[str] = None,
         normalize: Optional[bool] = None,
+        direction: Optional[str] = None,
     ):
-        """Create a new Literal instance."""
+        """Create a new Literal instance.
+
+        Args:
+            lexical_or_value: The lexical form (a `str`), a Python value to
+                convert, or another `Literal` to copy.
+            lang: An optional language tag.
+            datatype: An optional datatype IRI, mutually exclusive with `lang`.
+            normalize: Whether to normalize the lexical form of recognized
+                datatypes, defaults to `rdflib.NORMALIZE_LITERALS`.
+            direction: An optional RDF 1.2 base direction, `"ltr"` or `"rtl"`;
+                only allowed together with a language tag.
+
+        Raises:
+            TypeError: If both `lang` and `datatype` are given, or if a
+                `direction` is given without a language tag.
+            ValueError: If `lang` is not a valid language tag or `direction`
+                is not `"ltr"` or `"rtl"`.
+        """
         if lang == "":
             lang = None  # no empty lang-tags in RDF
 
@@ -655,6 +703,25 @@ class Literal(Identifier):
         if lang is not None and not _is_valid_langtag(lang):
             raise ValueError(f"'{str(lang)}' is not a valid language tag!")
 
+        if direction is not None:
+            if not _is_valid_direction(direction):
+                raise ValueError(
+                    f"{direction!r} is not a valid base direction, "
+                    "it must be 'ltr' or 'rtl'"
+                )
+            direction = str(direction)
+            if datatype is not None or (
+                lang is None
+                and not (
+                    isinstance(lexical_or_value, Literal) and lexical_or_value.language
+                )
+            ):
+                raise TypeError(
+                    "A Literal can only have a base direction if it has a "
+                    "language tag (and no datatype), "
+                    "per https://www.w3.org/TR/rdf12-concepts/#section-Graph-Literal"
+                )
+
         if datatype is not None:
             datatype = URIRef(datatype)
 
@@ -664,6 +731,9 @@ class Literal(Identifier):
             # create from another Literal instance
 
             lang = lang or lexical_or_value.language
+            if direction is None and lang and datatype is None:
+                # keep the base direction of the copied (language-tagged) literal
+                direction = lexical_or_value.direction
             if datatype is not None:
                 # override datatype
                 value = _castLexicalToPython(lexical_or_value, datatype)
@@ -699,6 +769,7 @@ class Literal(Identifier):
                 lexical_or_value = _value
             if datatype is not None:
                 lang = None
+                direction = None
 
         if isinstance(lexical_or_value, bytes):
             lexical_or_value = lexical_or_value.decode("utf-8")
…… 其余 2,025 行从略（共改动 19 个文件）

XMLParser 目前要么保留命名空间前缀，要么将其去掉（removeNSPrefix）。因此一旦 XML 的生成方换用其他前缀，以 soap:Envelope 为键的代码就会失效。请新增一个需显式开启的解析器选项 resolveNamespaces（类型为 boolean | Record<string, string>，默认 false，并在 X2jOptions 中声明类型），用于跟踪 xmlns 作用域并按命名空间 URI 解析名称；未设置或为 false 时，行为保持完全不变。

• xmlns="U"（默认命名空间）和 xmlns:p="U"（前缀 p）作用于声明它的元素（名称、属性、结束标签）及其后代；内层声明覆盖外层声明，xmlns="" 取消默认命名空间，xml 始终绑定到 http://www.w3.org/XML/1998/namespace。自闭合元素、非成对（unpaired）元素或停止节点（stop node）元素上的声明只影响该元素本身。
• 无前缀的元素名属于当前作用域内的默认命名空间（如果有）；p:local（在第一个冒号处拆分）属于绑定到 p 的命名空间。无前缀的属性从不属于任何命名空间；带前缀的属性按与元素相同的方式解析。
• 命名规则（紧凑输出与 preserveOrder 输出相同）：无命名空间 → 本地名；命名空间为 U → 若选项对象将 U（自有键）映射到 alias，则为 alias:local（若 alias 为 "" 则为 local），否则对 XML 命名空间为 xml:local，否则为 {U}local；true 等同于 {}。
• xmlns / xmlns:* 声明不是属性：从不出现在输出中（@_ 键、attributesGroupName 分组、:@ 映射），也从不传给 ignoreAttributes 函数、transformAttributeName 或 attributeValueProcessor。但即使 ignoreAttributes 为 true 或本会将其过滤掉，这些声明依然生效。
• 元素或属性上出现未绑定的前缀时，parse() 必须抛出 Error，消息恰好为 Undeclared namespace prefix: <prefix>。

所有选项和回调看到的都是解析后的名称：transformTagName 和 updateTag 收到元素名，transformAttributeName 收到 attributeNamePrefix + 属性名，unpairedTags / stopNodes 匹配的是先解析、再经 transformTagName 转换后的名称。jPath 使用解析后的名称（例如 soap:Envelope.soap:Body），且同一元素在 updateTag、tagValueProcessor、attributeValueProcessor、ignoreAttributes 和 isArray 中的 jPath 完全相同；jPath: false 时，matcher 的 getCurrentTag() / toString() 同样保持一致。停止节点的名称和属性会被解析，其内容保持原样，结束标签按原文匹配。启用该选项后：removeNSPrefix 被忽略；处理指令（包括 <?xml ...?>）及其属性保持不变；命名空间绑定绝不会在不同的 parse() 调用之间泄漏；解析为同一名称的元素照常归并为数组。

重要：请从 main 新建一个分支来完成这项工作，完成后提交所有改动。

diff --git a/src/xmlparser/OrderedObjParser.js b/src/xmlparser/OrderedObjParser.js
--- a/src/xmlparser/OrderedObjParser.js
+++ b/src/xmlparser/OrderedObjParser.js
@@ -10,6 +10,7 @@ import { Expression, Matcher } from 'path-expression-matcher';
 import { ExpressionSet } from 'path-expression-matcher';
 import { EntityDecoder, XML, CURRENCY, COMMON_HTML, ENTITY_ACTION } from '@nodable/entities';
 import { isUnsafe, HTML as HTML_CONTEXT, XML as XML_CONTEXT } from "is-unsafe"
+import { getNamespaceAliases, createRootScope, isNamespaceDeclaration, declareNamespaces, resolveQName } from './namespaces.js';
 
 
 // const regx =
@@ -79,12 +80,22 @@ export default class OrderedObjParser {
     this.parseTextData = parseTextData;
     this.resolveNameSpace = resolveNameSpace;
     this.buildAttributesMap = buildAttributesMap;
+    this.buildAttributes = buildAttributes;
+    this.readNamespacedStartTag = readNamespacedStartTag;
     this.isItStopNode = isItStopNode;
     this.replaceEntitiesValue = replaceEntitiesValue;
     this.readStopNodeData = readStopNodeData;
     this.saveTextToParentTag = saveTextToParentTag;
     this.addChild = addChild;
     this.ignoreAttributesFn = getIgnoreAttributesFn(this.options.ignoreAttributes)
+    // resolveNamespaces: namespace URI to alias map when enabled, null otherwise
+    this.nsAliases = getNamespaceAliases(this.options.resolveNamespaces);
+    // removeNSPrefix is ignored when names are resolved by namespace URI
+    this.removeNSPrefix = this.options.removeNSPrefix && this.nsAliases === null;
+    this.decodeNamespaceUri = (value) => {
+      const entityConfig = this.options.processEntities;
+      return entityConfig && entityConfig.enabled ? this.entityDecoder.decode(value) : value;
+    };
     this.entityExpansionCount = 0;
     this.currentExpandedLength = 0;
     this.doctypefound = false;
@@ -181,7 +192,7 @@ function parseTextData(val, tagName, jPath, dontTrim, hasAttributes, isLeafNode,
 }
 
 function resolveNameSpace(tagname) {
-  if (this.options.removeNSPrefix) {
+  if (this.removeNSPrefix) {
     const tags = tagname.split(':');
     const prefix = tagname.charAt(0) === '/' ? '/' : '';
     if (tags[0] === 'xmlns') {
@@ -206,82 +217,148 @@ function buildAttributesMap(attrStr, jPath, tagName, force = false) {
 
     const matches = getAllMatches(attrStr, attrsRegx);
     const len = matches.length; //don't make it inline
-    const attrs = {};
-
-    // Pre-process values once: trim + entity replacement
-    // Reused in both matcher update and second pass
-    const processedVals = new Array(len);
-    let hasRawAttrs = false;
-    const rawAttrsForMatcher = {};
-
+    const attrNames = new Array(len);
     for (let i = 0; i < len; i++) {
-      const attrName = this.resolveNameSpace(matches[i][1]);
-      const oldVal = matches[i][4];
-
-      if (attrName.length && oldVal !== undefined) {
-        let val = oldVal;
-        if (options.trimValues) val = val.trim();
-        val = this.replaceEntitiesValue(val, tagName, this.readonlyMatcher);
-        processedVals[i] = val;
-
-        rawAttrsForMatcher[attrName] = val;
-        hasRawAttrs = true;
-      }
+      attrNames[i] = this.resolveNameSpace(matches[i][1]);
     }
+    return this.buildAttributes(matches, attrNames, jPath, tagName);
+  }
+}
 
-    // Update matcher ONCE before second pass, if applicable
-    if (hasRawAttrs && typeof jPath === 'object' && jPath.updateCurrent) {
-      jPath.updateCurrent(rawAttrsForMatcher);
+/**
+ * Build the attributes map of a tag
+ * @param {Array<Array<string>>} matches - attribute matches of attrsRegx; [4] is the raw value
+ * @param {Array<string>} attrNames - name to use for each match ('' to skip it)
+ * @param {Matcher} jPath - matcher positioned at the tag
+ * @param {string} tagName
+ */
+function buildAttributes(matches, attrNames, jPath, tagName) {
+  const options = this.options;
+  const len = matches.length; //don't make it inline
+  const attrs = {};
+
+  // Pre-process values once: trim + entity replacement
+  // Reused in both matcher update and second pass
+  const processedVals = new Array(len);
+  let hasRawAttrs = false;
+  const rawAttrsForMatcher = {};
+
+  for (let i = 0; i < len; i++) {
+    const attrName = attrNames[i];
+    const oldVal = matches[i][4];
+
+    if (attrName.length && oldVal !== undefined) {
+      let val = oldVal;
+      if (options.trimValues) val = val.trim();
+      val = this.replaceEntitiesValue(val, tagName, this.readonlyMatcher);
+      processedVals[i] = val;
+
+      rawAttrsForMatcher[attrName] = val;
+      hasRawAttrs = true;
     }
+  }
 
-    // Hoist toString() once — path doesn't change during attribute processing
-    const jPathStr = options.jPath ? jPath.toString() : this.readonlyMatcher;
+  // Update matcher ONCE before second pass, if applicable
+  if (hasRawAttrs && typeof jPath === 'object' && jPath.updateCurrent) {
+    jPath.updateCurrent(rawAttrsForMatcher);
+  }
 
-    // Second pass: apply processors, build final attrs
-    let hasAttrs = false;
-    for (let i = 0; i < len; i++) {
-      const attrName = this.resolveNameSpace(matches[i][1]);
+  // Hoist toString() once — path doesn't change during attribute processing
+  const jPathStr = options.jPath ? jPath.toString() : this.readonlyMatcher;
 
-      if (this.ignoreAttributesFn(attrName, jPathStr)) continue;
+  // Second pass: apply processors, build final attrs
+  let hasAttrs = false;
+  for (let i = 0; i < len; i++) {
+    const attrName = attrNames[i];
…… 其余 988 行从略（共改动 9 个文件）

要修改很多行上的某个值，就意味着每一行都要进一次编辑页。请新增 ModelView.column_editable_list（默认 []；元素为名称或 InstrumentedAttribute）。每一项都必须是已映射的列（不能是关系或点号路径），且同时出现在列表中和编辑表单上，否则 Admin.add_view() 抛出 sqladmin.exceptions.ImproperlyConfigured。

新增 POST /{identity}/ajax/update/{pk:path}，路由名为 admin:ajax_update（Admin.ajax_update），表单字段为 name（属性名，例如字段 data_ 对应 data）和 value。只校验编辑表单中的这一个字段，然后通过 update_model(request, pk, {name: data}) 保存它的 data；可空列收到空输入时存为 NULL。on_model_change / after_model_change 收到 ({name: data}, obj, False, request)；审计收到 AuditEntry(action="update", identity=..., pk=<str>, changes={name: data})。返回 200 JSON：pk（字符串）、name、value（存储值的 JSON 形式；非 str 的 Enum → 成员名，日期 → ISO 格式）、display（列表单元格的 str()）。若 after_model_change 返回 Response，则用它代替该 JSON。同步和异步引擎都要同样支持。

在显示编辑链接的行中，可编辑列的 <td>（且仅限这些）带上 data-inline-edit-name="<attribute>" 和 data-inline-edit-url="<该行 ajax_update 的绝对 URL>"。

错误

按以下顺序：未知 identity 返回 404；can_edit / is_accessible 为 false 返回 403；行不存在返回 404；check_can_edit 不为 True 返回 403；name 缺失或不可编辑返回 400。400 响应给出非空的 {"errors": [...]}：值无效时为该字段的 WTForms 错误信息（不保存、不调用钩子、不写审计）；若 on_model_change 或数据库抛出异常，则为 [str(exc)]（该行保持不变）。

重要：请从 main 新建分支进行这项工作，完成后提交所有改动。

diff --git a/sqladmin/application.py b/sqladmin/application.py
--- a/sqladmin/application.py
+++ b/sqladmin/application.py
@@ -15,10 +15,12 @@ from typing import (
 )
 from urllib.parse import parse_qsl, urljoin
 
+import wtforms
 from jinja2 import ChoiceLoader, FileSystemLoader, PackageLoader, PrefixLoader
 from sqlalchemy.engine import Engine
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 from sqlalchemy.orm import Session, sessionmaker
+from sqlalchemy.orm.exc import DetachedInstanceError
 from starlette import status
 from starlette.applications import Starlette
 from starlette.datastructures import URL, FormData, MultiDict, UploadFile
@@ -53,7 +55,9 @@ from sqladmin.forms import WTFORMS_ATTRS, WTFORMS_ATTRS_REVERSED
 from sqladmin.helpers import (
     get_object_identifier,
     is_async_session_maker,
+    object_identifier_values,
     slugify_action_name,
+    to_json_value,
 )
 from sqladmin.i18n import (
     BABEL_INSTALLED,
@@ -88,6 +92,24 @@ def _save_button_clicked(form: FormData, label: str) -> bool:
     return form.get("save") in (label, gettext(label))
 
 
+def _ajax_errors(*messages: Any) -> JSONResponse:
+    """The 400 answer of `Admin.ajax_update`."""
+
+    return JSONResponse(
+        {"errors": [str(message) for message in messages]},
+        status_code=status.HTTP_400_BAD_REQUEST,
+    )
+
+
+def _csrf_field(form: wtforms.Form) -> wtforms.Field | None:
+    """The CSRF token field of ``form``, if its form class enables WTForms CSRF."""
+
+    if not getattr(form.meta, "csrf", False):
+        return None
+    name = form.meta.csrf_field_name
+    return form[name] if name in form else None
+
+
 class BaseAdmin:
     """Base class for implementing Admin interface.
 
@@ -458,6 +480,33 @@ class BaseAdminView(BaseAdmin):
             if can_edit_row is not True:
                 raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
 
+    async def _ajax_update(self, request: Request) -> tuple[ModelView, Any]:
+        """Guard an in-place edit from the list page and return its view and row.
+
+        Unlike `_edit`, the row is loaded before `check_can_edit` is asked
+        about it, so an unknown row is a 404 rather than a question about
+        ``None``.
+        """
+
+        model_view = self._find_model_view(request.path_params["identity"])
+        if not model_view.can_edit or not model_view.is_accessible(request):
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
+
+        try:
+            object_identifier_values(request.path_params["pk"], model_view.model)
+        except (ArithmeticError, TypeError, ValueError) as exc:
+            # A malformed identifier matches no row.
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND) from exc
+
+        obj = await model_view.get_object_for_edit(request)
+        if obj is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+
+        if await model_view.check_can_edit(request, obj) is not True:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN)
+
+        return model_view, obj
+
     async def _import(self, request: Request) -> None:
         model_view = self._find_model_view(request.path_params["identity"])
         if not model_view.is_accessible(request):
@@ -650,6 +699,12 @@ class Admin(BaseAdminView):
             Route(
                 "/{identity}/ajax/lookup", endpoint=self.ajax_lookup, name="ajax_lookup"
             ),
+            Route(
+                "/{identity}/ajax/update/{pk:path}",
+                endpoint=self.ajax_update,
+                name="ajax_update",
+                methods=["POST"],
+            ),
             Route("/login", endpoint=self.login, name="login", methods=["GET", "POST"]),
             Route("/logout", endpoint=self.logout, name="logout", methods=["GET"]),
             Route(
@@ -1077,6 +1132,106 @@ class Admin(BaseAdminView):
         data = [loader.format(m) for m in await loader.get_list(request, term)]
         return JSONResponse({"results": data})
 
+    @login_required
+    async def ajax_update(self, request: Request) -> Response:
+        """Save one column of one row, edited in place on the list page.
+
+        Takes the form fields ``name``, the attribute to change (which must
+        be in `ModelView.column_editable_list`), and ``value``. The value is
+        validated by that column's edit form field alone and saved through
+        `ModelView.update_model`, so `on_model_change`, `after_model_change`
+        and the audit backend all see ``{name: data}``. An empty ``value``
+        stores ``NULL`` in a nullable column.
+
+        Answers with JSON: the row's ``pk``, the ``name``, the stored
+        ``value`` and its ``display``, i.e. the list page cell as a string.
+        Invalid input or a failed save answers 400 with ``{"errors": [...]}``,
+        while a `Response` returned by `after_model_change` is used as is.
+        """
+
+        model_view, _ = await self._ajax_update(request)
+        pk = request.path_params["pk"]
+
+        request_form = await request.form()
+        name = request_form.get("name")
+        if not isinstance(name, str) or not name:
+            return _ajax_errors("The 'name' field is required.")
+        if name not in model_view._editable_fields:
+            return _ajax_errors(f"{name!r} cannot be edited in place.")
+
+        Form = await model_view.scaffold_form(model_view._form_edit_rules)
+        form = Form()
+        key = WTFORMS_ATTRS.get(name, name)
+        if key not in form:
+            return _ajax_errors(f"{name!r} is not a field of the edit form.")
…… 其余 2,125 行从略（共改动 11 个文件）

cloud 和 onpremise 中的每个服务方法都要经过 Client.Do，而它只发起一次尝试，因此各集成方都是自己手写 429/503 重试、自行解析限流响应头。我们要为这两个包都加上可选启用（opt-in）的重试和解析好的限流信息，并且两者的重试语义完全相同。

两个包都新增一个 RetryPolicy 结构体（MaxRetries int、MinBackoff, MaxBackoff time.Duration、RetryNonIdempotent bool、Sleep func(ctx context.Context, d time.Duration) error）以及 Client.RetryPolicy *RetryPolicy 字段。NewClient 让它保持为 nil；策略为 nil 或 MaxRetries <= 0 表示只发一次请求，行为与现在完全一致。

否则，Do 仅在以下条件同时满足时重试：状态码为 429 或 503；方法为 GET、HEAD、OPTIONS、PUT 或 DELETE（若 RetryNonIdempotent 为 true，则任何方法都可以）；请求体可重放（req.Body == nil 或 req.GetBody != nil）；已做的重试少于 MaxRetries 次。因此最多发出 MaxRetries+1 个请求。其他状态码一律不重试（即使是 500/502/504）；http.Client 的传输错误立即返回。在第 n 次重试（从 1 开始计数）之前，要读空并关闭上一个响应，并调用 Sleep(req.Context(), policy.Backoff(n, previousResponse))，即使延迟为零也要调用；Sleep 为 nil 时，用定时器等满该延迟，但一旦 context 结束就立即返回 ctx.Err()。如果 Sleep 返回错误，则停止重试，返回 nil 的 *Response，以及一个在 errors.Is 下与之匹配的错误。重试会重发相同的方法、URL 和请求头，以及由 req.GetBody 得到的逐字节相同的请求体；由 NewRequest、NewMultiPartRequest 创建的请求，以及传入 strings.Reader、bytes.Reader 或 bytes.Buffer 的 NewRawRequest 请求都可重放，而基于其他 reader 的 NewRawRequest 只发送一次。当重试用尽或响应不可重试时，Do 的处理与现在完全相同（2xx 时解码到 v，否则返回 *Response 和通常的 CheckResponse 错误），因此服务方法仍返回其 NewJiraError 结果，且 resp.StatusCode 为最终状态码。

func (p *RetryPolicy) Backoff(attempt int, resp *http.Response) time.Duration：当 resp 非 nil 且其 Retry-After 头是非负整数时，返回以秒计的 Retry-After 值，否则返回 MinBackoff * 2^(attempt-1)；HTTP 日期、负数或格式错误的值都会被忽略。无论哪种结果，都以 MaxBackoff 为上限且不得溢出（Backoff(100, nil) == MaxBackoff）。MinBackoff <= 0 表示 1s，MaxBackoff <= 0 表示 30s，attempt < 1 按 1 处理。例如，MaxRetries 为 3、MinBackoff 为 100ms、MaxBackoff 为 250ms 时，对一个始终返回 503（且不带 Retry-After）的服务器发起 GET：会发出 4 个请求，Sleep 依次收到 100ms、200ms、250ms，调用最终失败，resp.StatusCode 为 503。

另外新增 Response.RateLimit RateLimit 字段，Do 返回的每个 *Response 都要根据响应头填充它（无论 2xx 还是错误状态码，也无论是否设置策略）；缺失或无法解析的头部使对应字段保持零值。在 cloud 中，RateLimit 包含 Limit, Remaining int（X-RateLimit-Limit、X-RateLimit-Remaining）、Reset time.Time（X-RateLimit-Reset，RFC 3339）、NearLimit bool（当且仅当 X-RateLimit-NearLimit 不区分大小写地等于 "true" 时为 true）、Reason string（RateLimit-Reason，原样保留）以及 RetryAfter time.Duration（Retry-After，非负整数秒）。在 onpremise 中，它有同样的 Limit、Remaining 和 RetryAfter，另加 FillRate int（X-RateLimit-FillRate）和 Interval time.Duration（X-RateLimit-Interval-Seconds，整数秒）。Response 上的其他内容以及错误信息都不应改变。

重要：请从 main 新建一个分支进行这项工作，完成后提交所有改动。

diff --git a/cloud/retry.go b/cloud/retry.go
new file mode 100644
--- /dev/null
+++ b/cloud/retry.go
@@ -0,0 +1,262 @@
+package cloud
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"math"
+	"net/http"
+	"strconv"
+	"time"
+)
+
+const (
+	// defaultMinBackoff is used by RetryPolicy.Backoff if MinBackoff is not positive.
+	defaultMinBackoff = 1 * time.Second
+
+	// defaultMaxBackoff is used by RetryPolicy.Backoff if MaxBackoff is not positive.
+	defaultMaxBackoff = 30 * time.Second
+
+	// maxDrainBytes limits how much of a response body is read before a retry discards it.
+	// Small bodies are read completely so that the connection can be reused,
+	// without the risk of reading an arbitrarily large body.
+	maxDrainBytes = 64 << 10
+
+	// maxDuration is the largest representable time.Duration.
+	maxDuration = time.Duration(math.MaxInt64)
+
+	// maxDurationSeconds is the largest number of whole seconds a time.Duration can hold.
+	maxDurationSeconds = int64(maxDuration / time.Second)
+)
+
+// RetryPolicy configures how Client.Do retries requests that Jira rejected because of
+// rate limiting (429 Too Many Requests) or temporary unavailability (503 Service Unavailable).
+//
+// Retries are opt-in: they only happen if Client.RetryPolicy is set and MaxRetries is positive.
+// A request is retried only if all of the following conditions are met:
+//
+//   - the response status is 429 or 503. No other status is retried (not even 500, 502 or 504),
+//     and errors returned by the http.Client (e.g. network errors) are returned immediately.
+//   - the method is GET, HEAD, OPTIONS, PUT or DELETE, or RetryNonIdempotent is set.
+//   - the request body can be replayed: the request has no body or Request.GetBody is set.
+//     This is the case for all requests created by NewRequest and NewMultiPartRequest,
+//     and for NewRawRequest with a *strings.Reader, *bytes.Reader or *bytes.Buffer body.
+//     Requests created by NewRawRequest with any other reader are sent only once.
+//   - fewer than MaxRetries retries have been made, so at most MaxRetries+1 requests are sent.
+//
+// A retry resends the same method, URL, headers and body.
+// Before retry n (1-based), the previous response is drained and closed and
+// Sleep is called with the request's context and Backoff(n, previousResponse).
+//
+// Once a response is not retried (or no retries are left), Do handles it as without a policy.
+// The returned Response therefore always describes the last attempt.
+type RetryPolicy struct {
+	// MaxRetries is the maximum number of retries per request.
+	// Zero or a negative value disables retries.
+	MaxRetries int
+
+	// MinBackoff is the base delay of the exponential backoff (default 1s if <= 0).
+	MinBackoff time.Duration
+
+	// MaxBackoff caps every delay, including those requested via Retry-After (default 30s if <= 0).
+	MaxBackoff time.Duration
+
+	// RetryNonIdempotent enables retries for all request methods, including POST and PATCH.
+	// Only enable it if sending such a request more than once is safe for your use case.
+	RetryNonIdempotent bool
+
+	// Sleep waits for the given delay before a retry.
+	// It is called before every retry, even if the delay is zero.
+	// If it returns an error, Do stops retrying and returns a nil *Response
+	// together with an error that wraps the returned error.
+	//
+	// If Sleep is nil, Do waits for the delay on a timer, but returns
+	// ctx.Err() as soon as the context is done.
+	Sleep func(ctx context.Context, d time.Duration) error
+}
+
+// Backoff returns how long to wait before retry number attempt (1-based),
+// given resp, the response to the previous attempt (which may be nil).
+//
+// If resp has a Retry-After header holding a non-negative integer number of seconds,
+// that delay is returned. Otherwise, the delay grows exponentially: MinBackoff * 2^(attempt-1).
+// Retry-After values in the HTTP-date format as well as negative or malformed values are ignored.
+// The result is capped at MaxBackoff.
+//
+// A MinBackoff <= 0 is treated as 1s, a MaxBackoff <= 0 as 30s and an attempt < 1 as 1.
+func (p *RetryPolicy) Backoff(attempt int, resp *http.Response) time.Duration {
+	minBackoff, maxBackoff := defaultMinBackoff, defaultMaxBackoff
+	if p != nil && p.MinBackoff > 0 {
+		minBackoff = p.MinBackoff
+	}
+	if p != nil && p.MaxBackoff > 0 {
+		maxBackoff = p.MaxBackoff
+	}
+
+	if resp != nil {
+		if d, ok := parseDelaySeconds(resp.Header.Get("Retry-After")); ok {
+			if d > maxBackoff {
+				return maxBackoff
+			}
+			return d
+		}
+	}
+
+	if attempt < 1 {
+		attempt = 1
+	}
+	// minBackoff << shift <= maxBackoff holds exactly if minBackoff <= maxBackoff >> shift.
+	// Checking it this way avoids overflowing for large attempts.
+	shift := uint(attempt - 1)
+	if minBackoff > maxBackoff>>shift {
+		return maxBackoff
+	}
+	return minBackoff << shift
+}
+
+// shouldRetry reports whether p allows retrying req at all.
+// It does not consider the response status or the number of retries made so far.
+func (p *RetryPolicy) shouldRetry(req *http.Request) bool {
+	if p == nil || p.MaxRetries <= 0 {
+		return false
+	}
+	if !p.RetryNonIdempotent && !isIdempotentMethod(req.Method) {
+		return false
+	}
…… 其余 2,538 行从略（共改动 12 个文件）

目前，想预览一个 cron 表达式只能通过创建任务，而且只能从当前时刻往后看。也没有任何途径能告诉你某个调度上一次是什么时候触发的，而停机后的补跑、仪表盘和各类工具都需要这个信息。能否实现从任意时刻出发、正反两个方向的无状态触发时刻枚举，并在任务上提供上次运行的查询？

新增模块级的 getNextRuns(expression, options?): Date[] 和 getPreviousRuns(expression, options?): Date[]，选项为 { count?: number; from?: Date | string | number; timezone?: string }。在 ESM 和 CJS 构建中，它们都要作为包入口的具名导出，同时作为默认导出 cron 和 NodeCron 接口的成员。getNextRuns 返回严格晚于 from 的前 count 个触发时刻，按升序排列；getPreviousRuns 返回严格早于 from 的最近 count 个触发时刻，最近的排在最前。默认值：count 为 1，from 为当前时刻，timezone 为进程的本地时区；count 为 0 时返回 []。触发时刻都是整秒，但 from 可以带毫秒：对于 */20 * * * * *，从 12:00:00.500Z 起，之前 2 个为 [12:00:00Z, 11:59:40Z]，之后为 [12:00:20Z]。

两个方向都必须与调度器的实际触发完全一致：反向结果就是正向调度序列的倒序，两个返回时刻之间不能漏掉任何正向会出现的触发时刻。这适用于所有语法（预设别名、5 字段和 6 字段、名称、?、L、L-n、nW、LW、nL、# 以及首尾回绕的范围），也适用于夏令时：在回拨造成的重叠时段中，一个墙上时间只触发一次，即在其第一个（切换前的）时刻触发，因此重复的那一小时不会触发；拨快时被跳过的时间也永远不会触发。在 America/New_York 时区，* * * * * 从 2025-11-02T06:20:00Z 起取之前 2 个，必须得到 [05:59Z, 05:58Z]，而不是 06:19Z；30 2 * * * 从 2025-03-10T12:00:00Z 起取之前 2 个，得到 [2025-03-10T06:30Z, 2025-03-08T07:30Z]。

每一次搜索的范围都是从上一个找到的触发时刻（或从 from）起的 36,600 天；如果某次搜索一无所获，就返回较短的数组（可能为空），而不是抛出异常。因此 0 0 0 31 * 0#1 返回 []，而 0 0 0 29 2 1 在 UTC 下从 2026-01-01 起取之前 5 个，得到 2016、1988、1960、1932 和 1904 年的 2 月 29 日。

错误参数仍然会抛出异常：无效表达式抛出 Error，其消息与 cron.parse() 对该表达式抛出的消息完全相同；不是非负整数的 count 抛出 RangeError；若 from 不是能经 new Date(from) 得到有效日期的 Date、字符串或数字，则抛出 TypeError；未知时区抛出 RangeError。

在 ScheduledTask 接口上新增 getPreviousRun(): Date | null 和 getPreviousRuns(count: number): Date[]，由内联任务和后台任务实现，且两者结果完全相同（后台任务仅由父进程自行给出结果）。getPreviousRun() 按任务的表达式和时区，返回严格早于当前时刻的最近一个触发时刻，没有则返回 null；该结果与任务状态无关（包括已停止和已销毁）。getPreviousRuns(count) 返回最近的 count 个此类触发时刻，最近的排在最前；count <= 0 时返回 []。

以下内容均保持不变：任务的触发行为、夏令时模型、现有任务方法（getNextRun()、getNextRuns(count)、match()、msToNext()，包括它们抛出的 'Could not find next matching date' 异常），以及 cron.parse、validate 和 validateDetailed。

重要：请从 main 新建一个分支进行开发，完成后提交所有改动。

diff --git a/src/time/matcher-walker.ts b/src/time/matcher-walker.ts
--- a/src/time/matcher-walker.ts
+++ b/src/time/matcher-walker.ts
@@ -1,4 +1,4 @@
-import { LocalizedTime, localTimeToTimestamp } from './localized-time';
+import { LocalizedTime, WallClock, getOffsetMinutes, localTimeToTimestamp } from './localized-time';
 import { TimeMatcher } from './time-matcher';
 import { matchesDayOfMonth, DayOfMonthField } from './day-of-month';
 import { matchesDayOfWeek, DayOfWeekField } from './day-of-week';
@@ -8,6 +8,13 @@ import { matchesDayOfWeek, DayOfWeekField } from './day-of-week';
 // cheap, so reaching it means the expression can never match (e.g. `0 0 31 2 *`).
 const MAX_DAYS = 366 * 100;
 
+const DAY_MS = 86400000;
+
+// A JS Date spans +/-8.64e15 ms. Within a day of either end, the UTC offset
+// applied while materializing a wall-clock time can step outside that range.
+const DATE_RANGE_MS = 8.64e15;
+const SAFE_RANGE_MS = DATE_RANGE_MS - DAY_MS;
+
 export class MatcherWalker {
   baseDate: Date;
   timeMatcher: TimeMatcher;
@@ -40,7 +47,21 @@ export class MatcherWalker {
 
   /**
    * Finds the next instant that satisfies the expression, strictly after the
-   * base date.
+   * base date. Throws when there is none within the search bound; see
+   * findNext() for the algorithm.
+   */
+  matchNext(): LocalizedTime {
+    const next = this.findNext();
+    if (next === null) {
+      throw new Error('Could not find next matching date within reasonable time range');
+    }
+    return new LocalizedTime(new Date(next), this.timezone);
+  }
+
+  /**
+   * Finds the next instant that satisfies the expression, strictly after the
+   * base date, and returns its timestamp, or null when there is none within
+   * the search bound (MAX_DAYS calendar days, starting at the base day).
    *
    * Instead of scanning time tick by tick, it infers candidates directly from
    * the cron fields: it walks the calendar day by day (a Y/M/D is the same
@@ -50,10 +71,7 @@ export class MatcherWalker {
    * real matcher, which both enforces the weekday constraint and rejects
    * non-existent local times (the DST spring-forward gap) by construction.
    */
-  matchNext(): LocalizedTime {
-    const months = this.months;
-    const days = this.days;
-
+  findNext(): number | null {
     const baseMs = Math.floor(this.baseDate.getTime() / 1000) * 1000;
     const baseParts = new LocalizedTime(new Date(baseMs), this.timezone).getParts();
 
@@ -65,20 +83,82 @@ export class MatcherWalker {
       // exactly, so it only skips days that would be rejected anyway, and it
       // avoids scanning every time on a day whose weekday can't match (e.g.
       // `* * * 15 * 1`, the 15th only when it is a Monday).
-      if (months.includes(month) && matchesDayOfMonth(days, year, month, day) && this.matchesWeekday(year, month, day)) {
+      if (this.isCandidateDay(year, month, day)) {
         // On the base day the result must be strictly after the base instant;
         // on later days any matching time of day qualifies.
         const lowerBound = i === 0 ? baseParts : null;
         const found = this.firstTimeOnDay(year, month, day, lowerBound, baseMs);
         if (found !== null) {
-          return new LocalizedTime(new Date(found), this.timezone);
+          return found;
         }
       }
 
       ({ year, month, day } = nextDay(year, month, day));
     }
 
-    throw new Error('Could not find next matching date within reasonable time range');
+    return null;
+  }
+
+  /**
+   * Finds the latest instant strictly before the base date that the forward
+   * walk (findNext) can produce, and returns its timestamp, or null when there
+   * is none within the search bound (MAX_DAYS calendar days, ending at the
+   * starting day).
+   *
+   * It mirrors findNext(): it walks the calendar backwards day by day and, on
+   * each eligible day, tries the matching times in descending order. Every
+   * candidate is materialized exactly like the forward walk does, so:
+   *  - a wall-clock time repeated by a DST fall-back resolves to the single
+   *    instant the scheduler fires for it, never to the other one;
+   *  - a time inside a spring-forward gap materializes past the gap and is
+   *    rejected by the matcher (it never fires either).
+   * Within a day, later wall-clock times materialize to later instants, so the
+   * first confirmed candidate is the latest one.
+   *
+   * Occurrences are whole seconds while the base may carry milliseconds: the
+   * latest admissible instant is the last whole second strictly before it.
+   */
+  findPrevious(): number | null {
+    let latest = Math.ceil(this.baseDate.getTime() / 1000) * 1000 - 1000;
+    if (!(latest >= -DATE_RANGE_MS)) return null;
+
+    let bound = this.wallClockAt(latest);
+    const materialized = materialize(bound, this.timezone);
+    // NaN: the wall-clock time lies past the end of the Date range; the scan
+    // below simply skips the times that cannot be materialized.
+    if (materialized !== latest && !Number.isNaN(materialized)) {
+      // `latest` is the instance of a repeated (fall-back) wall-clock time that
+      // is never fired, and so is every instant from the start of that run up
+      // to it. Restart from the last instant before the run, whose wall-clock
+      // is an exact bound for the time-of-day scan below. The run is at most as
+      // long as the distance between the two instances of the wall-clock time.
+      const before = this.lastMaterializedBefore(latest, Math.abs(materialized - latest));
+      // Null only for timezone data not shaped like a DST overlap; the scan
+      // below then still never returns an instant after `latest`.
+      /* v8 ignore else */
+      if (before !== null) {
+        latest = before;
+        bound = this.wallClockAt(latest);
+      }
+    }
+
+    let { year, month, day } = bound;
+
+    for (let i = 0; i < MAX_DAYS; i++) {
+      if (this.isCandidateDay(year, month, day)) {
+        // On the starting day only times up to the bound qualify; on earlier
+        // days any matching time of day does.
…… 其余 1,495 行从略（共改动 15 个文件）

我看不出某个请求为什么被拒绝：is_authorized 只给出决策、起决定作用的策略 ID 和错误，所以一条 scope 从未匹配的策略，看起来和一条 when 子句不成立的策略一模一样。我希望在 Rust API、CLI 和 JSON/wasm FFI 中提供逐条策略的解释；现有行为不得改变。

新增 Authorizer::explain(&self, &Request, &PolicySet, &Entities) -> AuthorizationExplanation，并在 cedar_policy 根模块新增以下类型：AuthorizationExplanation，提供 response() -> &Response、decision() -> Decision、policies() -> impl Iterator<Item = &PolicyExplanation> 和 policy(&PolicyId) -> Option<&PolicyExplanation>；PolicyExplanation，提供 id() -> &PolicyId、effect() -> Effect、outcome() -> PolicyOutcome、condition_index() -> Option<usize>，以及返回 bool 的 getter principal_matched()、action_matched()、resource_matched()、is_determining()；以及 PolicyOutcome（派生 Debug, Clone, Copy, PartialEq, Eq），包含 NotApplicable、ConditionFalse、Satisfied、Error 四个变体。

• 在相同输入下，response() 与 is_authorized 的结果一致（决策、reason 和错误）；decision() 即其决策。
• policies() 列出所有静态策略和模板链接策略（不含未链接的模板），按 ID 字符串排序。
• 每个 scope 约束单独求值（模板链接使用其 slot 值）；三个标志始终都要计算。只要任一为 false，结果就是 NotApplicable，且不对条件求值，即使条件会出错也不求值。
• 否则按源码顺序（即 Policy::to_json() 中 conditions 的顺序）依次对 when / unless 子句求值，直到某个子句不通过（when 在值为 true 时通过，unless 在值为 false 时通过）：若该子句求值未出错，结果为 ConditionFalse；若出错或结果不是布尔值，结果为 Error。如果全部通过，或者根本没有子句，结果为 Satisfied。
• 对于 ConditionFalse / Error，condition_index() 是停止处子句从 0 开始的索引，否则为 None。
• 当且仅当该 ID 出现在 response().diagnostics().reason() 中时，is_determining() 为 true。

cedar authorize --explain 先原样打印正常输出，然后输出一个空行、explanation:，再按 ID 顺序为每条策略输出一行 <id> (<permit|forbid>): <text>，其中 <text> 为 satisfied (determining)、satisfied、scope did not match: <parts>、condition <i> not satisfied、error in condition <i> 之一；<parts> 用 , 连接 principal、action、resource 中未匹配的项（按此顺序），<i> 即 condition_index()。退出码不变；不带该选项时输出逐字节相同。

在 cedar_policy::ffi 中新增 explain_authorization(AuthorizationCall) -> ExplanationAnswer、explain_authorization_json(serde_json::Value) -> Result<serde_json::Value, serde_json::Error> 和 explain_authorization_json_str(&str) -> Result<String, serde_json::Error>，以及一个 wasm_bindgen 导出 explainAuthorization（feature wasm），并由 cedar-wasm 重新导出。无法解析的输入返回与 is_authorized 相同的失败结果。成功时为 {"type":"success","response":<与 isAuthorized 相同>,"policies":[...],"warnings":[...]}；每个策略对象按 policies() 的顺序排列，恰好包含 id、effect（"permit" / "forbid"）、principalMatched、actionMatched、resourceMatched、outcome（"notApplicable" / "conditionFalse" / "satisfied" / "error"）、conditionIndex（数字或 null）和 determining。_json 系列函数仅在输入不是 AuthorizationCall 时返回 Err。

重要：请从 main 新建一个分支来完成这项工作，完成后提交所有改动。

diff --git a/cedar-policy/src/api/explain.rs b/cedar-policy/src/api/explain.rs
new file mode 100644
--- /dev/null
+++ b/cedar-policy/src/api/explain.rs
@@ -0,0 +1,341 @@
…
+fn explain_conditions(
+    evaluator: &Evaluator<'_>,
+    policy: &Policy,
+) -> (PolicyOutcome, Option<usize>) {
+    // The AST has no non-scope constraints exactly when the policy has no
+    // `when` or `unless` clauses, in which case there's nothing to evaluate
+    if policy.ast.non_scope_constraints().is_none() {
+        return (PolicyOutcome::Satisfied, None);
+    }
+    // The AST combines all the clauses of a policy into a single expression
+    // (and may simplify that expression), so we can't recover the individual
+    // clauses from it. Instead, use the same lossless representation which
+    // `Policy::to_json()` uses, so that clause indices match the order of the
+    // `conditions` in the policy's JSON form. If that isn't available, fall
+    // back to the representation derived from the AST, which (like the JSON
+    // form of a policy constructed from an AST) has a single `when` clause
+    // containing all the conditions.
+    let est = policy
+        .lossless
+        .est(|| policy.ast.clone().into())
+        .unwrap_or_else(|_| policy.ast.clone().into());
+    for (index, clause) in est.conditions().iter().enumerate() {
+        // `when` clauses are satisfied when they evaluate to `true`, and
+        // `unless` clauses when they evaluate to `false`
+        let (body, satisfied_when) = match clause {
+            est::Clause::When(body) => (body, true),
+            est::Clause::Unless(body) => (body, false),
+        };
+        // A clause which can't be converted to an AST can't be evaluated
+        // successfully, so we report it as erroring
+        let value = body
+            .clone()
+            .try_into_ast(policy.ast.id())
+            .ok()
+            .and_then(|body| evaluate_to_bool(evaluator, &body, policy.ast.env()));
+        match value {
+            Some(value) if value == satisfied_when => {}
+            Some(_) => return (PolicyOutcome::ConditionFalse, Some(index)),
+            None => return (PolicyOutcome::Error, Some(index)),
+        }
+    }
+    (PolicyOutcome::Satisfied, None)
+}
+
+/// Returns `true` if `expr` evaluates to `true`.
+fn evaluates_to_true(evaluator: &Evaluator<'_>, expr: &ast::Expr, slots: &ast::SlotEnv) -> bool {
+    evaluate_to_bool(evaluator, expr, slots) == Some(true)
+}
+
+/// Evaluate `expr`, returning `None` if evaluation produces an error or a
+/// value which is not a boolean (including a residual, if the request or
+/// entities contain unknowns).
+fn evaluate_to_bool(
+    evaluator: &Evaluator<'_>,
+    expr: &ast::Expr,
+    slots: &ast::SlotEnv,
+) -> Option<bool> {
+    let value = evaluator.interpret(expr, slots).ok()?;
+    match value.value_kind() {
+        ast::ValueKind::Lit(ast::Literal::Bool(b)) => Some(*b),
+        _ => None,
+    }
+}
+
+/// An authorization [`Response`], together with an explanation of how each
+/// policy evaluated against the request.
+///
+/// Returned by [`Authorizer::explain()`](super::Authorizer::explain).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthorizationExplanation {
…
+impl ScopeMatches {
+    /// Evaluate each of the scope constraints of `policy` on its own, so that
+    /// we can report all of the constraints which don't match
+    fn new(evaluator: &Evaluator<'_>, policy: &Policy) -> Self {
+        // The constraints of the template may contain slots, which are filled
+        // in by `slots` for template-linked policies
+        let template = policy.ast.template();
+        let slots = policy.ast.env();
+        Self {
+            principal: evaluates_to_true(
+                evaluator,
+                &template.principal_constraint().as_expr(),
+                slots,
+            ),
+            action: evaluates_to_true(evaluator, &template.action_constraint().as_expr(), slots),
+            resource: evaluates_to_true(
+                evaluator,
+                &template.resource_constraint().as_expr(),
+                slots,
+            ),
+        }
+    }
+
+    /// Whether all the scope constraints match the request
+    fn all(self) -> bool {
+        self.principal && self.action && self.resource
+    }
+}
+
+/// Explanation of how a single static or template-linked policy evaluated
+/// against an authorization request.
+///
+/// Obtained from [`AuthorizationExplanation::policies()`] or
+/// [`AuthorizationExplanation::policy()`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PolicyExplanation {
+    /// ID of the policy
+    id: PolicyId,
+    /// Effect of the policy
+    effect: Effect,
+    /// Which of the policy's scope constraints match the request
+    scope: ScopeMatches,
…… 其余 2,505 行从略（共改动 13 个文件）

CreatePath 目前只接受 .name、[n]、[*] 和 ..name，而且即便在这些形式下，Path 的 Extract、Unmarshal 和 Get 的行为也不正确。请实现 RFC 9535 的选择器，并让这三个方法的行为保持一致。

路径是 $ 后接若干段：.name、.*、."name"、[sel, ...]、..name、..* 或 ..[sel, ...]。选择器包括带引号的名称（'a'、"a"；支持 JSON 字符串转义，单引号内另外支持 \'）、*、索引（可选的 - 加数字）、切片 start:end:step（各部分均可省略）以及过滤器 ?expr。方括号中的选择器、逗号和过滤器记号两侧都可以有空白。过滤器使用 ||（优先级最低）、&&、!、括号以及比较运算（==、!=、<、<=、>、>=），其操作数为字面量（数字、带引号的字符串、true、false、null）或单值查询（@ 后接任意个名称段或索引段）。像 @.isbn 这样单独的查询用于检测存在性，即使值为 null 也为真。其他任何路径（例如 [1:2:3:4]、函数调用或过滤器中的 $）都应使 CreatePath 返回 *PathError；它绝不能 panic。

求值遵循 RFC 9535（比较按 §2.3.5.2.2 进行），并且：

• 一个方括号中的各选择器按顺序应用，保留重复结果；
• 对象成员按文档顺序（原始 JSON）、键的升序（Go map）或字段顺序（结构体）访问；一个名称选中所有具有该名称的成员；
• 后代段先作用于节点本身，再按先序作用于其后代（$..b 作用于 {"x":{"b":1},"b":2} 得到 2, 1）；
• 不适用的选择器（成员不存在、索引越界、类型不符、标量、null）不选中任何值，也不报错。

Extract 按顺序返回所选的值，每个值为其在输入中的文本去掉首尾空白（无匹配时返回零个结果）；输入中任何位置无效时，无论路径如何，都返回 *SyntaxError；$ 原样返回输入。Unmarshal 按顺序解码同样的值，与现在一致。Get(src, dst) 遍历以字符串为键的 map、结构体（encoding/json 会编码的字段，按 JSON 键访问，忽略 omitempty）、切片和数组，并穿过指针和接口；nil 值视为 null，且绝不 panic。对于单值路径（每段只含一个名称或索引，且没有后代段），它存入该值，无匹配时返回错误；否则存入列表（*[]T 与现在一致，*any 存入一个可能为空的 []any）；$ 存入 src。

Path 绝不能改变，即使调用失败也是如此，并且必须能安全地在 goroutine 之间共享；PathString 原样返回传给 CreatePath 的参数。RootSelectorOnly 仍然只对 $ 为真，UsedSingleQuotePathSelector / UsedDoubleQuotePathSelector 仍报告带引号名称所使用的引号。

重要：请从 main 新建一个分支进行这项工作，完成后提交全部改动。

diff --git a/internal/decoder/path_parse.go b/internal/decoder/path_parse.go
new file mode 100644
--- /dev/null
+++ b/internal/decoder/path_parse.go
@@ -0,0 +1,787 @@
…
+// filterOr parses the expression of a filter at pos: the expressions which || joins, which binds the least.
+func (p *pathParser) filterOr() (pathFilter, error) {
+	return p.filterTerms(pathFilterOr, "||", (*pathParser).filterAnd)
+}
+
+// filterAnd parses the expressions which && joins.
+func (p *pathParser) filterAnd() (pathFilter, error) {
+	return p.filterTerms(pathFilterAnd, "&&", (*pathParser).filterBasic)
+}
+
+// filterTerms parses the expressions which the operator joins, each by term: one of them is the expression itself.
+// The white spaces after the last one are skipped.
+func (p *pathParser) filterTerms(kind pathFilterKind, operator string, term func(*pathParser) (pathFilter, error)) (pathFilter, error) {
+	first, err := term(p)
+	if err != nil {
+		return first, err
+	}
+	var terms []pathFilter
+	for {
+		p.skipSpaces()
+		if !strings.HasPrefix(p.text[p.pos:], operator) {
+			break
+		}
+		p.pos += len(operator)
+		p.skipSpaces()
+		next, err := term(p)
+		if err != nil {
+			return next, err
+		}
+		if terms == nil {
+			terms = []pathFilter{first}
+		}
+		terms = append(terms, next)
+	}
+	if terms == nil {
+		return first, nil
+	}
+	return pathFilter{kind: kind, terms: terms}, nil
+}
+
+// filterBasic parses what && and || join: an expression in parentheses or a query, which ! may negate, or a
+// comparison. As in RFC 9535, a comparison is negated in parentheses, and a literal is compared.
+func (p *pathParser) filterBasic() (pathFilter, error) {
+	negated := p.peek() == '!'
+	if negated {
+		p.pos++
+		p.skipSpaces()
+	}
+	var filter pathFilter
+	var err error
+	switch c := p.peek(); {
+	case c == '(':
+		if p.nesting == maxPathNesting {
+			return filter, p.errorf("the parentheses of a filter nest too deep")
+		}
+		p.nesting++
+		p.pos++
+		p.skipSpaces()
+		if filter, err = p.filterOr(); err != nil {
+			return filter, err
+		}
+		if p.peek() != ')' {
+			return filter, p.unexpected("a right parenthesis")
+		}
+		p.pos++
+		p.nesting--
+	case negated && c != '@':
+		return filter, p.unexpected("a left parenthesis or a query after !")
+	default:
+		if filter.left, err = p.operand(); err != nil {
+			return filter, err
+		}
+		var compared bool
+		if !negated {
+			filter.op, compared = p.compareOp()
+		}
+		switch {
+		case compared:
+			filter.kind = pathFilterCompare
+			p.skipSpaces()
+			if filter.right, err = p.operand(); err != nil {
+				return filter, err
+			}
+		case filter.left.query:
+			filter.kind = pathFilterExists
+		default:
+			return filter, p.unexpected("a comparison operator after a literal")
+		}
+	}
+	if negated {
+		filter = pathFilter{kind: pathFilterNot, terms: []pathFilter{filter}}
+	}
+	return filter, nil
+}
…
+// operand parses what a filter compares at pos: a literal or a query.
+func (p *pathParser) operand() (pathOperand, error) {
+	rest := p.text[p.pos:]
+	switch c := p.peek(); {
+	case c == '@':
+		steps, err := p.query()
+		return pathOperand{query: true, steps: steps}, err
+	case c == '\'' || c == '"':
+		str, err := p.quoted()
+		return pathOperand{kind: pathKindString, str: str}, err
+	case c == '-' || ('0' <= c && c <= '9'):
+		return p.number()
+	case strings.HasPrefix(rest, "true"):
+		p.pos += len("true")
+		return pathOperand{kind: pathKindTrue}, nil
+	case strings.HasPrefix(rest, "false"):
+		p.pos += len("false")
+		return pathOperand{kind: pathKindFalse}, nil
+	case strings.HasPrefix(rest, "null"):
+		p.pos += len("null")
+		return pathOperand{kind: pathKindNull}, nil
+	case c == '$':
+		return pathOperand{}, p.errorf("a query from the root identifier $ is not supported in a filter")
+	}
+	// the name of a function of RFC 9535, which its arguments follow in parentheses
+	name := strings.TrimLeft(rest, "_abcdefghijklmnopqrstuvwxyz0123456789")
+	if len(name) < len(rest) && strings.HasPrefix(name, "(") {
+		return pathOperand{}, p.errorf("the function %s is not supported in a filter", rest[:len(rest)-len(name)])
+	}
+	return pathOperand{}, p.unexpected("a literal or a query")
+}
…… 其余 5,878 行从略（共改动 35 个文件）