abelien-harness 0.18.0 → 0.19.0

package/skills/abelien-clarify/schemas/skill-reply.v1.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://git.abelien.cn/abelien/abelienharness/skills/abelien-clarify/schemas/skill-reply.v1.json",
+  "title": "clarify SkillResult reply",
+  "description": "clarify 模型回复契约（CLR-1）：与 skill-result.v1.json 同形，但 limits 只写 dimensions，不写 envelope；定稿代码核对引文出现在用户原话里，用共用求值核心换算出 envelope，得到 skill-result.v1.json 的完整快照。",
+  "type": "object",
+  "required": [],
+  "properties": {
+    "result": {
+      "allOf": [
+        {
+          "$ref": "skill-result.v1.json#/$defs/ReplyRequirements"
+        },
+        {
+          "required": [
+            "intent"
+          ]
+        }
+      ]
+    },
+    "questions": {
+      "type": "array",
+      "items": {
+        "$ref": "skill-result.v1.json#/$defs/Question"
+      },
+      "maxItems": 3
+    },
+    "note": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    }
+  },
+  "additionalProperties": false,
+  "anyOf": [
+    {
+      "required": [
+        "result"
+      ]
+    },
+    {
+      "required": [
+        "questions"
+      ],
+      "properties": {
+        "questions": {
+          "minItems": 1
+        }
+      }
+    },
+    {
+      "required": [
+        "note"
+      ]
+    }
+  ]
+}

package/skills/abelien-clarify/schemas/skill-result.v1.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://git.abelien.cn/abelien/abelienharness/skills/abelien-clarify/schemas/skill-result.v1.json",
   "title": "clarify SkillResult",
-  "description": "现行 clarify 完整快照契约；来源、稳定ID、系统假设 note 与 Envelope 算术由同包只读校验器复核。",
+  "description": "clarify 完整快照契约（定稿后的形状）：limits 的 envelope 只能由代码按 dimensions 的引文换算得出（CLR-1），两者同在同缺；模型回复的形状见 skill-reply.v1.json。来源、稳定ID、系统假设 note 与 Envelope 算术由同包只读校验器复核。",
   "type": "object",
   "required": [],
   "properties": {
@@ -149,6 +149,9 @@
                   "preference"
                 ]
               },
+              "dimensions": {
+                "$ref": "#/$defs/Dimensions"
+              },
               "envelope": {
                 "$ref": "../../abelien-harness/contracts/schemas/cross-domain.v1.json#/$defs/Envelope"
               },
@@ -156,7 +159,16 @@
                 "$ref": "#/$defs/Network"
               }
             },
-            "additionalProperties": false
+            "additionalProperties": false,
+            "description": "需求限制。envelope 是代码从 dimensions 换算出的毫米包络（abelien-clarify/scripts/dimensions.mjs），不是模型写的数；有 dimensions 就有 envelope，反之亦然，校验时按 dimensions 重新换算并要求与 envelope 完全一致。",
+            "dependentRequired": {
+              "dimensions": [
+                "envelope"
+              ],
+              "envelope": [
+                "dimensions"
+              ]
+            }
           }
         }
       },
@@ -258,6 +270,256 @@
         "offline",
         "no_cloud"
       ]
