abelien-harness 0.3.0 → 0.4.0

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,32 @@ 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 输入或已失败/未知副作用。

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

@@ -65,3 +65,12 @@ npm run smoke:hardware-search -- \
 构建器以源 Manifest SHA-256 作为 `release_id`，分片写入 `indexes/releases/<release_id>/...`。发布器先验证远端 Manifest，再以不可变语义上传并回读全部分片；只有全部 SHA、Schema、分类和记录数通过后，才用条件 PUT 替换 `_catalog.json`。并发发布导致 Catalog ETag 变化时显式失败，不覆盖别人的新版本。
 
 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/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/finalize-selection.mjs

@@ -1,4 +1,6 @@
 import crypto from "node:crypto";
+import { assemblyOccupancy, dimensionFields, evaluateDimensions } from "./dimensions.mjs";
+import { selectionRequestDigest } from "./selection-request.mjs";
 
 function error(message, details) {
   const out = new Error(message);
@@ -23,6 +25,7 @@ export async function finalizeHardwareSelection({ input }) {
   if (!recall || recall.status !== "completed" || !recall.source_snapshot) throw error("completed knowledge_recall is required");
   if (!["proposed", "verified", "needs_confirmation"].includes(proposal.status)) throw error("selection_proposal.status is not recognized");
   if (!["adapt_system", "assemble_new"].includes(proposal.plan_mode)) throw error("selection_proposal.plan_mode is not recognized");
+  if (recall.request_digest && recall.request_digest !== selectionRequestDigest(input)) throw error("recall does not match selection requirements and slots");
   const proposedModels = requireArray(proposal.selected_models, "selected_models");
   const coverageLedger = requireArray(proposal.coverage_ledger, "coverage_ledger");
   const remainingSlots = requireArray(proposal.remaining_slots, "remaining_slots");
@@ -71,7 +74,14 @@ export async function finalizeHardwareSelection({ input }) {
         slot_id: selected.slot_id, component_id: selected.component_id,
       });
     }
