abelien-harness 0.5.0 → 0.6.0

package/skills/abelien-reference/fixtures/restore.final.json

@@ -0,0 +1,267 @@
+{
+  "budget": {
+    "images": 1,
+    "pages": 2,
+    "queries": 1
+  },
+  "changeable": [],
+  "depth": "assembly",
+  "id": "ref-40ece5312c4ecbf6-fd2b162cb",
+  "images": [
+    {
+      "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+      "id": "i1",
+      "measurement": {
+        "aspect_h_over_w": 1.8188,
+        "background": {
+          "mode": "color",
+          "rgb": [
+            255,
+            255,
+            255
+          ]
+        },
+        "bbox": {
+          "height": 502,
+          "width": 276,
+          "x": 62,
+          "y": 49
+        },
+        "image": {
+          "height": 600,
+          "width": 400
+        },
+        "method": "silhouette-v1",
+        "status": "measured"
+      },
+      "media_type": "image/png",
+      "page_id": "p1",
+      "reason": null,
+      "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11",
+      "status": "read",
+      "url": "https://img.example.com/pro.png"
+    }
+  ],
+  "intent": "restore",
+  "items": [
+    {
+      "id": "u1",
+      "image": {
+        "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+        "media_type": "image/png",
+        "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11"
+      },
+      "kind": "user_input",
+      "query": null,
+      "role": "帮我根据图片还原小爱音箱",
+      "source": null,
+      "status": "ready",
+      "title": "你的输入",
+      "verdict": null
+    },
+    {
+      "id": "p1",
+      "image": {
+        "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+        "media_type": "image/png",
+        "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11"
+      },
+      "kind": "candidate",
+      "query": "Xiaomi XiaoAI speaker Pro dimensions",
+      "role": "候选产品",
+      "source": {
+        "site": "www.mi.example.com",
+        "url": "https://www.mi.example.com/pro/specs"
+      },
+      "status": "ready",
+      "title": "小爱音箱 Pro",
+      "verdict": {
+        "code": "closest",
+        "basis": "选定为「小爱音箱 Pro」；实测高宽比 1.8188，规格 1.822，相差 0.2%"
+      }
+    },
+    {
+      "id": "p2",
+      "image": null,
+      "kind": "candidate",
+      "query": "Xiaomi XiaoAI speaker Pro dimensions",
+      "role": "候选产品",
+      "source": {
+        "site": "www.mi.example.com",
+        "url": "https://www.mi.example.com/gen1/specs"
+      },
+      "status": "ready",
+      "title": "小米AI音箱",
+      "verdict": {
+        "code": "ratio_mismatch",
+        "basis": "实测高宽比 1.8188，规格 2.4045，相差 24.4%"
+      }
+    },
+    {
+      "id": "sp1",
+      "kind": "spec",
+      "title": "外形尺寸",
+      "role": "Ø118 × 215 mm（引自 p1）",
+      "source": {
+        "url": "https://www.mi.example.com/pro/specs",
+        "site": "www.mi.example.com"
+      },
+      "image": null,
+      "verdict": null,
+      "status": "ready",
+      "query": null
+    }
+  ],
+  "keep": [
+    "外形尺寸与比例"
+  ],
+  "pages": [
+    {
+      "excerpt": "小爱音箱 Pro 参数 产品尺寸：118 × 118 × 215 mm，重量 1187 g。",
+      "final_url": "https://www.mi.example.com/pro/specs",
+      "id": "p1",
+      "image_url": "https://img.example.com/pro.png",
+      "purpose": "identify",
+      "raw_sha256": "109cbac90dd51ef3dddfd21c4a97168a25f097b4211b2146d21669281d06e3b8",
+      "reason": null,
+      "search_id": "s1",
+      "status": "read",
+      "text_blob_ref": "sha256:a9d6a6d8668de3346efe1d94c1afd76e71faf37bee5a6e55d3a82f9bc60b9bf0",
+      "text_sha256": "bae09c2d8ac69290d90e7cf69d7809858b1149a391400d40030037db41896415",
+      "title": "小爱音箱 Pro 参数",
+      "url": "https://www.mi.example.com/pro/specs"
+    },
+    {
+      "excerpt": "小米AI音箱 规格 尺寸 88 mm × 88 mm × 211.6 mm",
+      "final_url": "https://www.mi.example.com/gen1/specs",
+      "id": "p2",
+      "image_url": null,
+      "purpose": "identify",
+      "raw_sha256": "c139f165c41dc34c2cd30a816a80d7cbef9ecbda49e7496d46163c8692da33c7",
+      "reason": null,
+      "search_id": "s1",
+      "status": "read",
+      "text_blob_ref": "sha256:3dd43ad1e906a2e95af747cc8f8386c00b43df981af8b8bafe45bb2d173e7e3c",
+      "text_sha256": "2de9e3c9406bd62a2e9eef887fd42008382616377ac49fb751cd5a109f1e9a00",
+      "title": "小米AI音箱 规格",
+      "url": "https://www.mi.example.com/gen1/specs"
+    }
+  ],
+  "request_digest": "40ece5312c4ecbf6f5548d36589de25734706b8a333d22e1a3c32adeb75e09f5",
+  "schema": "abelien.reference-evidence.v1",
+  "searches": [
+    {
+      "count": 5,
+      "error_code": null,
+      "id": "s1",
+      "purpose": "identify",
+      "query": "Xiaomi XiaoAI speaker Pro dimensions",
+      "receipt_sha256": "099206543e4389fde6c4838d3fc0b125dce0fb98cd57384db3062e1abcede7a8",
+      "request_id": "req-[redacted]",
+      "results": [
+        {
+          "rank": 1,
+          "snippet": "",
+          "title": "XiaoAI Speaker Pro",
+          "url": "https://www.mi.example.com/pro/specs"
+        },
+        {
+          "rank": 2,
+          "snippet": "",
+          "title": "Mi AI Speaker",
+          "url": "https://www.mi.example.com/gen1/specs"
+        }
+      ],
+      "status": "completed"
+    }
+  ],
+  "status": "final",
+  "text": "帮我根据图片还原小爱音箱",
+  "unknowns": [],
+  "user_image": {
+    "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+    "measurement": {
+      "aspect_h_over_w": 1.8188,
+      "background": {
+        "mode": "color",
+        "rgb": [
+          255,
+          255,
+          255
+        ]
+      },
+      "bbox": {
+        "height": 502,
+        "width": 276,
+        "x": 62,
+        "y": 49
+      },
+      "image": {
+        "height": 600,
+        "width": 400
+      },
+      "method": "silhouette-v1",
+      "status": "measured"
+    },
+    "media_type": "image/png",
+    "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11"
+  },
+  "collected_id": "ref-40ece5312c4ecbf6",
+  "judgement_digest": "d2b162cb00ce8cc52049f321226a89e4e0328b55d54fb022fb4a4539088882c0",
+  "identity": {
+    "candidates": [
+      {
+        "item_id": "p1",
+        "name": "小爱音箱 Pro",
+        "dimensions_mm": {
+          "width": 118,
+          "depth": 118,
+          "height": 215
+        },
+        "quote": {
+          "page_id": "p1",
+          "text": "产品尺寸：118 × 118 × 215 mm"
+        },
+        "ratio_check": {
+          "status": "consistent",
+          "measured": 1.8188,
+          "spec": 1.822,
+          "relative_error": 0.0018,
+          "tolerance": 0.1
+        }
+      },
+      {
+        "item_id": "p2",
+        "name": "小米AI音箱",
+        "dimensions_mm": {
+          "width": 88,
+          "depth": 88,
+          "height": 211.6
+        },
+        "quote": {
+          "page_id": "p2",
+          "text": "尺寸 88 mm × 88 mm × 211.6 mm"
+        },
+        "ratio_check": {
+          "status": "mismatch",
+          "measured": 1.8188,
+          "spec": 2.4045,
+          "relative_error": 0.2436,
+          "tolerance": 0.1
+        }
+      }
+    ],
+    "chosen_item_id": "p1",
+    "conflict": null
+  },
+  "similar": [],
+  "spec_quotes": [
+    {
+      "id": "sp1",
+      "quote": {
+        "page_id": "p1",
+        "text": "118 × 118 × 215 mm"
+      }
+    }
+  ]
+}