+    },
+    "Dimensions": {
+      "description": "尺寸限制的读法（CLR-1）：模型只给形状和每个边界的来源——用户原话的逐字引文，或系统估算的选择——以及它对应的轴和上下限；毫米数由代码用共用求值核心换算（半径乘 2 也由代码算）。盒体轴 width、depth、height 依次对应 envelope.max_mm 的三个分量；圆柱轴 diameter 或 radius、height；wall 是壁厚。",
+      "type": "object",
+      "required": [
+        "shape",
+        "bounds"
+      ],
+      "properties": {
+        "shape": {
+          "enum": [
+            "box",
+            "cylinder"
+          ]
+        },
+        "bounds": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/DimensionBound"
+          },
+          "minItems": 1,
+          "maxItems": 12
+        }
+      },
+      "additionalProperties": false
+    },
+    "DimensionBound": {
+      "description": "一个尺寸边界。axes：这个数管哪些轴（\"10 厘米见方\"写 width、depth、height 三个）；wall 只能单独出现。bound：max 上限、min 下限、exact 精确（上下限都取它）；wall 用 min（保证的最小壁厚）或 estimate（估算壁厚，只作风险提示）。quote 与 choice 二选一：source=user 的限制只能用 quote。",
+      "type": "object",
+      "required": [
+        "axes",
+        "bound"
+      ],
+      "properties": {
+        "axes": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "width",
+              "depth",
+              "height",
+              "diameter",
+              "radius",
+              "wall"
+            ]
+          },
+          "minItems": 1,
+          "maxItems": 3,
+          "uniqueItems": true
+        },
+        "bound": {
+          "enum": [
+            "max",
+            "min",
+            "exact",
+            "estimate"
+          ]
+        },
+        "quote": {
+          "$ref": "#/$defs/DimensionQuote"
+        },
+        "choice": {
+          "$ref": "#/$defs/DimensionChoice"
+        }
+      },
+      "additionalProperties": false,
+      "oneOf": [
+        {
+          "required": [
+            "quote"
+          ]
+        },
+        {
+          "required": [
+            "choice"
+          ]
+        }
+      ]
+    },
+    "DimensionQuote": {
+      "description": "用户原话的逐字引文（本轮用户消息或卡片答复里的原文，做 NFKC 规范化后比对），由代码从中取量。引文里不止一个数时用 index（从 0 起，数所有的数）指出取第几个。unit 只在取到的数自己没写单位时填（例如\"长 100、宽 80、高 60 毫米\"里的 100），写的是原话里共用的那个单位；数自己写了单位时不许填。",
+      "type": "object",
+      "required": [
+        "text"
+      ],
+      "properties": {
+        "text": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "pattern": "\\S"
+        },
+        "index": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 63
+        },
+        "unit": {
+          "enum": [
+            "um",
+            "mm",
+            "cm",
+            "m",
+            "in",
+            "mil"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "DimensionChoice": {
+      "description": "系统估算：模型的选择，写数值、单位（原样，代码换算成毫米）和依据。只用于 source=system 的限制，换算结果不带硬筛选权限。",
+      "type": "object",
+      "required": [
+        "value",
+        "unit",
+        "basis"
+      ],
+      "properties": {
+        "value": {
+          "type": "number",
+          "minimum": 0
+        },
+        "unit": {
+          "enum": [
+            "um",
+            "mm",
+            "cm",
+            "m",
+            "in",
+            "mil"
+          ]
+        },
+        "basis": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300,
+          "pattern": "\\S"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ReplyRequirements": {
+      "type": "object",
+      "required": [
+        "reaction",
+        "limits"
+      ],
+      "properties": {
+        "context": {
+          "type": "object",
+          "required": [
+            "text",
+            "source"
+          ],
+          "properties": {
+            "text": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "\\S"
+            },
+            "source": {
+              "enum": [
+                "user",
+                "system"
+              ]
+            }
+          },
+          "additionalProperties": false
+        },
+        "intent": {
+          "$ref": "#/$defs/Intent"
+        },
+        "reaction": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "text",
+              "source"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              },
+              "text": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              },
+              "source": {
+                "enum": [
+                  "user",
+                  "system"
+                ]
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "limits": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "text",
+              "source",
+              "strength"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              },
+              "text": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "\\S"
+              },
+              "source": {
+                "enum": [
+                  "user",
+                  "system"
+                ]
+              },
+              "strength": {
+                "enum": [
+                  "hard",
+                  "preference"
+                ]
+              },
+              "dimensions": {
+                "$ref": "#/$defs/Dimensions"
+              },
+              "network": {
+                "$ref": "#/$defs/Network"
+              }
+            },
+            "additionalProperties": false,
+            "description": "模型回复里的限制：尺寸只写 dimensions（引文或系统估算 + 轴 + 上下限），不写 envelope 或任何换算后的毫米数。"
+          }
+        }
+      },
+      "additionalProperties": false,
+      "description": "模型回复里的需求：与 Requirements 同形，只是 limits 不带 envelope（毫米包络由代码从 dimensions 换算）。"
     }
   }
 }

