abelien-harness 0.3.0 → 0.5.0

package/skills/abelien-hardware/domain.json

@@ -1,7 +1,7 @@
 {
   "name": "abelien-hardware",
-  "version": "1.1.0",
-  "description": "Hardware library recall, fixed Prismer-first/Volc fallback evidence and envelope candidates; formal selection remains hardware.select",
+  "version": "1.3.0",
+  "description": "Hardware library recall, English Volc query and source evidence (Prismer off by default) with envelope candidates; formal selection remains hardware.select",
   "resources": [
     "hardware-recall",
     "hardware-proposal",
@@ -13,7 +13,7 @@
   ],
   "capabilities": {
     "hardware.search": {
-      "description": "按三级功能槽位读取 TOS 压缩分类索引并只下载 Top-K Wiki，返回供 Agent 语义比较的完整候选页",
+      "description": "按三级功能槽位读取 TOS 压缩分类索引，先保守尺寸筛选再下载 Top-K Wiki，返回供 Agent 语义比较的完整候选页",
       "adapter": {
         "type": "module",
         "path": "scripts/tos-wiki-search.mjs",
@@ -155,7 +155,7 @@
       "produces": "hardware-selection"
     },
     "hardware.web-search": {
-      "description": "Fixed Prismer-first/Volc fallback, safe source evidence and original-task recovery",
+      "description": "English Volc query and direct source reads (Prismer switchable, off by default), safe source evidence and original-task recovery",
       "adapter": {
         "type": "module",
         "path": "scripts/web-search.mjs",

package/skills/abelien-hardware/references/search-index-format.md

@@ -1,6 +1,6 @@
 # 硬件 Wiki 分类索引格式
 
-本文件只在发布、校验或迁移 TOS 硬件 Wiki 搜索索引时读取。完整 Wiki 仍是型号事实与选型证据源；索引只负责在下载正文前缩小候选，不替代 Wiki。
+本文件只在发布、校验或迁移 TOS 硬件 Wiki 搜索索引时读取。完整 Wiki 是型号选型证据；尺寸仅以数据库导出快照为编辑源，生成 Wiki 和索引须逐字段同源。索引在 Top-K 前执行保守尺寸筛选，不替代 Wiki。
 
 ## 对象布局
 
@@ -28,7 +28,7 @@ npm run build:hardware-search-index -- \
   --output /absolute/path/to/tos-search-index
 ```
 
-构建器逐页验证 `record_id`、三级 `category_path` 和 Wiki SHA-256与 Manifest 一致，随后输出 `_catalog.json` 和 `indexes/releases/<release_id>/**/*.json.gz`。输出目录只包含搜索索引，不复制 Wiki 正文。
+构建器逐页验证 `record_id`、三级 `category_path` 和 Wiki SHA-256与 Manifest 一致，随后输出 `_catalog.json` 和 `indexes/releases/<release_id>/**/*.json.gz`。不带尺寸快照时输出仅有搜索索引；带 `--component-snapshot` 时另生成 Wiki 和 Manifest，见下节。
 
 使用[发布命令](search-index-release.md)先上传并回读全部不可变分片，最后以条件 PUT 替换 `_catalog.json`。这样搜索端不会看到指向尚未上传分片的新目录，并发发布也不会静默覆盖。发布完成后自动验证目录记录总数、Manifest、分类数和每个分片 SHA-256，并通过正式 `hardware.search` 执行真实冒烟。
 
@@ -39,3 +39,42 @@ npm run build:hardware-search-index -- \
 默认缺少 `_catalog.json` 时返回 `WIKI_SEARCH_INDEX_MISSING`，不会悄悄下载整个分类。迁移期可显式设置 `TOS_ALLOW_LEGACY_MANIFEST_FALLBACK=true`；此时响应的 `retrieval_mode` 为 `legacy_manifest_full_scan`，并在 `unknowns[]` 写入 `SEARCH_INDEX_FALLBACK`。迁移开关不应作为长期生产配置。
 
 正常响应的 `retrieval_mode` 为 `category_index`。每个槽位同时返回 `available_documents`、`indexed_candidates` 和 `fetched_documents`，用于核对“索引看了多少、全文实际下载多少”。
+
+
+## 数据库尺寸快照 v1
+
+数据库导出格式为 `abelien.component-dimensions.v1`，不是可手填的 Wiki 事实。`records` 按 component_id 的 Unicode 编码顺序排序且不得重复。每项包含 component_id、revision、dimensions_mm（正有限三元组或 null）、dimension_basis（measured/datasheet/estimate/unknown）、dimension_geometry（solid_box/bounding_box/unknown），可含 evidence_ref。revision 是去掉 revision 的记录递归按键排序、无空格 UTF-8 JSON 的 SHA-256 十六进制；snapshot_id 同法哈希整个 records 数组。缺尺寸必须 null/unknown/unknown。占位、默认、未证明的库尺寸不能升级成 measured 或 datasheet；solid_box 只能来自明确形体证据，不从 AABB、名称或占位 CAD 推断。
+
+```bash
+npm run build:hardware-search-index -- \
+  --source /absolute/path/to/硬件wiki \
+  --component-snapshot /absolute/path/to/component-dimensions.json \
+  --output /absolute/path/to/generated-release
+```
+
+source 与 output 须是互不嵌套的目录。每个 Wiki record_id 必须命中数据库导出，缺行失败；多余数据库行允许存在。构建器保留原人工 frontmatter 和正文，仅在 output/wiki 生成尺寸字段及来源，原文件不改。输出路径为 `wiki/components/<snapshot_id>/<content_sha>/<原相对路径>`，Manifest 与导出另存；catalog 指向不可变 `wiki/snapshots/<manifest_sha>/` 清单和数据库快照。再次构建已生成源时会核对 `_component-dimensions.json` 和全部尺寸字段；没有快照却手填尺寸、摘要不符或尺寸篡改均拒绝。
+
+新增 dimension_source/dimensions_mm 以单行严格 JSON 写入并解析（包括有限科学计数值）；原有 capability_coverage 等 YAML inline map 沿用旧解析语义，不因尺寸扩展改写或拒绝。
+
+候选和 selected_models 携带 dimensions_mm、dimension_basis、dimension_geometry、dimension_source={component_id,revision,snapshot_id,evidence_ref?}、dimension_check={status,decision_required,reasons,method}。status 只表达粗筛装配结果：clear 为所有粗筛通过，risk 为至少一项失败但不构成证明，incompatible 为用户 hard 上限＋measured/datasheet 尺寸下的证明，unknown 为无法判定；依据与上限权威仍看 dimension_basis 和 limit source，不另编码进 status。decision_required 仅在用户 hard 上限＋measured/datasheet 尺寸且轴对齐装法全部失败时为 true。索引读入时每条 Wiki sha256 必须存在且合法；即使该行会被尺寸剔除，也不能缺 hash。实际抓取时验证正文 hash、身份、分类及全部尺寸元数据与索引相同。source_snapshot 包含 catalog 和实际分片内容摘要，不以 ETag 代替内容身份。
+
+旧 v1 索引缺内容 hash 必须重新构建，迁移开关也不绕过 hash；缺尺寸或缺 geometry 的旧条目仍可读，但 dimension_check=unknown，不获得 hard rejection 或 clear。新索引为 legacy 无尺寸记录显式输出 null/unknown。搜索保留所有 unknown 和 estimate 候选；`dimension_screen` 报 evaluated/rejected/retained/demoted 和逐个硬拒绝原因。按相关度排序后，risk 候选保留但不占 Top-K 名额，因此每个 risk 会多带入一个可能装得下的替补，总抓取数不超过 TOS_MAX_FULL_WIKI_FETCH_PER_SLOT；返回列表先列非 risk、后列 risk，各层内保持相关度顺序，unknown 不降级。`all_indexed_candidates_rejected` 仅指该槽位已评估分类索引，不能说所有硬件都不适用。
+
+## 尺寸判定与占用边界
+
+`requirements.limits[].envelope` 支持 box.max_mm/min_mm 与 cylinder.max_diameter_mm/max_height_mm/min_diameter_mm/min_height_mm；保留同一条 text/id/source/strength。范围按最大外形减去两倍明确保证的 wall_mm.minimum（缺省 0）求最大腔体；estimate 不参与硬拒绝。所有尺寸有限正数，范围有序，无混合形状字段；最低壁厚必须留出正的最大腔体。较小范围端或估算壁厚不可行不扩大硬拒绝范围。
+
+只有 user+hard 边界和 measured/datasheet 组件可硬拒绝。solid_box 可用最小边、对角线、实体体积三项必要条件；任意 bounding_box 只可用最大支撑跨度超过容器最大弦长，不能用包围盒最小边、对角线或体积。六轴置换、圆柱 footprint 只是可装下粗筛，失败是 risk，未知形体是 unknown。clear 只表示单件粗筛，不代表多件装配、CAD 或工程通过。
+
+
+新域包 hardware 1.2.0 / selection 0.5.0 / workspace 1.3.0 使用此加法契约。已有持久结果只读原样；旧 workflow JSON 摘要不固定模块代码，因此不可用旧定义配新包宣称旧行为仍相同。宿主必须固定完整发布包，为尺寸筛选开新运行，不能原地改写旧 CAD 输入或已失败/未知副作用。
+
+## 电气字段（消费方契约）
+
+生成 Wiki 头部可带两行严格内联 JSON：
+
+- `electrical`：`{schema:"abelien.component-electrical.v1", basis, power_inputs, power_outputs, buses}`。`basis` 为 measured / datasheet / estimate / unknown；供电项为 `{id, voltage_v:[min,max], connector?, max_current_a?}`，id 与连接器为小写短横线标识，电压为有序正数；总线项为 `{type, role, count, logic_level_v?}`，type 取 i2c / spi / uart / usb / i2s / can / pwm / gpio / adc，role 为 controller 或 peripheral。不接受多余字段。
+- `electrical_source`：`{component_id, revision, snapshot_id, evidence_ref?}`，`revision` 是 `{component_id, ...electrical}` 规范 JSON 的 SHA-256。
+
+只有两行都在、源绑定一致的记录才进入候选；只有 `electrical` 没有来源时按未知处理，摘要不符则拒绝。组件数据库是电气数据唯一编辑源，生产方（P2-04.03）沿尺寸快照同一条只读导出与构建管道写入，禁止在 Wiki 上手改。占位、默认或无出处的数据只能标 estimate 或 unknown。
+

package/skills/abelien-hardware/references/search-index-release.md

@@ -62,6 +62,17 @@ npm run smoke:hardware-search -- \
 
 ## 激活与失败语义
 
-构建器以源 Manifest SHA-256 作为 `release_id`，分片写入 `indexes/releases/<release_id>/...`。发布器先验证远端 Manifest，再以不可变语义上传并回读全部分片；只有全部 SHA、Schema、分类和记录数通过后，才用条件 PUT 替换 `_catalog.json`。并发发布导致 Catalog ETag 变化时显式失败，不覆盖别人的新版本。
+构建器以源 Manifest SHA-256 作为 `release_id`，分片写入 `indexes/releases/<release_id>/...`。发布器先验证远端 Manifest，再以不可变语义上传并回读全部分片；只有全部 SHA、Schema、分类和记录数通过后，才替换 `_catalog.json`。
+
+存储是阿里云 OSS（S3 兼容签名），这条路径**没有条件 PUT**：`If-None-Match`／`If-Match` 返回 400 NotImplemented，`x-oss-forbid-overwrite` 被忽略、照常覆盖。所以不可变对象靠先读后写：不存在才上传，已存在则比对 SHA，字节不同以 `IMMUTABLE_OBJECT_CONFLICT` 失败，上传后一律回读校验。激活前重读 `_catalog.json`，按内容 SHA-256 与发布开始时读到的版本比对（OSS 对 JSON 对象不回 ETag），变了就以 `CATALOG_ACTIVATION_RACE` 失败，不覆盖别人的新版本。重读到写入之间仍有很短的窗口，写后校验会比对 `release_id`，输掉竞争的一方因此失败，不会误报成功；同一时刻只应有一人发布。结果的 `previous_catalog` 记录被替换的 catalog（sha256、release_id），作为回滚点。
 
 Catalog 激活失败只会留下未引用的不可变分片，不影响旧版本；搜索端始终从唯一 `_catalog.json` 读取一个完整 release。发布命令默认最后执行真实 `hardware.search`，确保 Catalog、分类索引和至少一篇 Wiki 正文能够按生产读取路径访问。`--skip-smoke` 只用于已有独立冒烟门禁的受控 CI，不能把单元测试当成生产连通性证明。
+
+
+## 尺寸快照发布
+
+数据库导出由 Web 仓库显式只读命令产生；Harness 不接收数据库凭据。尺寸发布使用同一命令的 `--component-snapshot /absolute/path/to/component-dimensions.json`，先运行 `--dry-run --output /absolute/path/to/review` 检查生成 Wiki、Manifest、导出和索引。确定发布环境后去掉 dry-run，才会执行远端写入。
+
+这条路径按 content-addressed key 上传生成 Wiki，再上传不可变导出和 Manifest、索引分片，最后按上节语义激活 `_catalog.json`；每个对象冲突即失败，不覆盖旧 Wiki、旧清单或旧快照。生成路径从 built.generated_source 读取，不能把原始 source 目录的 Wiki 当成新的正文。无需 bootstrap-manifest，catalog 使用该 release 自己的版本化 Manifest。故障只留下未引用的不可变文件；本地测试的内存 TOS 只证明执行顺序和摘要，不证明线上发布成功。
+
+v1 迁移：所有索引记录必须具备 Wiki 内容 SHA-256。旧无 hash 索引重建再发布；旧无尺寸/geometry 记录保持 unknown。dimensions 更新会改变源 revision、snapshot_id、生成 Wiki 内容 hash、Manifest 身份与分片摘要；旧固定产物保持原字节，不原地“补齐”过去的候选。

package/skills/abelien-hardware/references/selection-service-contract.md

@@ -23,3 +23,6 @@ URL 来自 `ABELIEN_HARDWARE_REVISE_URL`。请求包含 `operation: "revise_exis
 ## Supplemental source binding
 
 For new journeys, `hardware.web-search` and `hardware.web-merge` follow [web-evidence-contract](web-evidence-contract.md). Proposal-only finalize consumes the merged recall; formal selection uses its persisted ID and revalidates original recall/evidence. Finalize now keeps only model assessment fields from the proposal and uses candidate facts for manufacturer/model/classification/source/geometry/CAD. No self-reported source or CAD claim can override an external candidate.
+
+
+Dimension metadata is copied only from frozen candidates, with deterministic single-part screening shared by search/finalize/select. Name comes from the candidate title; `bom_item_id` is explicitly a selection-line identity, not a catalog BOM identity. Active envelope output may add advisory occupancy. The [local selection contract](../../abelien-hardware-selection/references/selection-service-contract.md#结构化尺寸与正式门禁) defines unknown/pending behavior and the [index contract](search-index-format.md#数据库尺寸快照-v1) defines database provenance. Finalize never upgrades its proposed result to formal verified authority.

package/skills/abelien-hardware/references/web-evidence-contract.md

@@ -2,9 +2,9 @@
 
 Read the [architecture](../../../docs/architecture/hardware-online-fallback.md) and [official API inventory](../../../docs/architecture/prismer-api-inventory.md). The trusted current-workdir reader/checkpoint owns all source bodies. A model cannot submit URL/key/provider/command/source content or default envelopes.
 
-hardware.web-search input is exactly {requirements,slots,recall_id,unresolved_slots}. Each unresolved item is {slot_id,reason,query,count?}; every zero-candidate slot must occur and all-unsuitable candidates need a reason. Query is nonempty; Count is a positive integer/default10 without undocumented fixed upper limits. Full selectionRequestDigest preserves original requirements, quantities and constraints. unresolved_slots lists only slots needing search: omit suitable slots entirely, never submit empty query/count0 placeholders; all suitable means []. Empty unresolved list with suitable candidates uses zero network/credentials. The shared validateHardwareWebPlan({input,readResource}) in scripts/web-search-plan.mjs returns {source} after the same original-recall and query/count checks used before search configuration, checkpoints or provider calls. It does not filter or default invalid entries.
+hardware.web-search input is exactly {requirements,slots,recall_id,unresolved_slots}. Each unresolved item is {slot_id,reason,query,count?}; every zero-candidate slot must occur and all-unsuitable candidates need a reason. Query is nonempty; Count is a positive integer. New plans (P2-05.02) must write the query in English (no Chinese/Japanese/Korean characters; keep model numbers and manufacturer names) and Count is 1–5, default 5; validateNewHardwareWebPlan rejects violations with VALIDATION. A plan already frozen in saved evidence keeps the rules it was accepted under (validateFrozenHardwareWebPlan). Full selectionRequestDigest preserves original requirements, quantities and constraints. unresolved_slots lists only slots needing search: omit suitable slots entirely, never submit empty query/count0 placeholders; all suitable means []. Empty unresolved list with suitable candidates uses zero network/credentials. The shared validateHardwareWebPlan({input,readResource}) in scripts/web-search-plan.mjs returns {source} after the original-recall, query/count and new-plan checks used by the preflight helper; search applies the new-plan checks only when the plan is not the one frozen in existing evidence, before configuration, checkpoints or provider calls. It does not filter or default invalid entries.
 
-The trusted fixed policy is prismer_then_volc. Fixed Prismer query POST /api/context/load sends inputType=query, search.topK and explicit return.topK/format=both. URL-load sends inputType=url/format=both; only result.raw supplies source text. cached/cachedAt/meta and complete raw/response/summary/cost/time are retained. HQCC-only is unavailable. PDF/image suffixes from original query URLs use actual Parse {url,mode:fast,output:markdown,wait:true}. Synchronous requestId is nullable; async taskId is persisted before fixed status/result GET. Callback/endpoints are ignored. Source text is API raw/parsed markdown, not original HTTP bytes or a verified realtime/final URL.
+The trusted fixed policy is prismer_then_volc. Prismer is temporarily off (P2-05.02): unless the trusted host sets ABELIEN_HARDWARE_WEB_PRISMER=enabled (default disabled; any other value is HARDWARE_WEB_CONFIG), every prismer attempt (query, context_url, parse) is saved unsent as status=unavailable, reason=prismer_disabled with no receipt, and that marker authorizes the same group's volcengine/query or direct_https/direct_page attempt; PDF/image sources then stay unavailable (parse_unavailable). Volc requests use Count = plan count or 5; Volc receipts saved by 0.4.0 keep their frozen default Count 10 request. When enabled, the fixed Prismer query POST /api/context/load sends inputType=query, search.topK and explicit return.topK/format=both. URL-load sends inputType=url/format=both; only result.raw supplies source text. cached/cachedAt/meta and complete raw/response/summary/cost/time are retained. HQCC-only is unavailable. PDF/image suffixes from original query URLs use actual Parse {url,mode:fast,output:markdown,wait:true}. Synchronous requestId is nullable; async taskId is persisted before fixed status/result GET. Callback/endpoints are ignored. Source text is API raw/parsed markdown, not original HTTP bytes or a verified realtime/final URL.
 
 New hardware-web-evidence has provider=prismer, protocol=prismer-volc-source-v2, schema_version=2, provider_policy=prismer_then_volc; original recall_id/recall_digest/request_digest/requirements/slots; plan_digest/unresolved_slots/query_plans; all searches; all pages; unknowns. Its stable ID depends only on original recall_id/request_digest. Every paid attempt has stable id/status/request/raw/raw_sha256/canonical response_sha256/received_at/http_status/request_id/response. Ordered searches[].attempts use prismer/query then the optional volcengine/query; pages[].attempts use prismer/context_url|parse then optional direct_https/direct_page. Each group retains selected_attempt_id/selected_provider and the exact selected receipt alias. Page primary attempt.kind is context_url or parse; pending Parse includes task_id and observations of each fixed GET. Page has source_url/returned_url (nullable), text/text_sha256/content_sha256/retrieval/cached/cachedAt/meta/loaded_at. Prismer source_bytes_verified/remote_redirects_verified remain false. Direct receipts retain actual wire and safe persisted raw/text digests, final_url/fetched_at, DNS/redirect/IP/TLS trace; redaction modifies only the safe copy and raw_redacted=true makes source_bytes_verified=false. PDF/image denial remains unavailable without a direct Parse substitute.
 

package/skills/abelien-hardware/scripts/build-search-index.mjs

@@ -5,6 +5,8 @@ import path from "node:path";
 import process from "node:process";
 import zlib from "node:zlib";
 import { fileURLToPath } from "node:url";
+import { validateComponentSnapshot, fieldsFromSnapshotRecord, dimensionFields } from './dimensions.mjs';
+import { digest } from './selection-request.mjs';
 import { parseHardwareWiki } from "./tos-wiki-search.mjs";
 
 const CATALOG_SCHEMA = "abelien.hardware-wiki-search-catalog.v1";
@@ -57,13 +59,49 @@ function compactRecord(entry, parsed) {
     functional_capabilities: meta.functional_capabilities ?? [],
     capability_coverage: meta.capability_coverage ?? [],
     selection_profile: meta.selection_profile,
+    ...dimensionFields(meta),
     search_text: searchText,
   };
 }
 
-export function buildSearchIndex({ sourceDir, outputDir, releaseId }) {
-  const source = path.resolve(sourceDir);
+function generatedSource(source, output, snapshotFile) {
+  if (source === output || source.startsWith(output + path.sep) || output.startsWith(source + path.sep)) throw fail("generated output and source must be separate directories");
+  const snapshot = validateComponentSnapshot(JSON.parse(fs.readFileSync(snapshotFile, "utf8")));
+  const records = new Map(snapshot.records.map(record => [record.component_id, record]));
+  const manifest = JSON.parse(fs.readFileSync(path.join(source, "_manifest.json"), "utf8"));
+  if (!Array.isArray(manifest)) throw fail("manifest must be an array");
+  const generated = path.join(output, "wiki");
+  const nextManifest = manifest.map(entry => {
+    const parsed = parseHardwareWiki(fs.readFileSync(safeSourceFile(source, entry.path), "utf8"));
+    if (parsed.meta.record_id !== entry.record_id) throw fail(`record_id mismatch for ${entry.path}`);
+    if (entry.sha256 && entry.sha256 !== sha256(parsed.content)) throw fail(`sha256 mismatch for ${entry.path}`);
+    const record = records.get(entry.record_id);
+    if (!record) throw fail(`component snapshot missing Wiki component: ${entry.record_id}`);
+    const fields = fieldsFromSnapshotRecord(record, snapshot.snapshot_id);
+    // Only replace generated top-level dimension keys; preserve every other frontmatter line and prose.
+    const lines = parsed.frontMatter.split("\n"), kept = [];
+    let skipping = false;
+    for (const line of lines) {
+      if (/^[^\s#][^:]*:/.test(line)) skipping = /^(dimensions_mm|dimension_basis|dimension_geometry|dimension_source):/.test(line);
+      if (!skipping) kept.push(line);
+    }
+    const content = `---\n${kept.join("\n")}\n${Object.entries(fields).map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join("\n")}\n---\n${parsed.body}`;
+    const generatedPath = `wiki/components/${snapshot.snapshot_id}/${sha256(content)}/${entry.path}`;
+    const target = safeSourceFile(generated, generatedPath); fs.mkdirSync(path.dirname(target), { recursive: true }); fs.writeFileSync(target, content);
+    return { ...entry, path: generatedPath, sha256: sha256(content) };
+  }).sort((a, b) => a.record_id < b.record_id ? -1 : a.record_id > b.record_id ? 1 : 0);
+  fs.mkdirSync(generated, { recursive: true });
+  fs.writeFileSync(path.join(generated, "_manifest.json"), `${JSON.stringify(nextManifest, null, 2)}\n`);
+  fs.writeFileSync(path.join(generated, "_component-dimensions.json"), `${JSON.stringify(snapshot, null, 2)}\n`);
+  return generated;
+}
+
+export function buildSearchIndex({ sourceDir, outputDir, releaseId, componentSnapshot }) {
   const output = path.resolve(outputDir);
+  const source = componentSnapshot ? generatedSource(path.resolve(sourceDir), output, componentSnapshot) : path.resolve(sourceDir);
+  const sourceSnapshotFile = path.join(source, "_component-dimensions.json");
+  const snapshot = fs.existsSync(sourceSnapshotFile) ? validateComponentSnapshot(JSON.parse(fs.readFileSync(sourceSnapshotFile, "utf8"))) : null;
+  const sourceRecords = new Map(snapshot?.records.map(row => [row.component_id, row]) ?? []);
   const manifestFile = path.join(source, "_manifest.json");
   if (!fs.existsSync(manifestFile)) throw fail(`manifest not found: ${manifestFile}`);
   const manifestBytes = fs.readFileSync(manifestFile);
@@ -82,6 +120,11 @@ export function buildSearchIndex({ sourceDir, outputDir, releaseId }) {
     if (recordIds.has(entry.record_id)) throw fail(`duplicate record_id in manifest: ${entry.record_id}`);
     recordIds.add(entry.record_id);
     const parsed = parseHardwareWiki(fs.readFileSync(safeSourceFile(source, entry.path), "utf8"));
+    const hasDimensions = ["dimensions_mm", "dimension_basis", "dimension_source", "dimension_geometry"].some(key => Object.hasOwn(parsed.meta, key));
+    if (hasDimensions) {
+      const expected = sourceRecords.get(entry.record_id);
+      if (!expected || digest(dimensionFields(parsed.meta)) !== digest(fieldsFromSnapshotRecord(expected, snapshot.snapshot_id))) throw fail(`Wiki dimensions do not match component snapshot: ${entry.path}`);
+    } else if (snapshot) throw fail(`snapshot-backed Wiki missing dimension fields: ${entry.path}`);
     const record = compactRecord(entry, parsed);
     const key = entry.category_path.join("/");
     if (!grouped.has(key)) grouped.set(key, []);
@@ -122,18 +165,19 @@ export function buildSearchIndex({ sourceDir, outputDir, releaseId }) {
     schema: CATALOG_SCHEMA,
     release_id: resolvedReleaseId,
     generated_at: latestSourceUpdate,
-    source_manifest: { object_key: "_manifest.json", sha256: sourceManifestSha, record_count: manifest.length },
+    source_manifest: { object_key: snapshot ? `wiki/snapshots/${sourceManifestSha}/_manifest.json` : "_manifest.json", sha256: sourceManifestSha, record_count: manifest.length },
     categories,
+    ...(snapshot ? { component_snapshot: { snapshot_id: snapshot.snapshot_id, object_key: `wiki/snapshots/${sourceManifestSha}/_component-dimensions.json`, sha256: sha256(fs.readFileSync(sourceSnapshotFile)) } } : {}),
   };
   fs.writeFileSync(path.join(output, "_catalog.json"), `${JSON.stringify(catalog, null, 2)}\n`);
-  return { documents: manifest.length, categories: categories.length, output, release_id: resolvedReleaseId, source_manifest_sha256: sourceManifestSha };
+  return { documents: manifest.length, categories: categories.length, output, release_id: resolvedReleaseId, source_manifest_sha256: sourceManifestSha, ...(snapshot ? { generated_source: source, component_snapshot_id: snapshot.snapshot_id } : {}) };
 }
 
 function parseArgs(argv) {
   const flags = {};
   for (let i = 0; i < argv.length; i++) {
     const name = argv[i];
-    if (name !== "--source" && name !== "--output" && name !== "--release-id") throw fail(`unknown argument: ${name}`);
+    if (name !== "--source" && name !== "--output" && name !== "--release-id" && name !== "--component-snapshot") throw fail(`unknown argument: ${name}`);
     if (!argv[i + 1]) throw fail(`${name} requires a value`);
     flags[name.slice(2)] = argv[++i];
   }
@@ -144,7 +188,7 @@ function parseArgs(argv) {
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   try {
     const flags = parseArgs(process.argv.slice(2));
-    process.stdout.write(`${JSON.stringify({ ok: true, data: buildSearchIndex({ sourceDir: flags.source, outputDir: flags.output, releaseId: flags["release-id"] }) })}\n`);
+    process.stdout.write(`${JSON.stringify({ ok: true, data: buildSearchIndex({ sourceDir: flags.source, outputDir: flags.output, releaseId: flags["release-id"], componentSnapshot: flags["component-snapshot"] }) })}\n`);
   } catch (cause) {
     process.stderr.write(`${JSON.stringify({ ok: false, error: { code: cause.code ?? "INDEX_BUILD_FAILED", message: cause.message } })}\n`);
     process.exitCode = 1;

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

@@ -0,0 +1,184 @@
+// Coarse single-part screening. This module never grants CAD/engineering authority.
+import { canonical, digest } from './selection-request.mjs';
+const object = v => v !== null && typeof v === 'object' && !Array.isArray(v);
+const positive = v => typeof v === 'number' && Number.isFinite(v) && v > 0;
+const nonnegative = v => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+const text = v => typeof v === 'string' && v.trim().length > 0;
+const hash = v => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const tuple = v => Array.isArray(v) && v.length === 3 && v.every(positive);
+const invalid = message => { throw Object.assign(new Error(message), { code: 'VALIDATION' }); };
+function keys(value, required, optional, label) {
+  if (!object(value) || required.some(key => !Object.hasOwn(value, key)) || Object.keys(value).some(key => ![...required, ...optional].includes(key))) invalid(`${label} has missing or unsupported fields`);
+}
+export function validateEnvelope(envelope) {
+  const box = envelope?.shape === 'box';
+  const cylinder = envelope?.shape === 'cylinder';
+  if (!box && !cylinder) invalid('envelope shape must be box or cylinder');
+  keys(envelope, box ? ['shape', 'max_mm'] : ['shape', 'max_diameter_mm', 'max_height_mm'], box ? ['min_mm', 'wall_mm'] : ['min_diameter_mm', 'min_height_mm', 'wall_mm'], 'envelope');
+  if (box) {
+    if (!tuple(envelope.max_mm) || (envelope.min_mm !== undefined && (!tuple(envelope.min_mm) || envelope.min_mm.some((v, i) => v > envelope.max_mm[i])))) invalid('box dimensions must be finite positive ordered triples');
+  } else {
+    for (const axis of ['diameter', 'height']) {
+      const max = envelope[`max_${axis}_mm`], min = envelope[`min_${axis}_mm`];
+      if (!positive(max) || (min !== undefined && (!positive(min) || min > max))) invalid('cylinder dimensions must be finite positive ordered ranges');
+    }
+  }
+  if (envelope.wall_mm !== undefined) {
+    keys(envelope.wall_mm, ['minimum'], ['estimate'], 'wall_mm');
+    const { minimum, estimate } = envelope.wall_mm;
+    if (!nonnegative(minimum) || (estimate !== undefined && (!nonnegative(estimate) || estimate < minimum))) invalid('wall minimum/estimate must be finite nonnegative ordered values');
+  }
+  const max = box ? envelope.max_mm : [envelope.max_diameter_mm, envelope.max_height_mm];
+  if (max.some(v => v - 2 * (envelope.wall_mm?.minimum ?? 0) <= 0)) invalid('guaranteed minimum wall leaves no positive maximum cavity');
+  return envelope;
+}
+export function validateRequirementEnvelopes(requirements) {
+  for (const row of requirements?.limits ?? []) if (row?.envelope !== undefined) validateEnvelope(row.envelope);
+}
+const BASE_FIELDS = ['component_id', 'dimensions_mm', 'dimension_basis', 'dimension_geometry'];
+function dimensionRecord(value) {
+  const record = Object.fromEntries(BASE_FIELDS.map(key => [key, value[key]]));
+  if (value.evidence_ref !== undefined) record.evidence_ref = value.evidence_ref;
+  return record;
+}
+function validRecord(value) {
+  return object(value) && text(value.component_id) && (value.dimensions_mm === null || tuple(value.dimensions_mm))
+    && ['measured', 'datasheet', 'estimate', 'unknown'].includes(value.dimension_basis)
+    && ['solid_box', 'bounding_box', 'unknown'].includes(value.dimension_geometry)
+    && (value.evidence_ref === undefined || text(value.evidence_ref))
+    && (value.dimensions_mm !== null || (value.dimension_basis === 'unknown' && value.dimension_geometry === 'unknown'));
+}
+export function validateComponentSnapshot(snapshot) {
+  keys(snapshot, ['schema', 'snapshot_id', 'records'], [], 'component snapshot');
+  if (snapshot.schema !== 'abelien.component-dimensions.v1' || !Array.isArray(snapshot.records) || !hash(snapshot.snapshot_id)) invalid('unsupported component dimension snapshot');
+  let previous;
+  for (const row of snapshot.records) {
+    keys(row, [...BASE_FIELDS, 'revision'], ['evidence_ref'], 'component snapshot record');
+    if (!validRecord(row) || !hash(row.revision) || row.revision !== digest(dimensionRecord(row))) invalid('component dimension record or revision is invalid');
+    if (previous !== undefined && previous >= row.component_id) invalid('component records must be unique and sorted by component_id');
+    previous = row.component_id;
+  }
+  if (snapshot.snapshot_id !== digest(snapshot.records)) invalid('component snapshot hash does not match records');
+  return snapshot;
+}
+// Only source-bound records can contribute a trusted basis. Legacy unbound fields stay display-only unknown.
+export function dimensionFields(value) {
+  const source = value?.dimension_source;
+  const id = value?.component_id ?? value?.record_id;
+  const validSize = tuple(value?.dimensions_mm);
+  const fields = { dimensions_mm: validSize ? [...value.dimensions_mm] : null, dimension_basis: 'unknown', dimension_geometry: 'unknown', dimension_source: null };
+  if (!object(source) || source.component_id !== id || !hash(source.revision) || !hash(source.snapshot_id)) return fields;
+  const record = { component_id: id, dimensions_mm: fields.dimensions_mm, dimension_basis: value.dimension_basis,
+    dimension_geometry: value.dimension_geometry ?? 'unknown', ...(source.evidence_ref !== undefined ? { evidence_ref: source.evidence_ref } : {}) };
+  // Missing geometry is a legacy gap, not permission to apply solid-box predicates.
+  if (value.dimension_geometry === undefined) { fields.dimension_source = { ...source }; return fields; }
+  if (!validRecord(record) || source.revision !== digest(record)) invalid('dimension source revision does not match candidate fields');
+  return { dimensions_mm: record.dimensions_mm, dimension_basis: record.dimension_basis, dimension_geometry: record.dimension_geometry, dimension_source: { ...source } };
+}
+export function fieldsFromSnapshotRecord(record, snapshotId) {
+  return { dimensions_mm: record.dimensions_mm, dimension_basis: record.dimension_basis, dimension_geometry: record.dimension_geometry,
+    dimension_source: { component_id: record.component_id, revision: record.revision, snapshot_id: snapshotId, ...(record.evidence_ref !== undefined ? { evidence_ref: record.evidence_ref } : {}) } };
+}
+// Compare raw dimension-bearing fields too: normalizing unknowns must not hide index/Wiki drift.
+export function sameDimensionMetadata(a, b) {
+  const pick = value => ({ dimensions_mm: value.dimensions_mm ?? null, dimension_basis: value.dimension_basis ?? 'unknown', dimension_geometry: value.dimension_geometry ?? 'unknown', dimension_source: value.dimension_source ?? null });
+  return canonical(pick(a)) === canonical(pick(b));
+}
+function cavity(envelope, wall) {
+  if (envelope.shape === 'box') {
+    const sides = envelope.max_mm.map(v => v - 2 * wall);
+    return { sides, width: Math.min(...sides), chord: Math.hypot(...sides), volume: sides.reduce((a, b) => a * b, 1), valid: sides.every(positive) };
+  }
+  const diameter = envelope.max_diameter_mm - 2 * wall, height = envelope.max_height_mm - 2 * wall;
+  return { diameter, height, width: Math.min(diameter, height), chord: Math.hypot(diameter, height), volume: Math.PI * (diameter / 2) ** 2 * height, valid: positive(diameter) && positive(height) };
+}
+const exceeds = (a, b) => a - b > 1e-9 * Math.max(1, Math.abs(a), Math.abs(b));
+function coarseFit(dims, container) {
+  if (!container.valid) return false;
+  return [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]].some(p => container.sides
+    ? p.every((axis, i) => !exceeds(dims[axis], container.sides[i]))
+    : !exceeds(dims[p[2]], container.height) && !exceeds(Math.hypot(dims[p[0]], dims[p[1]]), container.diameter));
+}
+// status is the coarse fit result only: clear = every coarse check passed, risk = some check failed without proof,
+// incompatible = proof under a user hard limit with measured/datasheet sizes. Data/limit authority stays in basis and limit source.
+// decision_required = user hard limit + trusted sizes, yet no axis-aligned mounting fits: only the user can trade the part against the limit.
+export function evaluateDimensions(candidate, requirements) {
+  validateRequirementEnvelopes(requirements);
+  const fields = dimensionFields(candidate), reasons = [], method = 'coarse-single-part-v2';
+  const unknown = code => ({ status: 'unknown', decision_required: false, reasons: [{ code }], method });
+  const limits = (requirements?.limits ?? []).filter(row => row?.envelope !== undefined);
+  if (!limits.length) return unknown('PRODUCT_ENVELOPE_MISSING');
+  if (!fields.dimensions_mm || fields.dimension_basis === 'unknown' || fields.dimension_geometry === 'unknown') return unknown('COMPONENT_DIMENSIONS_UNKNOWN');
+  const dims = fields.dimensions_mm;
+  if (!positive(dims.reduce((a, b) => a * b, 1)) || !positive(Math.hypot(...dims))
+    || limits.some(row => { const c = cavity(row.envelope, row.envelope.wall_mm?.minimum ?? 0); return !positive(c.volume) || !positive(c.chord); }))
+    return unknown('NUMERIC_RANGE_UNSUPPORTED');
+  let incompatible = false, risk = false, decisionRequired = false;
+  for (const row of limits) {
+    const hard = row.source === 'user' && row.strength === 'hard' && ['measured', 'datasheet'].includes(fields.dimension_basis);
+    const container = cavity(row.envelope, row.envelope.wall_mm?.minimum ?? 0);
+    const failures = fields.dimension_geometry === 'solid_box'
+      ? [['MIN_SUPPORT_WIDTH', Math.min(...dims), container.width], ['SOLID_DIAGONAL', Math.hypot(...dims), container.chord], ['SOLID_VOLUME', dims.reduce((a, b) => a * b, 1), container.volume]]
+      : [['MAX_SUPPORT_SPAN', Math.max(...dims), container.chord]];
+    for (const [code, observed, maximum] of failures) if (exceeds(observed, maximum)) {
+      reasons.push({ code, limit_id: row.id, observed, maximum, hard }); if (hard) incompatible = true; else risk = true;
+    }
+    // Parts are mounted axis-aligned in practice; failing that is a risk, never a proof, because a tilted part may still fit.
+    if (!coarseFit(dims, container)) {
+      risk = true; if (hard) decisionRequired = true;
+      reasons.push({ code: 'AXIS_ALIGNED_FIT_FAILS', limit_id: row.id, hard: false });
+    } else if (row.envelope.wall_mm?.estimate !== undefined && !coarseFit(dims, cavity(row.envelope, row.envelope.wall_mm.estimate))) {
+      // Estimated walls only hint; they never reject and never ask the user to decide.
+      risk = true; reasons.push({ code: 'ESTIMATED_WALL_FIT_FAILS', limit_id: row.id, hard: false });
+    }
+  }
+  return { status: incompatible ? 'incompatible' : risk ? 'risk' : 'clear', decision_required: !incompatible && decisionRequired, reasons, method };
+}
+export function screenDimensions(records, requirements) {
+  const checks = records.map(record => ({ record, check: evaluateDimensions(record, requirements) }));
+  const rejected = checks.filter(item => item.check.status === 'incompatible');
+  const survivors = checks.filter(item => item.check.status !== 'incompatible');
+  return { survivors, summary: {
+    status: records.length && rejected.length === records.length ? 'all_indexed_candidates_rejected' : records.length ? 'screened' : 'no_indexed_candidates',
+    scope: 'indexed_category_candidates', evaluated: records.length, rejected: rejected.length, retained: survivors.length,
+    demoted: survivors.filter(item => item.check.status === 'risk').length,
+    rejections: rejected.map(({ record, check }) => ({ component_id: record.component_id ?? record.record_id, ...check })),
+  } };
+}
+// Risk candidates stay visible but do not consume Top-K slots, so each one brings in a replacement that may fit.
+// Input must already be sorted by relevance; output lists non-risk candidates first, each tier keeping relevance order.
+export function shortlistByDimensionTier(ranked, topK, cap, statusOf) {
+  const picked = [];
+  let fitting = 0;
+  for (const item of ranked) {
+    if (fitting >= topK || picked.length >= cap) break;
+    picked.push(item);
+    if (statusOf(item) !== 'risk') fitting++;
+  }
+  return orderByDimensionTier(picked, statusOf);
+}
+export function orderByDimensionTier(items, statusOf) {
+  return [...items.filter(item => statusOf(item) !== 'risk'), ...items.filter(item => statusOf(item) === 'risk')];
+}
+export function assemblyOccupancy(models, requirements, policy = {}) {
+  validateRequirementEnvelopes(requirements);
+  let estimated_volume_mm3 = 0, unknown_lines = 0, includedLines = 0;
+  const seen = new Set();
+  for (const model of models) {
+    if (seen.has(model.bom_item_id)) continue;
+    if (model.bom_item_id) seen.add(model.bom_item_id);
+    const fields = dimensionFields(model);
+    if (!fields.dimensions_mm || fields.dimension_basis === 'unknown' || !Number.isSafeInteger(model.quantity) || model.quantity < 1) { unknown_lines++; continue; }
+    const volume = fields.dimensions_mm.reduce((a, b) => a * b, model.quantity);
+    if (!positive(volume) || !Number.isFinite(estimated_volume_mm3 + volume)) { unknown_lines++; continue; }
+    estimated_volume_mm3 += volume;
+    includedLines++;
+  }
+  const containers = (includedLines ? requirements?.limits ?? [] : []).filter(row => row?.envelope).flatMap(row => {
+    const value = cavity(row.envelope, row.envelope.wall_mm?.minimum ?? 0).volume;
+    const ratio = estimated_volume_mm3 / value;
+    return positive(value) && nonnegative(ratio) ? [{ limit_id: row.id, cavity_volume_mm3: value, ratio }] : [];
+  });
+  return { advisory: true, method: 'sum-selected-line-bounding-volumes-v1', estimated_volume_mm3, unknown_lines, containers,
+    ...(positive(policy.occupancy_warning_ratio) ? { warning: containers.some(c => c.ratio > policy.occupancy_warning_ratio), warning_ratio: policy.occupancy_warning_ratio } : {}) };
+}

package/skills/abelien-hardware/scripts/electrical.mjs

@@ -0,0 +1,125 @@
+// Deterministic electrical compatibility for a selected set of parts (star topology, v1).
+// Only measured/datasheet records can prove pass, fail or a supply gap; anything else stays unknown. This is not a circuit simulation.
+import { digest } from './selection-request.mjs';
+const object = v => v !== null && typeof v === 'object' && !Array.isArray(v);
+const positive = v => typeof v === 'number' && Number.isFinite(v) && v > 0;
+const text = v => typeof v === 'string' && v.trim().length > 0;
+const hash = v => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const slug = v => typeof v === 'string' && /^[a-z0-9][a-z0-9-]{0,47}$/.test(v);
+const invalid = message => { throw Object.assign(new Error(message), { code: 'VALIDATION' }); };
+function keys(value, required, optional, label) {
+  if (!object(value) || required.some(key => !Object.hasOwn(value, key)) || Object.keys(value).some(key => ![...required, ...optional].includes(key))) invalid(`${label} has missing or unsupported fields`);
+}
+export const ELECTRICAL_SCHEMA = 'abelien.component-electrical.v1';
+export const BUS_TYPES = ['i2c', 'spi', 'uart', 'usb', 'i2s', 'can', 'pwm', 'gpio', 'adc'];
+// Multi-drop buses only need to exist on the controller; the others are point-to-point and their counts add up.
+const SHARED_BUSES = ['i2c', 'spi', 'can'];
+const TRUSTED = ['measured', 'datasheet'];
+const BASES = ['measured', 'datasheet', 'estimate', 'unknown'];
+const range = v => Array.isArray(v) && v.length === 2 && v.every(positive) && v[0] <= v[1];
+
+function validatePower(rows, label) {
+  if (!Array.isArray(rows)) invalid(`${label} must be an array`);
+  const ids = new Set();
+  for (const row of rows) {
+    keys(row, ['id', 'voltage_v'], ['connector', 'max_current_a'], label);
+    if (!slug(row.id) || ids.has(row.id) || !range(row.voltage_v) || (row.connector !== undefined && !slug(row.connector))
+      || (row.max_current_a !== undefined && !positive(row.max_current_a))) invalid(`${label} entries need unique ids, ordered positive voltage ranges and slug connectors`);
+    ids.add(row.id);
+  }
+}
+// Strict consumer-side contract; the producer is the component database export (P2-04.03).
+export function validateElectricalRecord(value) {
+  keys(value, ['schema', 'basis', 'power_inputs', 'power_outputs', 'buses'], [], 'electrical record');
+  if (value.schema !== ELECTRICAL_SCHEMA || !BASES.includes(value.basis)) invalid('unsupported electrical record schema or basis');
+  validatePower(value.power_inputs, 'electrical power_inputs');
+  validatePower(value.power_outputs, 'electrical power_outputs');
+  if (!Array.isArray(value.buses)) invalid('electrical buses must be an array');
+  for (const bus of value.buses) {
+    keys(bus, ['type', 'role', 'count'], ['logic_level_v'], 'electrical bus');
+    if (!BUS_TYPES.includes(bus.type) || !['controller', 'peripheral'].includes(bus.role) || !Number.isSafeInteger(bus.count) || bus.count < 1
+      || (bus.logic_level_v !== undefined && !positive(bus.logic_level_v))) invalid('electrical bus needs a known type, role, positive count and positive logic level');
+  }
+  return value;
+}
+// Source-bound records only; an unbound or legacy record is reported as unknown, never trusted.
+export function electricalFields(value) {
+  const record = value?.electrical, source = value?.electrical_source, id = value?.component_id ?? value?.record_id;
+  if (record === undefined && source === undefined) return {};
+  if (!object(source) || source.component_id !== id || !hash(source.revision) || !hash(source.snapshot_id)
+    || Object.keys(source).some(key => !['component_id', 'revision', 'snapshot_id', 'evidence_ref'].includes(key))
+    || (source.evidence_ref !== undefined && !text(source.evidence_ref))) return { electrical: null, electrical_source: null };
+  validateElectricalRecord(record);
+  if (source.revision !== digest({ component_id: id, ...record })) invalid('electrical source revision does not match candidate fields');
+  return { electrical: record, electrical_source: { ...source } };
+}
+const overlaps = (a, b) => a[0] <= b[1] && b[0] <= a[1];
+const within = (inner, outer) => inner[0] >= outer[0] && inner[1] <= outer[1];
+const isController = part => part.category_path?.[0] === 'compute-control' && ['controller-board', 'controller-module'].includes(part.category_path?.[1]);
+const isPower = part => part.category_path?.[0] === 'power-energy';
+const isLevelShifter = part => part.category_path?.[0] === 'electrical-interconnect' && part.category_path?.[1] === 'level-shifting';
+const trusted = part => TRUSTED.includes(part.electrical?.basis);
+const ref = part => ({ slot_id: part.slot_id, component_id: part.component_id });
+
+// Supply match against trusted rails only. A missing rail is a supply gap (add a power part), never a reason to reject the consumer.
+function supply(consumer, sources, rule, dimension) {
+  const parts = [consumer, ...sources].map(ref), inputs = consumer.electrical?.power_inputs ?? [];
+  if (!trusted(consumer) || !inputs.length) return { rule, dimension, status: 'unknown', parts, reason: trusted(consumer) ? 'NO_DECLARED_INPUT' : 'UNTRUSTED_OR_MISSING_DATA' };
+  const rails = sources.filter(trusted).flatMap(source => (source.electrical.power_outputs ?? []).map(output => ({ source, output })));
+  const fit = rails.find(({ output }) => inputs.some(input => within(output.voltage_v, input.voltage_v)));
+  if (fit) {
+    const input = inputs.find(row => within(fit.output.voltage_v, row.voltage_v));
+    const connectorRisk = Boolean(input.connector && fit.output.connector && input.connector !== fit.output.connector);
+    return { rule, dimension, status: connectorRisk ? 'risk' : 'pass', parts, reason: connectorRisk ? 'CONNECTOR_MISMATCH' : 'RAIL_WITHIN_INPUT',
+      rail: { component_id: fit.source.component_id, id: fit.output.id, voltage_v: fit.output.voltage_v, connector: fit.output.connector ?? null },
+      input: { id: input.id, voltage_v: input.voltage_v, connector: input.connector ?? null } };
+  }
+  if (sources.some(source => !trusted(source))) return { rule, dimension, status: 'unknown', parts, reason: 'UNTRUSTED_SOURCE_MAY_SUPPLY' };
+  const partial = rails.some(({ output }) => inputs.some(input => overlaps(output.voltage_v, input.voltage_v)));
+  return { rule, dimension, status: partial ? 'risk' : 'gap', parts, reason: partial ? 'RAIL_PARTIALLY_OUTSIDE_INPUT' : 'NO_SUPPLY_RAIL_FOR_INPUT' };
+}
+// fail (incompatible part) > gap (missing part) > pass (all checks pass on trusted data) > risk > unknown.
+const aggregate = (checks, dimension, members) => {
+  const rows = checks.filter(check => check.dimension === dimension);
+  for (const status of ['fail', 'gap']) if (rows.some(check => check.status === status)) return status;
+  if (rows.length && rows.every(check => check.status === 'pass') && members.every(trusted)) return 'pass';
+  return rows.some(check => check.status === 'risk') ? 'risk' : 'unknown';
+};
+// parts: [{slot_id, component_id, category_path, quantity, electrical}] for the whole selection.
+export function evaluateElectrical(parts) {
+  const method = 'electrical-star-v1', controllers = parts.filter(isController);
+  if (controllers.length !== 1) return { method, topology: 'not_star', dimensions: { power: 'unknown', interfaces: 'unknown' }, checks: [],
+    reasons: [{ code: controllers.length ? 'MULTIPLE_CONTROLLERS' : 'NO_CONTROLLER', controllers: controllers.map(ref) }] };
+  const [controller] = controllers, sources = parts.filter(isPower), shifter = parts.some(isLevelShifter);
+  const peripherals = parts.filter(part => part !== controller && !isPower(part) && !isLevelShifter(part));
+  const checks = [];
+  // Rule 1: a selected supply must power the controller. Without one the controller is powered from outside the selection.
+  if (sources.length) checks.push(supply(controller, sources, 'controller_supply', 'power'));
+  // Rule 2: each peripheral needs a controller rail or a selected supply rail inside one of its input ranges.
+  for (const part of peripherals) if (part.electrical?.power_inputs?.length || !trusted(part)) checks.push(supply(part, [controller, ...sources], 'peripheral_supply', 'power'));
+  // Rule 3: bus types the peripherals need must exist on the controller; point-to-point counts must also fit.
+  const need = new Map();
+  for (const part of peripherals) for (const bus of part.electrical?.buses ?? []) if (bus.role === 'peripheral')
+    need.set(bus.type, [...(need.get(bus.type) ?? []), { part, bus, count: bus.count * (part.quantity ?? 1) }]);
+  for (const part of peripherals) if (!trusted(part)) checks.push({ rule: 'bus_availability', dimension: 'interfaces', status: 'unknown', parts: [ref(part), ref(controller)], reason: 'UNTRUSTED_OR_MISSING_DATA' });
+  for (const [type, rows] of need) {
+    const parts2 = [ref(controller), ...rows.map(row => ref(row.part))];
+    if (!trusted(controller) || rows.some(row => !trusted(row.part))) { checks.push({ rule: 'bus_availability', dimension: 'interfaces', status: 'unknown', bus: type, parts: parts2, reason: 'UNTRUSTED_OR_MISSING_DATA' }); continue; }
+    const offered = (controller.electrical.buses ?? []).filter(bus => bus.type === type && bus.role === 'controller');
+    const available = offered.reduce((sum, bus) => sum + bus.count, 0);
+    const required = SHARED_BUSES.includes(type) ? 1 : rows.reduce((sum, row) => sum + row.count, 0);
+    checks.push({ rule: 'bus_availability', dimension: 'interfaces', bus: type, parts: parts2, required, available,
+      status: available >= required ? 'pass' : 'fail', reason: !available ? 'BUS_TYPE_MISSING' : available < required ? 'BUS_COUNT_SHORT' : 'BUS_AVAILABLE' });
+    // Rule 4: a logic-level mismatch is only a risk in v1; cables and level shifters can bridge it.
+    for (const row of rows) {
+      const level = offered.find(bus => bus.logic_level_v !== undefined)?.logic_level_v;
+      if (level === undefined || row.bus.logic_level_v === undefined) continue;
+      const mismatch = Math.abs(level - row.bus.logic_level_v) > 1e-9;
+      checks.push({ rule: 'logic_level', dimension: 'interfaces', bus: type, parts: [ref(controller), ref(row.part)], controller_v: level, peripheral_v: row.bus.logic_level_v,
+        status: mismatch && !shifter ? 'risk' : 'pass', reason: !mismatch ? 'LOGIC_LEVEL_MATCH' : shifter ? 'LEVEL_SHIFTER_SELECTED' : 'LOGIC_LEVEL_MISMATCH' });
+    }
+  }
+  const powerMembers = [controller, ...sources, ...peripherals.filter(part => checks.some(check => check.dimension === 'power' && check.parts.some(row => row.component_id === part.component_id)))];
+  return { method, topology: 'star', controller: ref(controller), checks,
+    dimensions: { power: aggregate(checks, 'power', powerMembers), interfaces: aggregate(checks, 'interfaces', [controller, ...peripherals]) } };
+}