package/skills/abelien-reference/references/research-contract.md

@@ -0,0 +1,74 @@
+# 参考研究契约（reference.research / reference.finalize）
+
+本文是 `abelien-reference` 两个 capability 的输入、输出、上限与错误码的正文。数据格式以 `schemas/reference-evidence.v1.json` 为准，样例见 `fixtures/`；判定逻辑在 `scripts/` 中，并有测试覆盖。
+
+## reference.research
+
+### 输入
+
+只接受下列字段，出现其他字段一律 `VALIDATION`：
+
+| 字段 | 规则 |
+| --- | --- |
+| `intent` | `restore` / `create` / `modify`，取自需求的 `intent.kind`（clarify 判定） |
+| `keep` / `changeable` | 保留项与可改项，各最多 20 条，每条 1–500 字 |
+| `depth` | `appearance` / `assembly` / `functional`，或 `null` |
+| `text` | 用户原话，1–4000 字 |
+| `links` | 最多 5 个公开 HTTPS 链接，不得带凭据或指向内网 |
+| `user_image` | 可选，`{media_type: "image/png", base64}`，不超过 16MB；其他格式由宿主先转成 PNG |
+| `plan.queries` | 最多 6 条，每条为 `{purpose: identify / teardown / similar, query, count?: 1–5}` |
+| `plan.max_pages` / `plan.max_images` | 页面最多读几页（0–12，默认 8）、主图最多抓几张（0–8，默认 6） |
+
+### 执行
+
+- **检索**：只用宿主环境变量 `WEB_SEARCH_API_KEY` 调 Volc。原始回执先脱敏，再计算摘要。单条检索失败时，该条记为 `failed`，并写明错误码，其余照常进行；缺少 key 时，在发出任何请求之前就以 `REFERENCE_WEB_CONFIG` 失败。
+- **页面**：先读链接，再从各条检索结果中轮流取页面，避免某一条检索占满读取预算。读取只走内核的安全直读：只读公网 HTTPS，每一跳都重新解析并钉住地址，限制重定向次数。每页最多读 8MB，超出时记为 `too_large`、不可用。正文存为内容 blob，资源里只保留前 1200 字的摘录。
+- **主图**：取页面的 `og:image`、`twitter:image` 或 `image_src`。图片同样走钉住地址的直读，每张不超过 4MB，只接受 PNG、JPEG、WebP，原始字节存为内容 blob。其中的 PNG 会额外测量轮廓。
+- **用户原图**：存为内容 blob 并测量轮廓（`silhouette-v1`），得到包围盒和高宽比；背景必须是单色或透明。背景杂乱、没有主体、隔行 PNG、超大图都记为 `unknown`，并写明原因。
+- **幂等**：结果 id 由完整请求摘要（包括原图哈希）派生。已有同 id 的收集结果时直接返回，不再检索、不再读取。因此单条检索或页面的临时失败不会因为原样重试而自动恢复；要重试，就改写检索计划（比如换个检索词、改结果数），形成新的请求。
+
+### 输出
+
+输出 `reference-evidence`，status=collected。`items` 中第一项是 `user_input`，其后每个页面对应一格：识别用途为 `candidate`，逆向用途为 `teardown`，相似用途为 `similar`。读不到的页面状态为 `unavailable`。此时还没有任何 `verdict`。
+
+## reference.finalize
+
+### 输入
+
+| 字段 | 规则 |
+| --- | --- |
+| `evidence_id` | 必须指向一份 status=collected 的 `reference-evidence:ref-…` |
+| `identity` | 可选，`{candidates: [{item_id, name, dimensions_mm?: {width, depth?, height}, quote: {page_id, text}}], chosen_item_id}`，最多 6 个候选；只要有候选，`chosen_item_id` 就必须是其中之一。引用是必填的识别依据；页面没有给出尺寸时，可以不填 `dimensions_mm`，此时比例记为未核对 |
+| `similar` | 可选，最多 12 条，每条为 `{item_id, decision: borrow / skip, borrowed?, why, not_copied?}`；`borrow` 时必须写明 `borrowed` |
+| `excluded` | 可选，最多 12 条，每条为 `{item_id, reason}` |
+| `specs` | 可选，最多 12 条，每条为 `{title, value, quote}`，生成 `spec` 格 |
+
+### 核验
+
+- 引用经过空白归一后，必须逐字出现在该页已保存的正文里。只能引用读取成功的页面。
+- 给出尺寸时，宽、高（以及给出时的深）这些数字必须都出现在引用里；没给尺寸时，比例核对为 `unknown`（`no_dimensions`），并写入 `unknowns`。
+- 条目种类必须匹配：候选必须是 `candidate` 格，相似必须是 `similar` 格；排除不能作用于 `user_input`。
+
+### 判定（确定性）
+
+- 正面视角下，比较高宽比：规格比例为 `height / width`，与用户原图的实测值比较，相对误差不超过 10% 记为 `consistent`，否则记为 `mismatch`；没有测量或缺尺寸时记为 `unknown`。
+- 所选候选：比例一致或无法核对时，判定为 `closest`，依据中写明比例情况；比例不符时，判定为 `ratio_mismatch`，并在 `identity.conflict` 中写明。
+- 其他候选：比例不符时判定为 `ratio_mismatch`，其余不加判定，仍保留为候选，供用户切换。
+- 相似产品：`borrow` 判定为 `borrowed`，依据中写明借用了什么、原因、哪些不照搬；`skip` 判定为 `not_copied`。
+- 排除项：状态改为 `excluded`，判定为 `excluded`。
+- 同一份收集结果可以多次提交不同判断，每次生成一份新的 final 结果（id 带判断摘要），收集结果本身不变。
+
+## 错误码
+
+| 码 | 含义 |
+| --- | --- |
+| `VALIDATION` | 输入不合规、引用不在原文、尺寸不在引用中、条目种类不符 |
+| `REFERENCE_WEB_CONFIG` | 缺少 `WEB_SEARCH_API_KEY`，或 DNS 配置非法 |
+| `REFERENCE_WEB_*` | 单条检索、读取的失败码，只记在对应的检索、页面或图片里，不使整次运行失败 |
+| `REFERENCE_HOST` | 宿主没有提供可信的资源读取、内容读写端口 |
+
+## 宿主责任
+
+- 把上传的图片转成 PNG，写入作品目录中的输入文件，再用 `--input-file` 传入。
+- 只展示 `items` 和 `unknowns`；`verdict` 原样展示，不重新解释，也不改写。
+- 第三方图片从内容 blob 转存到私有存储，展示时附来源，不进入图鉴或公开分享。