package/skills/abelien-clarify/scripts/check_result.py

@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
-"""Read-only validation and ID-based diff of a clarify SkillResult (Python 3.9+)."""
+"""Read-only validation and ID-based diff of a clarify SkillResult reply (Python 3.9+).
+
+Sizes are limits[].dimensions (quotes or system choices, axes, bounds); the millimetre envelope is computed by the
+runtime from them, so a reply never carries one. This script checks structure only: it does not look the quotes up in
+the user's message or convert units."""
 
 import argparse
 import json
@@ -18,6 +22,10 @@ INTENT_KINDS = ("restore", "create", "modify")
 DEPTHS = ("appearance", "assembly", "functional")
 MAX_FEATURES = 20
 MAX_FEATURE_CHARS = 500
+LENGTH_UNITS = ("um", "mm", "cm", "m", "in", "mil")
+SHAPE_AXES = {"box": ("width", "depth", "height", "wall"), "cylinder": ("diameter", "radius", "height", "wall")}
+BOUNDS = ("max", "min", "exact", "estimate")
+MAX_BOUNDS = 12
 
 
 def nonempty_string(value: Any) -> bool:
@@ -96,6 +104,76 @@ def check_envelope(value: Any, path: str, errors: list) -> None:
                 issue(errors, f"{path}.wall_mm.estimate", "估算壁厚必须有限且不小于保证下界")
 
 