+    const dimensionCheck = evaluateDimensions(candidate, input.requirements);
+    if (dimensionCheck.status === "incompatible") throw error("selected component is dimensionally incompatible; choose a surviving candidate", { slot_id: selected.slot_id, component_id: selected.component_id, dimension_check: dimensionCheck });
     return {
+      name: String(candidate.title ?? candidate.name ?? candidate.model ?? candidate.component_id),
+      // This is a deterministic selection-line identity, NOT an upstream catalog BOM identity.
+      bom_item_id: `selection-line-${digest({ slot_id: selected.slot_id, component_id: candidate.component_id }).slice(0, 24)}`,
+      ...dimensionFields(candidate), dimension_check: dimensionCheck,
+      ...(candidate.interfaces !== undefined ? { interfaces: candidate.interfaces } : {}),
       slot_id: selected.slot_id, component_id: selected.component_id, quantity: selected.quantity,
       selection_reason: selected.selection_reason, wiki_evidence: selected.wiki_evidence,
       ...(selected.constraint_checks !== undefined ? { constraint_checks: selected.constraint_checks } : {}),
@@ -97,6 +107,7 @@ export async function finalizeHardwareSelection({ input }) {
     revision: `r-${hash.slice(0, 12)}`,
     plan_mode: proposal.plan_mode,
     selected_models: selectedModels,
+    ...(input.requirements?.limits?.some(row => row?.envelope) ? { occupancy: assemblyOccupancy(selectedModels, input.requirements, input.policy) } : {}),
     coverage_ledger: coverageLedger,
     remaining_slots: remainingSlots,
     unknowns,

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

@@ -8,7 +8,7 @@ import { publishHardwareSearchIndex } from "./search-index-release.mjs";
 function parseArgs(argv) {
   const flags = {};
   const booleans = new Set(["--dry-run", "--skip-smoke", "--bootstrap-manifest"]);
-  const valued = new Set(["--source", "--output", "--release-id", "--env-file", "--concurrency"]);
+  const valued = new Set(["--source", "--output", "--release-id", "--env-file", "--concurrency", "--component-snapshot"]);
   for (let i = 0; i < argv.length; i++) {
     const name = argv[i];
     if (booleans.has(name)) flags[name.slice(2)] = true;
@@ -30,6 +30,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
       sourceDir: path.resolve(cwd, flags.source),
       outputDir: flags.output ? path.resolve(cwd, flags.output) : undefined,
       releaseId: flags["release-id"],
+      componentSnapshot: flags["component-snapshot"] ? path.resolve(cwd, flags["component-snapshot"]) : undefined,
       env,
       fetchImpl: deps.fetchImpl || fetch,
       dryRun: Boolean(flags["dry-run"]),

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

@@ -69,6 +69,7 @@ export function validateLocalRelease(outputDir) {
     if (index.source_manifest_sha256 !== catalog.source_manifest?.sha256) {
       throw releaseError("INDEX_RELEASE_INVALID", `index Manifest digest mismatch: ${descriptor.index_key}`);
     }
+    if (index.records.some(record => !/^[a-f0-9]{64}$/.test(record.sha256 ?? ""))) throw releaseError("INDEX_RELEASE_INVALID", "every Wiki needs a content SHA-256; rebuild legacy indexes");
     documents += index.records.length;
     files.push({ key: descriptor.index_key, file, bytes, sha256: descriptor.sha256 });
   }
@@ -242,12 +243,12 @@ export async function smokePublishedIndex({ env, fetchImpl = fetch, categoryPath
   };
 }
 
-export async function publishHardwareSearchIndex({ sourceDir, outputDir, releaseId, env, fetchImpl = fetch, dryRun = false, smoke = true, concurrency, bootstrapManifest = false } = {}) {
+export async function publishHardwareSearchIndex({ sourceDir, outputDir, releaseId, componentSnapshot, env, fetchImpl = fetch, dryRun = false, smoke = true, concurrency, bootstrapManifest = false } = {}) {
   if (!sourceDir) throw releaseError("USAGE", "sourceDir is required");
   const temporary = !outputDir;
   const output = outputDir ? path.resolve(outputDir) : fs.mkdtempSync(path.join(os.tmpdir(), "abelien-hardware-index-"));
   try {
-    const built = buildSearchIndex({ sourceDir, outputDir: output, releaseId });
+    const built = buildSearchIndex({ sourceDir, outputDir: output, releaseId, componentSnapshot });
     const local = validateLocalRelease(output);
     if (dryRun) return {
       status: "validated",
@@ -262,6 +263,18 @@ export async function publishHardwareSearchIndex({ sourceDir, outputDir, release
     };
 
     const config = createTosConfig(env);
+    if (built.generated_source) {
+      const manifestBytes = fs.readFileSync(path.join(built.generated_source, "_manifest.json"));
+      const entries = JSON.parse(manifestBytes);
+      const limit = Number(concurrency || env?.TOS_PUBLISH_CONCURRENCY || 6);
+      await mapConcurrent(entries, Number.isFinite(limit) ? limit : 6, async entry => {
+        const bytes = fs.readFileSync(safeFile(built.generated_source, entry.path));
+        if (sha256(bytes) !== entry.sha256) throw releaseError("SOURCE_WIKI_MISMATCH", "generated Wiki changed after build");
+        await putImmutable(config, `${config.prefix}${entry.path}`, bytes, fetchImpl);
+      });
+      await putImmutable(config, `${config.prefix}${local.catalog.component_snapshot.object_key}`, fs.readFileSync(path.join(built.generated_source, "_component-dimensions.json")), fetchImpl);
+      await putImmutable(config, `${config.prefix}${local.catalog.source_manifest.object_key}`, manifestBytes, fetchImpl);
+    }
     let manifest = await requireMatchingManifest(config, local.catalog, fetchImpl, { optional: true });
     if (!manifest && !bootstrapManifest) {
       throw releaseError("SOURCE_MANIFEST_MISSING", "TOS Wiki Manifest is missing; rerun with --bootstrap-manifest to verify every remote Wiki object before creating it", {