package/skills/abelien-reference/schemas/reference-evidence.v1.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://git.abelien.cn/abelien/abelienharness/skills/abelien-reference/schemas/reference-evidence.v1.json",
+  "title": "abelien.reference-evidence.v1",
+  "description": "参考研究证据。status=collected 由 reference.research 产出，只有收集结果；status=final 由 reference.finalize 产出，带核验过的识别、相似产品与判定。宿主只展示与转存，不自行改写判定。",
+  "type": "object",
+  "required": ["id", "schema", "status", "intent", "keep", "changeable", "depth", "text", "user_image", "searches", "pages", "images", "items", "unknowns"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^ref-[0-9a-f]{16}(-f[0-9a-f]{8})?$" },
+    "schema": { "const": "abelien.reference-evidence.v1" },
+    "status": { "enum": ["collected", "final"] },
+    "request_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "intent": { "enum": ["restore", "create", "modify"] },
+    "keep": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "changeable": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "depth": { "enum": ["appearance", "assembly", "functional", null] },
+    "text": { "type": "string", "minLength": 1 },
+    "user_image": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["blob_ref", "sha256", "media_type", "measurement"],
+          "properties": {
+            "blob_ref": { "$ref": "#/$defs/blobRef" },
+            "sha256": { "$ref": "#/$defs/sha256" },
+            "media_type": { "const": "image/png" },
+            "measurement": { "$ref": "#/$defs/measurement" }
+          }
+        }
+      ]
+    },
+    "searches": { "type": "array", "items": { "$ref": "#/$defs/search" } },
+    "pages": { "type": "array", "items": { "$ref": "#/$defs/page" } },
+    "images": { "type": "array", "items": { "$ref": "#/$defs/image" } },
+    "items": { "type": "array", "items": { "$ref": "#/$defs/item" } },
+    "unknowns": { "type": "array", "items": { "type": "string" } },
+    "collected_id": { "type": "string", "description": "status=final 时为来源收集结果的 id" },
+    "judgement_digest": { "type": "string" },
+    "identity": {
+      "description": "status=final；还原与改现成时为识别判断，新创时为 null",
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["candidates", "chosen_item_id", "conflict"],
+          "properties": {
+            "candidates": { "type": "array", "items": { "$ref": "#/$defs/candidate" } },
+            "chosen_item_id": { "type": ["string", "null"] },
+            "conflict": { "type": ["string", "null"] }
+          }
+        }
+      ]
+    },
+    "similar": { "type": "array", "items": { "$ref": "#/$defs/similar" } }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "blobRef": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "measurement": {
+      "type": "object",
+      "required": ["status", "method"],
+      "properties": {
+        "status": { "enum": ["measured", "unknown"] },
+        "method": { "const": "silhouette-v1" },
+        "reason": { "type": "string" },
+        "aspect_h_over_w": { "type": "number" },
+        "bbox": { "type": "object" },
+        "background": { "type": "object" }
+      }
+    },
+    "search": {
+      "type": "object",
+      "required": ["id", "purpose", "query", "count", "status", "results"],
+      "properties": {
+        "purpose": { "enum": ["identify", "teardown", "similar"] },
+        "status": { "enum": ["completed", "failed"] },
+        "error_code": { "type": ["string", "null"] },
+        "results": { "type": "array", "items": { "type": "object", "required": ["rank", "url", "title"] } }
+      }
+    },
+    "page": {
+      "type": "object",
+      "required": ["id", "url", "purpose", "status"],
+      "properties": {
+        "status": { "enum": ["read", "unavailable"] },
+        "text_blob_ref": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/blobRef" }] },
+        "excerpt": { "type": "string" },
+        "image_url": { "type": ["string", "null"] }
+      }
+    },
+    "image": {
+      "type": "object",
+      "required": ["id", "url", "page_id", "status"],
+      "properties": {
+        "status": { "enum": ["read", "unavailable"] },
+        "blob_ref": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/blobRef" }] },
+        "media_type": { "type": ["string", "null"] }
+      }
+    },
+    "verdict": {
+      "type": "object",
+      "required": ["code", "basis"],
+      "properties": {
+        "code": { "enum": ["closest", "ratio_mismatch", "excluded", "borrowed", "not_copied", "fits", "envelope"] },
+        "basis": { "type": "string", "minLength": 1 }
+      }
+    },
+    "item": {
+      "type": "object",
+      "description": "画布网格中的一格。verdict 只由 reference.finalize 的确定性检查给出。",
+      "required": ["id", "kind", "title", "role", "source", "image", "verdict", "status", "query"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["user_input", "candidate", "teardown", "spec", "similar"] },
+        "title": { "type": "string" },
+        "role": { "type": "string" },
+        "source": { "oneOf": [{ "type": "null" }, { "type": "object", "required": ["url", "site"], "properties": { "url": { "type": "string" }, "site": { "type": "string" } } }] },
+        "image": { "oneOf": [{ "type": "null" }, { "type": "object", "required": ["blob_ref", "sha256", "media_type"], "properties": { "blob_ref": { "$ref": "#/$defs/blobRef" }, "sha256": { "$ref": "#/$defs/sha256" }, "media_type": { "type": "string" } } }] },
+        "verdict": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/verdict" }] },
+        "status": { "enum": ["pending", "ready", "excluded", "unavailable"] },
+        "query": { "type": ["string", "null"], "description": "pending 时为真实检索词" }
+      }
+    },
+    "candidate": {
+      "type": "object",
+      "required": ["item_id", "name", "dimensions_mm", "quote", "ratio_check"],
+      "properties": {
+        "dimensions_mm": { "description": "页面未给尺寸时为 null，此时比例核对为 unknown", "oneOf": [{ "type": "null" }, { "type": "object", "required": ["width", "height"] }] },
+        "quote": { "type": "object", "required": ["page_id", "text"] },
+        "ratio_check": { "type": "object", "required": ["status"], "properties": { "status": { "enum": ["consistent", "mismatch", "unknown"] } } }
+      }
+    },
+    "similar": {
+      "type": "object",
+      "required": ["item_id", "decision", "why"],
+      "properties": { "decision": { "enum": ["borrow", "skip"] } }
+    }
+  }
+}