+def check_dimensions(value: Any, path: str, user_limit: bool, errors: list) -> None:
+    """Structure of limits[].dimensions (CLR-1). Quote lookup and unit conversion are code's job in the runtime."""
+    if not object_fields(value, ("shape", "bounds"), (), path, errors):
+        return
+    shape = value.get("shape")
+    if shape not in SHAPE_AXES:
+        issue(errors, f"{path}.shape", "shape 必须是 box 或 cylinder")
+        return
+    bounds = value.get("bounds")
+    if not isinstance(bounds, list) or not 1 <= len(bounds) <= MAX_BOUNDS:
+        issue(errors, f"{path}.bounds", f"必须是 1–{MAX_BOUNDS} 项的数组")
+        return
+    slots = set()
+    for index, bound in enumerate(bounds):
+        location = f"{path}.bounds[{index}]"
+        if not object_fields(bound, ("axes", "bound"), ("quote", "choice"), location, errors):
+            continue
+        axes = bound.get("axes")
+        if (not isinstance(axes, list) or not 1 <= len(axes) <= 3 or len(set(map(str, axes))) != len(axes)
+                or any(axis not in SHAPE_AXES[shape] for axis in axes)):
+            issue(errors, f"{location}.axes", f"必须是 1–3 个不重复的 {shape} 轴：{', '.join(SHAPE_AXES[shape])}")
+            continue
+        if ("wall" in axes or "radius" in axes) and len(axes) > 1:
+            issue(errors, f"{location}.axes", "wall、radius 只能单独出现")
+        kind = bound.get("bound")
+        allowed = ("min", "estimate") if "wall" in axes else ("max", "min", "exact")
+        if kind not in allowed:
+            issue(errors, f"{location}.bound", f"必须是 {' / '.join(allowed)}")
+        for axis in axes:
+            for side in (("max", "min") if kind == "exact" else (kind,)):
+                slot = ("diameter" if axis == "radius" else axis, side)
+                if slot in slots:
+                    issue(errors, f"{location}.axes", f"{slot[0]} 的 {slot[1]} 给了两次")
+                slots.add(slot)
+        if ("quote" in bound) == ("choice" in bound):
+            issue(errors, location, "quote 与 choice 必须二选一")
+            continue
+        if "quote" in bound:
+            quote = bound["quote"]
+            if object_fields(quote, ("text",), ("index", "unit"), f"{location}.quote", errors):
+                if not nonempty_string(quote.get("text")) or len(quote["text"]) > 200:
+                    issue(errors, f"{location}.quote.text", "必须是 1–200 字的逐字引文")
+                if "index" in quote and not (type(quote["index"]) is int and 0 <= quote["index"] <= 63):
+                    issue(errors, f"{location}.quote.index", "必须是 0–63 的整数")
+                if "unit" in quote and quote["unit"] not in LENGTH_UNITS:
+                    issue(errors, f"{location}.quote.unit", f"必须是长度单位：{', '.join(LENGTH_UNITS)}")
+        else:
+            choice = bound["choice"]
+            if user_limit:
+                issue(errors, f"{location}.choice", "source=user 的限制只能引用用户原话；系统估算写在 source=system 的限制里")
+            if object_fields(choice, ("value", "unit", "basis"), (), f"{location}.choice", errors):
+                if not finite_number(choice.get("value"), inclusive=True):
+                    issue(errors, f"{location}.choice.value", "必须是有限非负数")
+                if choice.get("unit") not in LENGTH_UNITS:
+                    issue(errors, f"{location}.choice.unit", f"必须是长度单位：{', '.join(LENGTH_UNITS)}")
+                if not nonempty_string(choice.get("basis")) or len(choice["basis"]) > 300:
+                    issue(errors, f"{location}.choice.basis", "必须写 1–300 字的依据")
+    check_dimension_cover(shape, slots, path, errors)
+
+
+def check_dimension_cover(shape: str, slots: set, path: str, errors: list) -> None:
+    axes = ("width", "depth", "height") if shape == "box" else ("diameter", "height")
+    missing = [axis for axis in axes if (axis, "max") not in slots]
+    if missing:
+        issue(errors, f"{path}.bounds", f"{shape} 需要 {'、'.join(axes)} 的上限，缺 {'、'.join(missing)}；凑不齐就不写 dimensions")
+    mins = [axis for axis in axes if (axis, "min") in slots]
+    if shape == "box" and mins and len(mins) != 3:
+        issue(errors, f"{path}.bounds", "盒体下限要三个轴一起给")
+
+
 def check_features(value: Any, path: str, errors: list) -> None:
     if not isinstance(value, list) or len(value) > MAX_FEATURES:
         issue(errors, path, f"必须是数组，至多 {MAX_FEATURES} 项")
@@ -122,7 +200,8 @@ def check_intent(value: Any, path: str, errors: list) -> None:
         issue(errors, f"{path}.keep", "create 没有来源产品，keep 必须为空")
 
 
-def check_requirements(value: Any, path: str, errors: list, require_intent: bool = False) -> None:
+def check_requirements(value: Any, path: str, errors: list, require_intent: bool = False, reply: bool = False) -> None:
+    """reply=True: a model reply, whose limits carry dimensions only; otherwise stored requirements (envelope comes with dimensions)."""
     if not object_fields(value, ("reaction", "limits"), ("context", "intent"), path, errors):
         return
     if "intent" in value:
@@ -145,7 +224,11 @@ def check_requirements(value: Any, path: str, errors: list, require_intent: bool
         fields = ("id", "text", "source") + (("strength",) if group == "limits" else ())
         for index, entry in enumerate(entries):
             location = f"{path}.{group}[{index}]"
-            if not object_fields(entry, fields, ("envelope", "network") if group == "limits" else (), location, errors):
+            if group == "limits" and reply and "envelope" in entry:
+                issue(errors, f"{location}.envelope", "envelope 由代码按 dimensions 换算，回复只写 dimensions（引文、轴和上下限），不写毫米数")
+                continue
+            optional = (("dimensions", "network") if reply else ("dimensions", "envelope", "network")) if group == "limits" else ()
+            if not object_fields(entry, fields, optional, location, errors):
                 continue
             text_field(entry, "id", location, errors)
             text_field(entry, "text", location, errors)
@@ -156,6 +239,10 @@ def check_requirements(value: Any, path: str, errors: list, require_intent: bool
                 seen_ids.add(entry_id)
             if entry.get("source") not in SOURCES:
                 issue(errors, f"{location}.source", "必须是 user 或 system")
+            if group == "limits" and "dimensions" in entry:
+                check_dimensions(entry["dimensions"], f"{location}.dimensions", entry.get("source") == "user", errors)
+            if group == "limits" and not reply and ("envelope" in entry) != ("dimensions" in entry):
+                issue(errors, location, "envelope 与 dimensions 同在同缺：envelope 由代码按 dimensions 换算")
             if group == "limits" and "envelope" in entry:
                 check_envelope(entry["envelope"], f"{location}.envelope", errors)
             if group == "limits" and "network" in entry and entry["network"] not in NETWORKS:
@@ -189,7 +276,8 @@ def check_questions(value: Any, errors: list) -> None:
 
 
 def requirement_items(requirements: dict) -> dict:
-    """Keys are tuples: an opaque ID can contain any character without collision."""
+    """Keys are tuples: an opaque ID can contain any character without collision.
+    A stored envelope is derived from dimensions, so it is left out of the comparison."""
     items = {}
     if "context" in requirements:
         items[("context", None)] = requirements["context"]
@@ -197,7 +285,7 @@ def requirement_items(requirements: dict) -> dict:
         items[("intent", None)] = requirements["intent"]
     for group in ("reaction", "limits"):
         for entry in requirements[group]:
-            items[(group, entry["id"])] = entry
+            items[(group, entry["id"])] = {key: item for key, item in entry.items() if key != "envelope"}
     return items
 
 
@@ -222,7 +310,7 @@ def validate(proposal: Any, current: Any = None) -> dict:
     if not object_fields(proposal, (), ("result", "questions", "note"), "$", errors):
         return report
     if "result" in proposal:
-        check_requirements(proposal["result"], "$.result", errors, require_intent=True)
+        check_requirements(proposal["result"], "$.result", errors, require_intent=True, reply=True)
     if "questions" in proposal:
         check_questions(proposal["questions"], errors)
     if "note" in proposal:

package/skills/abelien-clarify/scripts/dimensions.mjs

@@ -0,0 +1,141 @@
+// 需求尺寸的代码换算（模型算术 CLR-1）：模型只给用户原话的数值引文（或系统估算的选择）和轴向映射，
+// 毫米包络由这里用共用求值核心换算（英寸、厘米换毫米，半径乘 2），并核对引文确实出现在用户本轮的原话里，
+// 做法同 web clarify.ts 的 withdraw。换算出的 envelope 与 abelien-hardware dimensions.mjs 的 validateEnvelope 同形，
+// 下游硬件选型、骨架照旧只读 envelope。模型回复里不再有任何换算后的毫米数，也没有兼容别名。
+import { canonical } from "../../abelien-harness/contracts/index.mjs";
+import { evaluateFormula, parseQuantities } from "../../abelien-harness/scripts/calc/index.mjs";
+import { validateEnvelope } from "../../abelien-hardware/scripts/dimensions.mjs";
+
+/** 尺寸换算的拒收码；定稿把它们包进 TASK_REPLY_INVALID，details.issues[].code 是这里的码。 */
+export const CLARIFY_DIMENSION_CODES = Object.freeze([
+  "CLARIFY_ENVELOPE_FROM_MODEL", // 模型回复里写了 envelope（毫米数只由代码换算）
+  "CLARIFY_QUOTE_NOT_IN_MESSAGE", // 引文没有逐字出现在本轮用户消息或卡片答复里（沿用的旧边界除外）
+  "CLARIFY_QUOTE_NO_LENGTH", // 引文里取不到唯一一个长度量（没有数、不止一个数却没给 index、index 越界、单位不是长度）
+  "CLARIFY_QUOTE_UNIT", // 数自己写了单位却又填 unit，或裸数没填 unit，或链式尺寸里单位有歧义
+  "CLARIFY_CHOICE_ON_USER_LIMIT", // source=user 的限制用了系统估算的 choice
+  "CLARIFY_DIMENSIONS_MAPPING", // 轴与形状不符、wall 和别的轴混写、上下限不适用于该轴、同一边界给了两次、缺必需的上限
+  "CLARIFY_ENVELOPE_INVALID", // 换算出的包络不成立（下限大于上限、保证壁厚吃掉腔体等）
+  "CLARIFY_ENVELOPE_MISMATCH", // 存下的 envelope 与按 dimensions 重新换算的结果不一致，或两者只有其一
+]);
+const LENGTH_UNITS = new Set(["um", "mm", "cm", "m", "in", "mil"]);
+const AXES = { box: ["width", "depth", "height"], cylinder: ["diameter", "height"] };
+const SHAPE_AXES = { box: new Set(["width", "depth", "height", "wall"]), cylinder: new Set(["diameter", "radius", "height", "wall"]) };
+
+function fail(code, path, message) {
+  throw Object.assign(new Error(`${code} at ${path}: ${message}`), { code: "TASK_REPLY_INVALID", details: { issues: [{ code, path, message }] } });
+}
+const normalize = text => text.normalize("NFKC");
+
+/** 引文 → 带单位的操作数（值仍是原文十进制，换算交给求值核心）。 */
+function quoteOperand(quote, path) {
+  const found = parseQuantities(quote.text);
+  if (!found.length) fail("CLARIFY_QUOTE_NO_LENGTH", `${path}/quote`, `the quote has no number: ${JSON.stringify(quote.text)}`);
+  if (quote.index === undefined && found.length !== 1)
+    fail("CLARIFY_QUOTE_NO_LENGTH", `${path}/quote`, `the quote has ${found.length} numbers (${found.map(item => item.text).join(", ")}); give index to pick one`);
+  const picked = found[quote.index ?? 0];
+  if (!picked) fail("CLARIFY_QUOTE_NO_LENGTH", `${path}/quote/index`, `index ${quote.index} is outside the quote's ${found.length} numbers`);
+  if (picked.ambiguous) fail("CLARIFY_QUOTE_UNIT", `${path}/quote`, `${picked.text} has no unit of its own and its chain mixes units`);
+  const bare = picked.unit === null && picked.unit_text === null && !picked.inherited;
+  if (bare) {
+    if (quote.unit === undefined) fail("CLARIFY_QUOTE_UNIT", `${path}/quote/unit`, `${picked.text} has no unit; give the length unit the user stated for it`);
+    return { value: Number(picked.value), unit: quote.unit, source: { choice: `the user wrote ${picked.text} with the shared unit ${quote.unit}` } };
+  }
+  if (quote.unit !== undefined) fail("CLARIFY_QUOTE_UNIT", `${path}/quote/unit`, `${picked.text} states its own unit; leave unit out`);
+  if (!LENGTH_UNITS.has(picked.unit)) fail("CLARIFY_QUOTE_NO_LENGTH", `${path}/quote`, `${picked.text} is not a length (${picked.unit ?? picked.unit_text})`);
+  return { source: { quote: { text: quote.text, source_id: "user-message", ...(quote.index !== undefined ? { index: quote.index } : {}) } } };
+}
+
+/** 一个边界的毫米数，全部经求值核心（引文取量、单位换算、半径乘 2）。 */
+function boundMillimetres(bound, radius, path) {
+  const operand = bound.quote ? quoteOperand(bound.quote, path) : { value: bound.choice.value, unit: bound.choice.unit, source: { choice: bound.choice.basis } };
+  if (bound.choice && !LENGTH_UNITS.has(bound.choice.unit)) fail("CLARIFY_QUOTE_NO_LENGTH", `${path}/choice/unit`, "the unit must be a length");
+  try {
+    return evaluateFormula({ expression: radius ? "2 * q" : "q", operands: { q: operand }, unit: "mm" }, { resolveQuote: () => true }).value;
+  } catch (error) {
+    fail("CLARIFY_QUOTE_NO_LENGTH", path, `${error.code ?? "CALC"}: ${error.message}`);
+  }
+}
+
+/**
+ * dimensions → envelope。onQuote(quote, path, bound) 核对引文出处（定稿：本轮原话；复核存档：不再核对）；
+ * userLimit 为 true 时只收引文。返回与 validateEnvelope 同形的包络。
+ */
+export function deriveEnvelope(dimensions, { userLimit, onQuote = () => {}, path = "/dimensions" } = {}) {
+  const shape = dimensions?.shape;
+  if (!Object.hasOwn(AXES, shape)) fail("CLARIFY_DIMENSIONS_MAPPING", `${path}/shape`, "shape must be box or cylinder");
+  const slots = new Map();
+  for (const [index, bound] of (dimensions.bounds ?? []).entries()) {
+    const at = `${path}/bounds/${index}`;
+    if (Boolean(bound.quote) === Boolean(bound.choice)) fail("CLARIFY_DIMENSIONS_MAPPING", at, "give exactly one of quote or choice");
+    if (bound.choice && userLimit) fail("CLARIFY_CHOICE_ON_USER_LIMIT", `${at}/choice`, "a source=user limit takes the user's words only; a system estimate belongs to a source=system limit");
+    const axes = bound.axes ?? [];
+    for (const axis of axes) if (!SHAPE_AXES[shape].has(axis)) fail("CLARIFY_DIMENSIONS_MAPPING", `${at}/axes`, `${axis} is not an axis of a ${shape}`);
+    if (axes.includes("wall") && axes.length > 1) fail("CLARIFY_DIMENSIONS_MAPPING", `${at}/axes`, "wall stands alone");
+    if (axes.includes("wall") ? !["min", "estimate"].includes(bound.bound) : !["max", "min", "exact"].includes(bound.bound))
+      fail("CLARIFY_DIMENSIONS_MAPPING", `${at}/bound`, axes.includes("wall") ? "a wall takes min or estimate" : "a size takes max, min or exact");
+    if (bound.quote) onQuote(bound.quote, `${at}/quote`, bound);
+    const radius = axes.includes("radius");
+    if (radius && axes.length > 1) fail("CLARIFY_DIMENSIONS_MAPPING", `${at}/axes`, "radius stands alone");
+    const mm = boundMillimetres(bound, radius, at);
+    for (const axis of axes) for (const kind of bound.bound === "exact" ? ["max", "min"] : [bound.bound]) {
+      const key = `${radius ? "diameter" : axis}:${kind}`;
+      if (slots.has(key)) fail("CLARIFY_DIMENSIONS_MAPPING", `${at}/axes`, `${key} is given twice`);
+      slots.set(key, mm);
+    }
+  }
+  const get = (axis, kind) => slots.get(`${axis}:${kind}`);
+  const missing = AXES[shape].filter(axis => get(axis, "max") === undefined);
+  if (missing.length) fail("CLARIFY_DIMENSIONS_MAPPING", `${path}/bounds`, `a ${shape} needs an upper bound on ${AXES[shape].join(", ")}; missing ${missing.join(", ")}`);
+  const mins = AXES[shape].filter(axis => get(axis, "min") !== undefined);
+  let envelope;
+  if (shape === "box") {
+    if (mins.length && mins.length !== 3) fail("CLARIFY_DIMENSIONS_MAPPING", `${path}/bounds`, "a box lower bound needs width, depth and height together");
+    envelope = { shape, max_mm: AXES.box.map(axis => get(axis, "max")), ...(mins.length ? { min_mm: AXES.box.map(axis => get(axis, "min")) } : {}) };
+  } else {
+    envelope = { shape, max_diameter_mm: get("diameter", "max"), max_height_mm: get("height", "max"),
+      ...(get("diameter", "min") !== undefined ? { min_diameter_mm: get("diameter", "min") } : {}),
+      ...(get("height", "min") !== undefined ? { min_height_mm: get("height", "min") } : {}) };
+  }
+  const wallMin = get("wall", "min"), wallEstimate = get("wall", "estimate");
+  // 没写保证壁厚时按 0（契约原有口径），估算只作风险提示。
+  if (wallMin !== undefined || wallEstimate !== undefined) envelope.wall_mm = { minimum: wallMin ?? 0, ...(wallEstimate !== undefined ? { estimate: wallEstimate } : {}) };
+  try { validateEnvelope(envelope); }
+  catch (error) { fail("CLARIFY_ENVELOPE_INVALID", path, `${error.message}; derived ${canonical(envelope)}`); }
+  return envelope;
+}
+
+const boundKey = bound => canonical(bound);
+
+/**
+ * 定稿：把模型回复里的需求补成完整快照。每个带 dimensions 的限制由代码换算出 envelope；
+ * 新写或改动的引文必须逐字出现在 userTexts（本轮用户消息与卡片答复）里，与当前需求同 ID 同形状里原样沿用的边界不再核对。
+ */
+export function completeRequirements(result, { current = null, userTexts = [] } = {}) {
+  const words = userTexts.filter(text => typeof text === "string").map(normalize);
+  const priorLimits = new Map((current?.limits ?? []).map(item => [item.id, item]));
+  const completed = structuredClone(result);
+  for (const [index, limit] of completed.limits.entries()) {
+    const path = `/result/limits/${index}`;
+    if (Object.hasOwn(limit, "envelope")) fail("CLARIFY_ENVELOPE_FROM_MODEL", `${path}/envelope`, "write dimensions (quotes, axes, bounds); the millimetre envelope is computed by code");
+    if (limit.dimensions === undefined) continue;
+    const prior = priorLimits.get(limit.id)?.dimensions;
+    const carried = new Set(prior?.shape === limit.dimensions.shape ? prior.bounds.map(boundKey) : []);
+    limit.envelope = deriveEnvelope(limit.dimensions, { userLimit: limit.source === "user", path: `${path}/dimensions`,
+      onQuote: (quote, at, bound) => {
+        if (carried.has(boundKey(bound))) return;
+        if (!words.some(text => text.includes(normalize(quote.text))))
+          fail("CLARIFY_QUOTE_NOT_IN_MESSAGE", at, `${JSON.stringify(quote.text)} is not word for word in this turn's user message or card answer`);
+      } });
+  }
+  return completed;
+}
+
+/** 复核存档：envelope 与 dimensions 同在同缺，且 envelope 等于按 dimensions 重新换算的结果（不再核对引文出处）。 */
+export function checkStoredEnvelope(limit, path) {
+  const has = [Object.hasOwn(limit, "envelope"), Object.hasOwn(limit, "dimensions")];
+  if (has[0] !== has[1]) fail("CLARIFY_ENVELOPE_MISMATCH", path, "envelope and dimensions come together: the envelope is derived from dimensions");
+  if (!has[0]) return;
+  const derived = deriveEnvelope(limit.dimensions, { userLimit: limit.source === "user", path: `${path}/dimensions` });
+  if (canonical(derived) !== canonical(limit.envelope))
+    fail("CLARIFY_ENVELOPE_MISMATCH", `${path}/envelope`, `the stored envelope ${canonical(limit.envelope)} is not the one its dimensions give (${canonical(derived)})`);
+}