package/skills/abelien-reference/scripts/evidence.mjs

@@ -0,0 +1,60 @@
+// reference-evidence v1 的唯一字段定义与校验（P2-13.04）。schemas/reference-evidence.v1.json 与本文件的枚举保持一致，
+// 由测试核对；宿主据 schema 与 fixtures 做契约测试，不自行解释字段含义。
+import { createPublicReader } from "../../abelien-harness/scripts/web/public-read.mjs";
+import { createVolcSearch } from "../../abelien-harness/scripts/web/volc.mjs";
+import { redact } from "../../abelien-harness/scripts/web/redact.mjs";
+import { failure, text, record } from "../../abelien-harness/scripts/web/common.mjs";
+
+export const SCHEMA = "abelien.reference-evidence.v1";
+export const INTENTS = Object.freeze(["restore", "create", "modify"]);
+export const DEPTHS = Object.freeze(["appearance", "assembly", "functional"]);
+export const PURPOSES = Object.freeze(["identify", "teardown", "similar"]);
+export const ITEM_KINDS = Object.freeze(["user_input", "candidate", "teardown", "spec", "similar"]);
+export const ITEM_STATUSES = Object.freeze(["pending", "ready", "excluded", "unavailable"]);
+export const VERDICT_CODES = Object.freeze(["closest", "ratio_mismatch", "excluded", "borrowed", "not_copied", "fits", "envelope"]);
+export const EVIDENCE_STATUSES = Object.freeze(["collected", "final"]);
+export const KIND_BY_PURPOSE = Object.freeze({ identify: "candidate", teardown: "teardown", similar: "similar" });
+
+export const LIMITS = Object.freeze({ queries: 6, count: 5, pages: 12, images: 8, links: 5, textChars: 4000, queryChars: 200,
+  pageBytes: 8 * 1024 * 1024, imageBytes: 4 * 1024 * 1024, userImageBytes: 16 * 1024 * 1024, excerptChars: 1200, pageTimeoutMs: 30000, searchTimeoutMs: 30000, concurrency: 4 });
+
+export const CODES = Object.freeze({ transport: "REFERENCE_WEB_TRANSPORT", dns: "REFERENCE_WEB_DNS", access: "REFERENCE_WEB_URL", redirect: "REFERENCE_WEB_PAGE",
+  timeout: "REFERENCE_WEB_TIMEOUT", url: "REFERENCE_WEB_URL", config: "REFERENCE_WEB_CONFIG", readTimeout: "REFERENCE_PUBLIC_READ_TIMEOUT",
+  capability: "REFERENCE_WEB_CAPABILITY", provider: "REFERENCE_WEB_PROVIDER", auth: "REFERENCE_WEB_AUTH", rateLimit: "REFERENCE_WEB_RATE_LIMIT", response: "REFERENCE_WEB_RESPONSE" });
+
+export const reader = createPublicReader({ codes: CODES, userAgent: "Abelien-Reference-Evidence/1", accept: "text/html,text/plain,application/xhtml+xml", decodeCharset: true });
+export const imageReader = createPublicReader({ codes: CODES, userAgent: "Abelien-Reference-Evidence/1", accept: "image/png,image/jpeg,image/webp" });
+export const volc = createVolcSearch({ codes: CODES, ownsError: error => Boolean(error?.code?.startsWith("REFERENCE_WEB_")),
+  redact: (raw, env = {}) => redact(raw, [env.WEB_SEARCH_API_KEY].filter(text)), timeoutMessage: "reference network request timed out" });
+
+export const invalid = message => { throw failure("VALIDATION", message); };
+export const stringList = (value, label, max = 20) => {
+  if (!Array.isArray(value) || value.length > max || value.some(item => !text(item) || item.length > 500)) invalid(`${label} must be a list of up to ${max} non-empty strings`);
+  return value.map(item => item.trim());
+};
+export const site = url => { try { return new URL(url).hostname; } catch { return null; } };
+
+function checkItem(item, index) {
+  const at = `items[${index}]`;
+  if (!record(item) || !text(item.id) || !ITEM_KINDS.includes(item.kind) || !ITEM_STATUSES.includes(item.status) || typeof item.title !== "string" || typeof item.role !== "string") invalid(`${at} has invalid id, kind, status, title or role`);
+  if (item.source !== null && !(record(item.source) && text(item.source.url) && typeof item.source.site === "string")) invalid(`${at}.source must be null or {url, site}`);
+  if (item.image !== null && !(record(item.image) && /^sha256:[0-9a-f]{64}$/.test(item.image.blob_ref ?? "") && /^[0-9a-f]{64}$/.test(item.image.sha256 ?? "") && text(item.image.media_type))) invalid(`${at}.image must be null or {blob_ref, sha256, media_type}`);
+  if (item.verdict !== null && !(record(item.verdict) && VERDICT_CODES.includes(item.verdict.code) && text(item.verdict.basis))) invalid(`${at}.verdict must be null or {code, basis}`);
+  if (item.query !== null && typeof item.query !== "string") invalid(`${at}.query must be null or a string`);
+}
+
+/** Strict structural check of a reference-evidence v1 body; returns the body. */
+export function validateEvidence(body) {
+  if (!record(body) || body.schema !== SCHEMA || !text(body.id) || !EVIDENCE_STATUSES.includes(body.status)) invalid("not a reference-evidence v1 body");
+  if (!INTENTS.includes(body.intent) || (body.depth !== null && !DEPTHS.includes(body.depth))) invalid("intent or depth is invalid");
+  stringList(body.keep, "keep"); stringList(body.changeable, "changeable"); stringList(body.unknowns, "unknowns", 200);
+  for (const name of ["searches", "pages", "images", "items"]) if (!Array.isArray(body[name])) invalid(`${name} must be an array`);
+  body.items.forEach(checkItem);
+  const ids = body.items.map(item => item.id); if (new Set(ids).size !== ids.length) invalid("item ids must be unique");
+  if (body.status === "final") {
+    if (!record(body.identity) && body.identity !== null) invalid("identity must be null or an object");
+    if (!Array.isArray(body.similar)) invalid("similar must be an array");
+    if (!text(body.collected_id)) invalid("final evidence must name its collected_id");
+  }
+  return body;
+}