@faicad/faijs 0.33.1 → 0.35.2

package/dist/api/assembly/solve-tree.js.map

@@ -1 +1 @@
-{"version":3,"file":"solve-tree.js","sourceRoot":"","sources":["../../../src/api/assembly/solve-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,EAAE,uBAAuB,EAAE,YAAY,EAAE,cAAc,EAAmB,MAAM,QAAQ,CAAA;AAC/F,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE5E,MAAM,OAAO,GAAG,IAAI,CAAC,EAAE,GAAG,GAAG,CAAA;AAsB7B,4EAA4E;AAC5E,SAAS,UAAU,CAAC,IAAkB;IACpC,MAAM,QAAQ,GAA6B,IAAI,CAAC,SAAS;QACvD,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACb,IAAI,QAAQ,GAAqC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IAC7D,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,MAAM,IAAI,GAAsC,IAAI,CAAC,MAAM,CAAC,IAAI;YAC9D,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACjE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;QACb,QAAQ,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC,CAAA;IACjE,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAA;AAC/B,CAAC;AAED,oEAAoE;AACpE,SAAS,WAAW,CAAC,MAAkB,EAAE,KAAiB;IACxD,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAA;IAC5D,OAAO;QACL,QAAQ,EAAE;YACR,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;YAChC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;YAChC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;SACjC;QACD,QAAQ,EAAE,YAAY,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC;KACxD,CAAA;AACH,CAAC;AAUD;;;;;GAKG;AACH,SAAS,WAAW,CAAC,IAAkB;IACrC,MAAM,OAAO,GAAY,EAAE,CAAA;IAC3B,MAAM,WAAW,GAAa,EAAE,CAAA;IAChC,MAAM,WAAW,GAAyB,EAAE,CAAA;IAC5C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAsB,CAAA;IAEjD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,WAAW;YAAE,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACvD,CAAC;IAED,SAAS,IAAI,CAAC,IAAkB,EAAE,MAAc,EAAE,WAAuB;QACvE,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAA;YAC7D,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;YACnC,MAAM,gBAAgB,GAAG,WAAW,CAAC,WAAW,EAAE,SAAS,CAAC,CAAA;YAE5D,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;gBAChB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;gBACzB,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;gBACvB,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAA;YAC1C,CAAC;YAED,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;gBACtB,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,WAAW;oBAAE,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACxD,CAAC;YAED,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9B,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,gBAAgB,CAAC,CAAA;YACtC,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAA;IACjC,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAA;IACxB,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,CAAA;AAC3D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAkB,EAClB,IAAmB;IAEnB,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;IAC9B,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;IAC5E,CAAC;IAED,MAAM,SAAS,GAAiB,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,CAAA;IAC7D,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAA;IACvF,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,kEAAkE;YAChE,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAClF,CAAA;IACH,CAAC;IAED,MAAM,UAAU,GAAsC,EAAE,CAAA;IAExD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAA;QAChC,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC7C,IAAI,UAAU,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9C,UAAU,CAAC,IAAI,CAAC,GAAG,uBAAuB,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACtE,CAAC;IACH,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;QACtC,IAAI,CAAC,IAAI;YAAE,SAAQ;QACnB,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC7C,IAAI,CAAC,UAAU,IAAI,cAAc,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9C,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YACpB,SAAQ;QACV,CAAC;QACD,MAAM,UAAU,GAAe;YAC7B,QAAQ,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAChE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,UAA8C,CAAC;SACzE,CAAA;QACD,MAAM,QAAQ,GAAG,WAAW,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;QACpD,UAAU,CAAC,IAAI,CAAC,GAAG,uBAAuB,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAA;IAC1E,CAAC;IAED,OAAO;QACL,UAAU;QACV,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,qCAAqC;QACrC,eAAe,EAAE,MAAM,CAAC,eAAe;KACxC,CAAA;AACH,CAAC","sourcesContent":["/**\n * api/assembly/solve-tree — 嵌套子装配求解（P4，方案 §4.2）\n *\n * flatten → solveGlobal → recompose：\n * 1. flatten：walkAssembly 收集叶 shape + qualified member name（如 `subassy.part`），\n *    构建扁平 members/memberNames；约束从各层收集（part 名用 qualified name，可跨层引用）。\n * 2. solve：调 solveGlobal 求解扁平问题。\n * 3. recompose：自顶向下将父变换（AssemblyNode.translate/rotate）与 solver 变换复合\n *    （parentTransform ∘ childLocalTransform），得到每个叶节点的世界变换。\n *\n * 语义对齐 CQ `Assembly.solve()`：每个对象的 `loc` 累积合成世界变换。\n * faijs Shape 不携带 placement → 求解器从 identity 初值求解；父变换在 recompose 阶段复合。\n */\n\nimport type { Shape } from '../../mesh/types'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport type { AssemblyConstraint } from './types'\nimport type { SolveOptions } from './solvers/types'\nimport type { AssemblyNode } from './solvers/assembly-tree'\nimport { solveGlobal } from './solvers/global-solver'\nimport { poseToAssemblyTransform, toBrepjsQuat, isIdentityPose, type SolverPose } from './pose'\nimport { quatFromAxisAngle, quatRotate, quatMultiply } from './solvers/quat'\n\nconst DEG2RAD = Math.PI / 180\n\n/** 嵌套子装配求解结果：per-leaf 世界变换 + 诊断量。 */\nexport interface AssemblyTreeSolveResult {\n  /** 每个叶节点的世界变换（键 = qualified name）。 */\n  transforms: Record<string, AssemblyTransform>\n  /** 是否全部约束可解。 */\n  converged: boolean\n  /** 无法求解的约束明细。 */\n  unsupported: string[]\n  /** 逐约束最终残差。 */\n  residuals: number[]\n  /** 残差超阈值的约束逐条写入。 */\n  warnings?: string[]\n  /**\n   * P7/D1-3：欠定自由度诊断（透传自 solveGlobal）。dof > 0 = 约束集欠定，\n   * 终态位姿依赖优化器轨迹、无唯一「正确解」——判等方应走规范判等通道而非逐位比对。\n   */\n  underdetermined?: { dof: number }\n}\n\n\n/** 把 AssemblyNode 的 translate/rotate 转为 SolverPose（brepjs [w,x,y,z] 旋转）。 */\nfunction nodeToPose(node: AssemblyNode): SolverPose {\n  const position: [number, number, number] = node.translate\n    ? [node.translate[0], node.translate[1], node.translate[2]]\n    : [0, 0, 0]\n  let rotation: [number, number, number, number] = [1, 0, 0, 0]\n  if (node.rotate) {\n    const axis: readonly [number, number, number] = node.rotate.axis\n      ? [node.rotate.axis[0], node.rotate.axis[1], node.rotate.axis[2]]\n      : [0, 0, 1]\n    rotation = quatFromAxisAngle(axis, node.rotate.angle * DEG2RAD)\n  }\n  return { position, rotation }\n}\n\n/** 复合两个 pose：先应用 child，再应用 parent（p' = R_p·(R_c·p + T_c) + T_p）。 */\nfunction composePose(parent: SolverPose, child: SolverPose): SolverPose {\n  const rotatedT = quatRotate(parent.rotation, child.position)\n  return {\n    position: [\n      parent.position[0] + rotatedT[0],\n      parent.position[1] + rotatedT[1],\n      parent.position[2] + rotatedT[2],\n    ],\n    rotation: quatMultiply(parent.rotation, child.rotation),\n  }\n}\n\ninterface FlatAssembly {\n  members: Shape[]\n  memberNames: string[]\n  constraints: AssemblyConstraint[]\n  /** 每个叶节点的累积父 pose（从 root 到该叶，含该叶自身 translate/rotate）。 */\n  parentPoses: Map<string, SolverPose>\n}\n\n/**\n * flatten：递归遍历装配树，收集叶 shape + qualified name + 约束 + 累积父 pose。\n *\n * qualified name = 从 root 的子节点到叶的 dot-separated 路径（如 `subassy.partB`）。\n * 约束从各层收集 as-is——约束中的 part 名应为 qualified name（可跨层引用）。\n */\nfunction flattenTree(root: AssemblyNode): FlatAssembly {\n  const members: Shape[] = []\n  const memberNames: string[] = []\n  const constraints: AssemblyConstraint[] = []\n  const parentPoses = new Map<string, SolverPose>()\n\n  if (root.constraints) {\n    for (const c of root.constraints) constraints.push(c)\n  }\n\n  function walk(node: AssemblyNode, prefix: string, accumulated: SolverPose): void {\n    for (const child of node.children) {\n      const qName = prefix ? `${prefix}.${child.name}` : child.name\n      const childPose = nodeToPose(child)\n      const childAccumulated = composePose(accumulated, childPose)\n\n      if (child.shape) {\n        members.push(child.shape)\n        memberNames.push(qName)\n        parentPoses.set(qName, childAccumulated)\n      }\n\n      if (child.constraints) {\n        for (const c of child.constraints) constraints.push(c)\n      }\n\n      if (child.children.length > 0) {\n        walk(child, qName, childAccumulated)\n      }\n    }\n  }\n\n  const rootPose = nodeToPose(root)\n  walk(root, '', rootPose)\n  return { members, memberNames, constraints, parentPoses }\n}\n\n/**\n * 求解嵌套子装配树：flatten → solveGlobal → recompose。\n *\n * @param root - 装配树根节点（root 的 shape 被忽略，仅作容器）。\n * @param opts - 求解选项（透传给 solveGlobal；默认 solver:'global'）。\n * @returns 每个叶节点的世界变换 + 诊断量。\n * @throws Error on empty members, unknown constraint parts, or non-convergence.\n */\nexport function solveAssemblyTree(\n  root: AssemblyNode,\n  opts?: SolveOptions,\n): AssemblyTreeSolveResult {\n  const flat = flattenTree(root)\n  if (flat.members.length === 0) {\n    return { transforms: {}, converged: true, unsupported: [], residuals: [] }\n  }\n\n  const solveOpts: SolveOptions = { solver: 'global', ...opts }\n  const result = solveGlobal(flat.members, flat.memberNames, flat.constraints, solveOpts)\n  if (!result.converged) {\n    throw new Error(\n      '[assembly:tree] constraint solve did not converge; unsupported: ' +\n        (result.unsupported.length > 0 ? result.unsupported.join(', ') : '(no detail)'),\n    )\n  }\n\n  const transforms: Record<string, AssemblyTransform> = {}\n\n  for (let i = 0; i < flat.memberNames.length; i++) {\n    const name = flat.memberNames[i]\n    const parentPose = flat.parentPoses.get(name)\n    if (parentPose && !isIdentityPose(parentPose)) {\n      transforms[name] = poseToAssemblyTransform(parentPose, [0, 0, 0], i)\n    }\n  }\n\n  for (const t of result.transforms) {\n    const name = flat.memberNames[t.index]\n    if (!name) continue\n    const parentPose = flat.parentPoses.get(name)\n    if (!parentPose || isIdentityPose(parentPose)) {\n      transforms[name] = t\n      continue\n    }\n    const solverPose: SolverPose = {\n      position: [t.translation[0], t.translation[1], t.translation[2]],\n      rotation: toBrepjsQuat(t.quaternion as [number, number, number, number]),\n    }\n    const composed = composePose(parentPose, solverPose)\n    transforms[name] = poseToAssemblyTransform(composed, [0, 0, 0], t.index)\n  }\n\n  return {\n    transforms,\n    converged: result.converged,\n    unsupported: result.unsupported,\n    residuals: result.residuals,\n    warnings: result.warnings,\n    // P7/D1-3：显式透传（此处是重建对象，spread 不会带上）。\n    underdetermined: result.underdetermined,\n  }\n}"]}
+{"version":3,"file":"solve-tree.js","sourceRoot":"","sources":["../../../src/api/assembly/solve-tree.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/solve-tree — 嵌套子装配求解（P4，方案 §4.2）\n *\n * flatten → solveGlobal → recompose：\n * 1. flatten：walkAssembly 收集叶 shape + qualified member name（如 `subassy.part`），\n *    构建扁平 members/memberNames；约束从各层收集（part 名用 qualified name，可跨层引用）。\n * 2. solve：调 solveGlobal 求解扁平问题。\n * 3. recompose：自顶向下将父变换（AssemblyNode.translate/rotate）与 solver 变换复合\n *    （parentTransform ∘ childLocalTransform），得到每个叶节点的世界变换。\n *\n * 语义对齐 CQ `Assembly.solve()`：每个对象的 `loc` 累积合成世界变换。\n * faijs Shape 不携带 placement → 求解器从 identity 初值求解；父变换在 recompose 阶段复合。\n */\n\nimport type { Shape } from '../../mesh/types'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport type { AssemblyConstraint } from './types'\nimport type { SolveOptions } from './solvers/types'\nimport type { AssemblyNode } from './solvers/assembly-tree'\nimport { solveGlobal } from './solvers/global-solver'\nimport { poseToAssemblyTransform, isIdentityPose, type SolverPose } from './pose'\nimport { quatFromAxisAngle, quatRotate, quatMultiply } from './solvers/quat'\n\nconst DEG2RAD = Math.PI / 180\n\n/** 嵌套子装配求解结果：per-leaf 世界变换 + 诊断量。 */\nexport interface AssemblyTreeSolveResult {\n  /** 每个叶节点的世界变换（键 = qualified name）。 */\n  transforms: Record<string, AssemblyTransform>\n  /** 是否全部约束可解。 */\n  converged: boolean\n  /** 无法求解的约束明细。 */\n  unsupported: string[]\n  /** 逐约束最终残差。 */\n  residuals: number[]\n  /** 残差超阈值的约束逐条写入。 */\n  warnings?: string[]\n  /**\n   * P7/D1-3：欠定自由度诊断（透传自 solveGlobal）。dof > 0 = 约束集欠定，\n   * 终态位姿依赖优化器轨迹、无唯一「正确解」——判等方应走规范判等通道而非逐位比对。\n   */\n  underdetermined?: { dof: number; freeDirs?: number[][] }\n}\n\n\n/** 把 AssemblyNode 的 translate/rotate 转为 SolverPose（brepjs [w,x,y,z] 旋转）。 */\nfunction nodeToPose(node: AssemblyNode): SolverPose {\n  const position: [number, number, number] = node.translate\n    ? [node.translate[0], node.translate[1], node.translate[2]]\n    : [0, 0, 0]\n  let rotation: [number, number, number, number] = [1, 0, 0, 0]\n  if (node.rotate) {\n    const axis: readonly [number, number, number] = node.rotate.axis\n      ? [node.rotate.axis[0], node.rotate.axis[1], node.rotate.axis[2]]\n      : [0, 0, 1]\n    rotation = quatFromAxisAngle(axis, node.rotate.angle * DEG2RAD)\n  }\n  return { position, rotation }\n}\n\n/** 复合两个 pose：先应用 child，再应用 parent（p' = R_p·(R_c·p + T_c) + T_p）。 */\nfunction composePose(parent: SolverPose, child: SolverPose): SolverPose {\n  const rotatedT = quatRotate(parent.rotation, child.position)\n  return {\n    position: [\n      parent.position[0] + rotatedT[0],\n      parent.position[1] + rotatedT[1],\n      parent.position[2] + rotatedT[2],\n    ],\n    rotation: quatMultiply(parent.rotation, child.rotation),\n  }\n}\n\ninterface FlatAssembly {\n  members: Shape[]\n  memberNames: string[]\n  constraints: AssemblyConstraint[]\n  /** 每个叶节点的累积父 pose（从 root 到该叶，含该叶自身 translate/rotate）。 */\n  parentPoses: Map<string, SolverPose>\n  /** P8：刚体分组（成员下标）——同一子装配的叶共享一个刚体块。 */\n  rigidGroups: number[][]\n}\n\n/**\n * flatten：递归遍历装配树，收集叶 shape + qualified name + 约束 + 累积父 pose。\n *\n * qualified name = 从 root 的子节点到叶的 dot-separated 路径（如 `subassy.partB`）。\n * 约束从各层收集 as-is——约束中的 part 名应为 qualified name（可跨层引用）。\n */\nfunction flattenTree(root: AssemblyNode): FlatAssembly {\n  const members: Shape[] = []\n  const memberNames: string[] = []\n  const constraints: AssemblyConstraint[] = []\n  const parentPoses = new Map<string, SolverPose>()\n  // P8：子装配 → 叶下标分组（叶序号在收集时递增，组按收集序记录）。\n  const rigidGroups: number[][] = []\n\n  if (root.constraints) {\n    for (const c of root.constraints) constraints.push(c)\n  }\n\n  function walk(node: AssemblyNode, prefix: string, accumulated: SolverPose, groupId: number | null): void {\n    for (const child of node.children) {\n      const qName = prefix ? `${prefix}.${child.name}` : child.name\n      const childPose = nodeToPose(child)\n      const childAccumulated = composePose(accumulated, childPose)\n\n      // P8：子装配节点（有 children）开一个新刚体组——其自身 shape 叶（root 件）\n      // 与全部成员叶同组。必须在建组后再 push 自身叶，否则 root 件落在外层\n      // groupId（null）下、组内只剩成员叶，length>1 过滤会把整组丢掉\n      // （nested_assy 实测：组 [b3] 被滤掉，b2 仍自由漂移）。\n      const isSub = child.children.length > 0\n      const myGroup = isSub ? rigidGroups.length : groupId\n      if (isSub) rigidGroups.push([])\n\n      if (child.shape) {\n        members.push(child.shape)\n        memberNames.push(qName)\n        parentPoses.set(qName, childAccumulated)\n        if (myGroup !== null) rigidGroups[myGroup].push(members.length - 1)\n      }\n\n      if (child.constraints) {\n        for (const c of child.constraints) constraints.push(c)\n      }\n\n      if (isSub) {\n        walk(child, qName, childAccumulated, myGroup)\n      }\n    }\n  }\n\n  const rootPose = nodeToPose(root)\n  walk(root, '', rootPose, null)\n  return { members, memberNames, constraints, parentPoses, rigidGroups }\n}\n\n/**\n * 求解嵌套子装配树：flatten → solveGlobal → recompose。\n *\n * @param root - 装配树根节点（root 的 shape 被忽略，仅作容器）。\n * @param opts - 求解选项（透传给 solveGlobal；默认 solver:'global'）。\n * @returns 每个叶节点的世界变换 + 诊断量。\n * @throws Error on empty members, unknown constraint parts, or non-convergence.\n */\nexport function solveAssemblyTree(\n  root: AssemblyNode,\n  opts?: SolveOptions,\n): AssemblyTreeSolveResult {\n  const flat = flattenTree(root)\n  if (flat.members.length === 0) {\n    return { transforms: {}, converged: true, unsupported: [], residuals: [] }\n  }\n\n  const solveOpts: SolveOptions = { solver: 'global', ...opts }\n  // P8：子装配刚体分组传入求解器（同组叶共享一个 6 维状态块）。\n  const groups = flat.rigidGroups.filter((g) => g.length > 1)\n  if (groups.length > 0) solveOpts.rigidGroups = groups\n  // P8 方案 A（CQ sublocs）：叶的累积 loc（含自身 translate/rotate）作为求解\n  // 初位姿传入——约束 marker 取自成员本地系，绝对位姿 = initial ∘ delta 在\n  // 求解器内部合成。无累积位姿（恒等）的叶不注入，保持旧语义。\n  const initPoses: SolveOptions['initialPoses'] = []\n  let hasInit = false\n  for (let i = 0; i < flat.memberNames.length; i++) {\n    const pp = flat.parentPoses.get(flat.memberNames[i]!)\n    if (pp && !isIdentityPose(pp)) {\n      initPoses[i] = {\n        translation: [pp.position[0], pp.position[1], pp.position[2]],\n        rotation: [pp.rotation[0], pp.rotation[1], pp.rotation[2], pp.rotation[3]],\n      }\n      hasInit = true\n    }\n  }\n  if (hasInit) solveOpts.initialPoses = initPoses\n  const result = solveGlobal(flat.members, flat.memberNames, flat.constraints, solveOpts)\n  if (!result.converged) {\n    throw new Error(\n      '[assembly:tree] constraint solve did not converge; unsupported: ' +\n        (result.unsupported.length > 0 ? result.unsupported.join(', ') : '(no detail)'),\n    )\n  }\n\n  const transforms: Record<string, AssemblyTransform> = {}\n\n  for (let i = 0; i < flat.memberNames.length; i++) {\n    const name = flat.memberNames[i]\n    const parentPose = flat.parentPoses.get(name)\n    if (parentPose && !isIdentityPose(parentPose)) {\n      transforms[name] = poseToAssemblyTransform(parentPose, [0, 0, 0], i)\n    }\n  }\n\n  for (const t of result.transforms) {\n    const name = flat.memberNames[t.index]\n    if (!name) continue\n    // P8 方案 A：solver 发射的已是绝对位姿（initial ∘ delta 在求解器内合成），\n    // 直接采用——若再 compose parentPose 会把初 loc 算两遍。\n    transforms[name] = t\n  }\n\n  return {\n    transforms,\n    converged: result.converged,\n    unsupported: result.unsupported,\n    residuals: result.residuals,\n    warnings: result.warnings,\n    // P7/D1-3：显式透传（此处是重建对象，spread 不会带上）。\n    underdetermined: result.underdetermined,\n  }\n}"]}

package/dist/api/assembly/solve.d.ts

@@ -42,6 +42,7 @@ export interface AssemblySolveResult {
      */
     underdetermined?: {
         dof: number;
+        freeDirs?: number[][];
     };
 }
 /**

package/dist/api/assembly/solve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solve.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/solve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAO5D,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,SAAS,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGnD,oCAAoC;AACpC,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,UAAU,EAAE,iBAAiB,EAAE,CAAA;IAC/B,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAA;IACX,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAA;IAClB,uCAAuC;IACvC,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IAC3C;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAClC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,KAAK,EAAE,EAChB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,kBAAkB,EAAE,EACjC,IAAI,CAAC,EAAE,YAAY,GAClB,mBAAmB,CA0DrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,KAAK,EAAE,EAChB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,kBAAkB,EAAE,EACjC,MAAM,GAAE,SAAS,EAAO,EACxB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EACzC,IAAI,CAAC,EAAE,YAAY,GAClB,mBAAmB,CAkCrB"}
+{"version":3,"file":"solve.d.ts","sourceRoot":"","sources":["../../../src/api/assembly/solve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAO5D,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,SAAS,CAAA;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAGnD,oCAAoC;AACpC,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,UAAU,EAAE,iBAAiB,EAAE,CAAA;IAC/B,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAA;IACX,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAA;IAClB,uCAAuC;IACvC,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IAC3C;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,EAAE,CAAA;KAAE,CAAA;CACzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,KAAK,EAAE,EAChB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,kBAAkB,EAAE,EACjC,IAAI,CAAC,EAAE,YAAY,GAClB,mBAAmB,CA0DrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,KAAK,EAAE,EAChB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,kBAAkB,EAAE,EACjC,MAAM,GAAE,SAAS,EAAO,EACxB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,EACzC,IAAI,CAAC,EAAE,YAAY,GAClB,mBAAmB,CAkCrB"}

package/dist/api/assembly/solve.js.map

@@ -1 +1 @@
-{"version":3,"file":"solve.js","sourceRoot":"","sources":["../../../src/api/assembly/solve.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/solve — 装配求解入口（P1，方案 §4.2）\n *\n * 流程：规范化（normalize）→ 降级（lower）→ brepjs solveConstraints\n *（拓扑轮次调度 / DOF / converged 全部由 brepjs 提供，零 brepjs 修改）→\n * per-member 终态 AssemblyTransform（修 L6：不再 per-constraint 增量叠加）。\n *\n * 不收敛 → 抛错（D3，错误信息带 unsupported 明细；对齐「绝不静默」约定）。\n * 恒等位姿的成员（锚定/链根）不输出变换——引擎不做无谓的几何重算。\n */\n\nimport type { Shape } from '../../mesh/types'\nimport type { BrepEngineApi } from '../../brep/engine/primitives'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport { getBrepApi } from '../../brep/handle-bridge'\nimport { solveConstraints } from './solvers/chain-solver'\nimport { normalizeConstraint } from './normalize'\nimport { lowerStructuralConstraint } from './lower'\nimport { type EntityResolutionEnv } from './entities'\nimport { poseToAssemblyTransform, isIdentityPose, type SolverPose } from './pose'\nimport { solveKinematics, type JointSpec, type KinematicsPose } from './joints'\nimport type { AssemblyConstraint, AssemblyVec3 } from './types'\nimport type { SolveOptions } from './solvers/types'\nimport { solveGlobal } from './solvers/global-solver'\n\n/** 求解完整结果：per-member 终态变换 + 诊断量。 */\nexport interface AssemblySolveResult {\n  /** 每个被定位成员一条终态变换（index = 成员下标；恒等位姿不输出）。 */\n  transforms: AssemblyTransform[]\n  /** unsupported 约束的自由度合计（诊断量；收敛时为 0）。 */\n  dof: number\n  /** 是否全部约束可解（不收敛时 solveAssembly 已抛错，此字段恒 true）。 */\n  converged: boolean\n  /** 无法求解的约束明细（entity 类型不匹配 / 参考不可达）。 */\n  unsupported: string[]\n  /**\n   * P3：运动副解算的全成员位姿表（键 = 成员名；含恒等链根），\n   * 只有该装配声明了 joints 时才存在——宿主从 ExecutionResult.kinematics 消费。\n   */\n  kinematics?: Record<string, KinematicsPose>\n  /**\n   * P3：合并诊断（joints 覆盖约束解时各记一条；D-P3-1，不参与 converged 统计）。\n   */\n  warnings?: string[]\n  /**\n   * P1（global 求解器）：逐约束最终残差（CQ 代价的逐约束平方和）。chain 路径不填。\n   */\n  residuals?: number[]\n  /**\n   * P7/D1-3：欠定自由度诊断（仅 global 路径透传）。dof > 0 = 约束集欠定，\n   * 终态位姿依赖优化器轨迹、无唯一「正确解」——判等方应走规范判等通道而非逐位比对。\n   */\n  underdetermined?: { dof: number }\n}\n\n/**\n * 求解装配：members + memberNames + constraints → per-member 终态。\n *\n * @param members - member shapes (compound children, aligned with memberNames).\n * @param memberNames - member variable names (R7: empty names throw before solving).\n * @param constraints - raw constraints from `cad.assembly({ constraints })`.\n * @param opts - optional solver options (e.g. `solver: 'global'` selects the global least-squares path).\n * @returns the solve result (transforms + diagnostics).\n * @throws Error on empty member names, unknown constraint parts, or non-convergence.\n */\nexport function solveAssembly(\n  members: Shape[],\n  memberNames: string[],\n  constraints: AssemblyConstraint[],\n  opts?: SolveOptions,\n): AssemblySolveResult {\n  // P1：global 求解器分派（CadQuery 兼容全局最小二乘；零额外依赖）\n  if (opts?.solver === 'global') {\n    return solveGlobal(members, memberNames, constraints, opts)\n  }\n\n  // R7：成员名是 solver 的节点键，空串会让多成员互相覆盖——求解前断言\n  memberNames.forEach((name, i) => {\n    if (!name) {\n      throw new Error(\n        `[assembly] member at index ${i} has an empty name — members are referenced by variable name in constraints`,\n      )\n    }\n  })\n\n  const memberMap = new Map<string, Shape>()\n  members.forEach((m, i) => {\n    const name = memberNames[i]\n    if (name && !memberMap.has(name)) memberMap.set(name, m)\n  })\n  // kernel 仅 TopoRef/边引用解析需要；backends 未配置（纯位姿场景/单测）→ null，\n  // 此时快照引用仍可解，TopoRef 引用按 E_TOPO_NOT_FOUND 显式报错\n  let kernel: BrepEngineApi | null = null\n  try {\n    kernel = getBrepApi()\n  } catch {\n    // backends not configured — snapshot-form constraints still solvable\n  }\n  const env: EntityResolutionEnv = { kernel, memberOf: (p: string) => memberMap.get(p) }\n\n  const lowered: ReturnType<typeof lowerStructuralConstraint>['constraint'][] = []\n  const depOrigins = new Map<string, AssemblyVec3>()\n  for (const raw of constraints) {\n    const c = normalizeConstraint(raw)\n    const { constraint, depOrigin } = lowerStructuralConstraint(c, env)\n    lowered.push(constraint)\n    if (depOrigin && constraint.entityB) depOrigins.set(constraint.entityB.node, depOrigin)\n  }\n\n  const result = solveConstraints([...memberNames], lowered)\n  if (!result.converged) {\n    throw new Error(\n      `[assembly] constraint solve did not converge (dof=${result.dof}); unsupported: ` +\n        (result.unsupported.length > 0 ? result.unsupported.join(', ') : '(no detail)'),\n    )\n  }\n\n  // per-member 终态（L6 修复）：恒等位姿（锚定/链根）不输出，引擎不重算\n  const transforms: AssemblyTransform[] = []\n  for (const [node, rawPose] of result.transforms) {\n    const pose: SolverPose = rawPose\n    if (isIdentityPose(pose)) continue\n    const index = memberNames.indexOf(node)\n    if (index < 0) continue\n    const pivot = depOrigins.get(node) ?? ([0, 0, 0] as AssemblyVec3)\n    transforms.push(poseToAssemblyTransform(pose, pivot, index))\n  }\n  return { transforms, dof: result.dof, converged: result.converged, unsupported: result.unsupported }\n}\n\n/**\n * 求解装配（约束 + 运动副，P3）：先跑约束求解得到 per-member 终态，再跑\n * solveKinematics 得到 joints 的 per-member 位姿，以**成员名**为键用 joints 结果\n * 覆盖同名成员的约束解，得到唯一一张表——**在库侧一次合并**，调用方一次性\n * setPendingAssemblyTransforms（禁止引擎侧两次登记）。\n *\n * 诊断不混用：joints 不参与 solveConstraints 的 converged/dof/unsupported 统计；\n * 覆盖发生时在 warnings 里各记一条（D-P3-1）。kinematics 为全成员位姿表（含\n * 恒等链根），供宿主从 ExecutionResult.kinematics 消费。\n *\n * joints 为空 → 退化为基础 solveAssembly 行为（无 kinematics/warnings 字段）。\n *\n * @param members - member shapes (aligned with memberNames).\n * @param memberNames - member variable names (R7: empty names throw).\n * @param constraints - raw constraints (may be empty).\n * @param joints - raw joint declarations (may be empty).\n * @param drive - per-child DOF value overrides (may be undefined).\n * @param opts - optional solver options (forwarded to the base constraint solve).\n * @returns the merged solve result (transforms + diagnostics + kinematics/warnings).\n */\nexport function solveAssemblyAndKinematics(\n  members: Shape[],\n  memberNames: string[],\n  constraints: AssemblyConstraint[],\n  joints: JointSpec[] = [],\n  drive?: Record<string, number | number[]>,\n  opts?: SolveOptions,\n): AssemblySolveResult {\n  const base = solveAssembly(members, memberNames, constraints, opts)\n  if (joints.length === 0) return base\n\n  const kin = solveKinematics(memberNames, joints, drive)\n  // 合并：以成员名为键，joints 结果覆盖同名成员的约束解（唯一一张表）\n  const merged = new Map<string, AssemblyTransform>()\n  for (const t of base.transforms) {\n    const name = memberNames[t.index]\n    if (name) merged.set(name, t)\n  }\n  const warnings: string[] = []\n  for (const t of kin.transforms) {\n    const name = memberNames[t.index]\n    if (!name) continue\n    if (merged.has(name)) {\n      warnings.push(`[assembly] joint '${name}' overrides the constraint solution for member '${name}'`)\n    }\n    merged.set(name, t)\n  }\n  // 按成员下标升序输出（与约束解的 Map 遍历序解耦，输出顺序确定）\n  const transforms = [...merged.entries()]\n    .map(([name, t]) => ({ name, t }))\n    .sort((a, b) => memberNames.indexOf(a.name) - memberNames.indexOf(b.name))\n    .map(({ t }) => t)\n\n  return {\n    transforms,\n    dof: base.dof,\n    converged: base.converged,\n    unsupported: base.unsupported,\n    kinematics: kin.kinematics,\n    warnings: warnings.length > 0 ? warnings : undefined,\n  }\n}\n"]}
+{"version":3,"file":"solve.js","sourceRoot":"","sources":["../../../src/api/assembly/solve.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * api/assembly/solve — 装配求解入口（P1，方案 §4.2）\n *\n * 流程：规范化（normalize）→ 降级（lower）→ brepjs solveConstraints\n *（拓扑轮次调度 / DOF / converged 全部由 brepjs 提供，零 brepjs 修改）→\n * per-member 终态 AssemblyTransform（修 L6：不再 per-constraint 增量叠加）。\n *\n * 不收敛 → 抛错（D3，错误信息带 unsupported 明细；对齐「绝不静默」约定）。\n * 恒等位姿的成员（锚定/链根）不输出变换——引擎不做无谓的几何重算。\n */\n\nimport type { Shape } from '../../mesh/types'\nimport type { BrepEngineApi } from '../../brep/engine/primitives'\nimport type { AssemblyTransform } from '../../runtime-state'\nimport { getBrepApi } from '../../brep/handle-bridge'\nimport { solveConstraints } from './solvers/chain-solver'\nimport { normalizeConstraint } from './normalize'\nimport { lowerStructuralConstraint } from './lower'\nimport { type EntityResolutionEnv } from './entities'\nimport { poseToAssemblyTransform, isIdentityPose, type SolverPose } from './pose'\nimport { solveKinematics, type JointSpec, type KinematicsPose } from './joints'\nimport type { AssemblyConstraint, AssemblyVec3 } from './types'\nimport type { SolveOptions } from './solvers/types'\nimport { solveGlobal } from './solvers/global-solver'\n\n/** 求解完整结果：per-member 终态变换 + 诊断量。 */\nexport interface AssemblySolveResult {\n  /** 每个被定位成员一条终态变换（index = 成员下标；恒等位姿不输出）。 */\n  transforms: AssemblyTransform[]\n  /** unsupported 约束的自由度合计（诊断量；收敛时为 0）。 */\n  dof: number\n  /** 是否全部约束可解（不收敛时 solveAssembly 已抛错，此字段恒 true）。 */\n  converged: boolean\n  /** 无法求解的约束明细（entity 类型不匹配 / 参考不可达）。 */\n  unsupported: string[]\n  /**\n   * P3：运动副解算的全成员位姿表（键 = 成员名；含恒等链根），\n   * 只有该装配声明了 joints 时才存在——宿主从 ExecutionResult.kinematics 消费。\n   */\n  kinematics?: Record<string, KinematicsPose>\n  /**\n   * P3：合并诊断（joints 覆盖约束解时各记一条；D-P3-1，不参与 converged 统计）。\n   */\n  warnings?: string[]\n  /**\n   * P1（global 求解器）：逐约束最终残差（CQ 代价的逐约束平方和）。chain 路径不填。\n   */\n  residuals?: number[]\n  /**\n   * P7/D1-3：欠定自由度诊断（仅 global 路径透传）。dof > 0 = 约束集欠定，\n   * 终态位姿依赖优化器轨迹、无唯一「正确解」——判等方应走规范判等通道而非逐位比对。\n   */\n  underdetermined?: { dof: number; freeDirs?: number[][] }\n}\n\n/**\n * 求解装配：members + memberNames + constraints → per-member 终态。\n *\n * @param members - member shapes (compound children, aligned with memberNames).\n * @param memberNames - member variable names (R7: empty names throw before solving).\n * @param constraints - raw constraints from `cad.assembly({ constraints })`.\n * @param opts - optional solver options (e.g. `solver: 'global'` selects the global least-squares path).\n * @returns the solve result (transforms + diagnostics).\n * @throws Error on empty member names, unknown constraint parts, or non-convergence.\n */\nexport function solveAssembly(\n  members: Shape[],\n  memberNames: string[],\n  constraints: AssemblyConstraint[],\n  opts?: SolveOptions,\n): AssemblySolveResult {\n  // P1：global 求解器分派（CadQuery 兼容全局最小二乘；零额外依赖）\n  if (opts?.solver === 'global') {\n    return solveGlobal(members, memberNames, constraints, opts)\n  }\n\n  // R7：成员名是 solver 的节点键，空串会让多成员互相覆盖——求解前断言\n  memberNames.forEach((name, i) => {\n    if (!name) {\n      throw new Error(\n        `[assembly] member at index ${i} has an empty name — members are referenced by variable name in constraints`,\n      )\n    }\n  })\n\n  const memberMap = new Map<string, Shape>()\n  members.forEach((m, i) => {\n    const name = memberNames[i]\n    if (name && !memberMap.has(name)) memberMap.set(name, m)\n  })\n  // kernel 仅 TopoRef/边引用解析需要；backends 未配置（纯位姿场景/单测）→ null，\n  // 此时快照引用仍可解，TopoRef 引用按 E_TOPO_NOT_FOUND 显式报错\n  let kernel: BrepEngineApi | null = null\n  try {\n    kernel = getBrepApi()\n  } catch {\n    // backends not configured — snapshot-form constraints still solvable\n  }\n  const env: EntityResolutionEnv = { kernel, memberOf: (p: string) => memberMap.get(p) }\n\n  const lowered: ReturnType<typeof lowerStructuralConstraint>['constraint'][] = []\n  const depOrigins = new Map<string, AssemblyVec3>()\n  for (const raw of constraints) {\n    const c = normalizeConstraint(raw)\n    const { constraint, depOrigin } = lowerStructuralConstraint(c, env)\n    lowered.push(constraint)\n    if (depOrigin && constraint.entityB) depOrigins.set(constraint.entityB.node, depOrigin)\n  }\n\n  const result = solveConstraints([...memberNames], lowered)\n  if (!result.converged) {\n    throw new Error(\n      `[assembly] constraint solve did not converge (dof=${result.dof}); unsupported: ` +\n        (result.unsupported.length > 0 ? result.unsupported.join(', ') : '(no detail)'),\n    )\n  }\n\n  // per-member 终态（L6 修复）：恒等位姿（锚定/链根）不输出，引擎不重算\n  const transforms: AssemblyTransform[] = []\n  for (const [node, rawPose] of result.transforms) {\n    const pose: SolverPose = rawPose\n    if (isIdentityPose(pose)) continue\n    const index = memberNames.indexOf(node)\n    if (index < 0) continue\n    const pivot = depOrigins.get(node) ?? ([0, 0, 0] as AssemblyVec3)\n    transforms.push(poseToAssemblyTransform(pose, pivot, index))\n  }\n  return { transforms, dof: result.dof, converged: result.converged, unsupported: result.unsupported }\n}\n\n/**\n * 求解装配（约束 + 运动副，P3）：先跑约束求解得到 per-member 终态，再跑\n * solveKinematics 得到 joints 的 per-member 位姿，以**成员名**为键用 joints 结果\n * 覆盖同名成员的约束解，得到唯一一张表——**在库侧一次合并**，调用方一次性\n * setPendingAssemblyTransforms（禁止引擎侧两次登记）。\n *\n * 诊断不混用：joints 不参与 solveConstraints 的 converged/dof/unsupported 统计；\n * 覆盖发生时在 warnings 里各记一条（D-P3-1）。kinematics 为全成员位姿表（含\n * 恒等链根），供宿主从 ExecutionResult.kinematics 消费。\n *\n * joints 为空 → 退化为基础 solveAssembly 行为（无 kinematics/warnings 字段）。\n *\n * @param members - member shapes (aligned with memberNames).\n * @param memberNames - member variable names (R7: empty names throw).\n * @param constraints - raw constraints (may be empty).\n * @param joints - raw joint declarations (may be empty).\n * @param drive - per-child DOF value overrides (may be undefined).\n * @param opts - optional solver options (forwarded to the base constraint solve).\n * @returns the merged solve result (transforms + diagnostics + kinematics/warnings).\n */\nexport function solveAssemblyAndKinematics(\n  members: Shape[],\n  memberNames: string[],\n  constraints: AssemblyConstraint[],\n  joints: JointSpec[] = [],\n  drive?: Record<string, number | number[]>,\n  opts?: SolveOptions,\n): AssemblySolveResult {\n  const base = solveAssembly(members, memberNames, constraints, opts)\n  if (joints.length === 0) return base\n\n  const kin = solveKinematics(memberNames, joints, drive)\n  // 合并：以成员名为键，joints 结果覆盖同名成员的约束解（唯一一张表）\n  const merged = new Map<string, AssemblyTransform>()\n  for (const t of base.transforms) {\n    const name = memberNames[t.index]\n    if (name) merged.set(name, t)\n  }\n  const warnings: string[] = []\n  for (const t of kin.transforms) {\n    const name = memberNames[t.index]\n    if (!name) continue\n    if (merged.has(name)) {\n      warnings.push(`[assembly] joint '${name}' overrides the constraint solution for member '${name}'`)\n    }\n    merged.set(name, t)\n  }\n  // 按成员下标升序输出（与约束解的 Map 遍历序解耦，输出顺序确定）\n  const transforms = [...merged.entries()]\n    .map(([name, t]) => ({ name, t }))\n    .sort((a, b) => memberNames.indexOf(a.name) - memberNames.indexOf(b.name))\n    .map(({ t }) => t)\n\n  return {\n    transforms,\n    dof: base.dof,\n    converged: base.converged,\n    unsupported: base.unsupported,\n    kinematics: kin.kinematics,\n    warnings: warnings.length > 0 ? warnings : undefined,\n  }\n}\n"]}

package/dist/api/assembly/solvers/global-solver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"global-solver.d.ts","sourceRoot":"","sources":["../../../../src/api/assembly/solvers/global-solver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAIhD,OAAO,KAAK,EAAE,kBAAkB,EAAa,MAAM,UAAU,CAAA;AAQ7D,OAAO,EAAE,KAAK,YAAY,EAAqB,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAA;AA8PtF;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,KAAK,EAAE,EAChB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,kBAAkB,EAAE,EACjC,IAAI,CAAC,EAAE,YAAY,GAClB,iBAAiB,CA6UnB"}
+{"version":3,"file":"global-solver.d.ts","sourceRoot":"","sources":["../../../../src/api/assembly/solvers/global-solver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAIhD,OAAO,KAAK,EAAE,kBAAkB,EAAa,MAAM,UAAU,CAAA;AAQ7D,OAAO,EAAE,KAAK,YAAY,EAAqB,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAsStF;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,KAAK,EAAE,EAChB,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,kBAAkB,EAAE,EACjC,IAAI,CAAC,EAAE,YAAY,GAClB,iBAAiB,CAoYnB"}

package/dist/api/assembly/solvers/global-solver.js

@@ -22,7 +22,8 @@ import { normalizeConstraint } from '../normalize.js';
 import { poseToAssemblyTransform } from '../pose.js';
 import { resolveFaceGeometryOfRef, resolveSolverEntity, } from '../entities.js';
 import { vadd, vsub, vdot, vscale, vnormalize, vsumsqr, ata, atb, solveDampedNormal, } from './linalg.js';
-import { rotateByR, quatFromR } from './pose-from-delta.js';
+import { rotateByR, quatFromR, quatToRvec } from './pose-from-delta.js';
+import { quatMultiply, quatRotate } from './quat.js';
 const DEG2RAD = Math.PI / 180;
 const R_INIT = 1e-2; // B3
 const LM_LAMBDA0 = 1e-3;
@@ -86,7 +87,7 @@ function termResidual(t, sa, sb, scale) {
             const d = vscale(vsub(pa, pb), inv);
             if (Math.abs(t.val) < 1e-12)
                 return d; // 3-vec，val=0
-            return [vsumsqr(d) - (t.val / scale) ** 2]; // 1-vec，val≠0
+            return [vsumsqr(d) - (t.val * inv) ** 2]; // 1-vec，val≠0（目标值与残差同除 scale）
         }
         case 'axis': {
             const d1 = markerDir(t.ma, sa.R);
@@ -114,7 +115,11 @@ function termResidual(t, sa, sb, scale) {
             const perp = vscale(vsub(delta, vscale(dln, vdot(delta, dln))), inv);
             if (Math.abs(t.val) < 1e-12)
                 return perp; // 3-vec，val=0
-            return [vsumsqr(perp) - t.val]; // 1-vec，val≠0（注意 val 不缩放）
+            // 1-vec，val≠0：perp 已除 scale → vsumsqr(perp) = (dist/scale)²；
+            // 目标值必须同尺度（t.val·inv）²，否则实际满足 dist = scale·√val。
+            // （历史缺陷：此处曾写 `vsumsqr(perp) - t.val`，val 不缩放——金丝雀见
+            // planetary-static.test.ts distance 用例，修复后该断言已翻转为 ORBIT_R。）
+            return [vsumsqr(perp) - (t.val * inv) ** 2];
         }
     }
 }
@@ -133,12 +138,22 @@ function residualDim(t) {
 }
 void residualDim; // P7/D1-1：诊断参考表（秩判定走列归一特征值，见下）
 /**
- * 对称 n×n 矩阵的特征值（循环 Jacobi 旋转）。
+ * 对称 n×n 矩阵的特征分解（循环 Jacobi 旋转）。
  *
+ * @param A      行主 n×n 对称矩阵（会被复制，不修改原矩阵）。
+ * @param n      阶数。
+ * @param outVec 可选输出：n×n 行主特征向量矩阵 V（列 v[:,i] 是 outVec[i] 对应的
+ *   特征向量）。传 `V`（单位矩阵）时原地累积旋转。
  * @returns 特征值数组（无序）；扫掠不收敛返回 null（调用方走保守 fallback）。
  */
-function symEigenvalues(A, n) {
+function symEigenvalues(A, n, outVec) {
     const a = A.slice();
+    if (outVec)
+        for (let i = 0; i < n * n; i++)
+            outVec[i] = 0;
+    if (outVec)
+        for (let i = 0; i < n; i++)
+            outVec[i * n + i] = 1;
     for (let sweep = 0; sweep < 60; sweep++) {
         let off = 0;
         for (let p = 0; p < n; p++) {
@@ -169,6 +184,14 @@ function symEigenvalues(A, n) {
                     a[p * n + k] = c * apk - s * aqk;
                     a[q * n + k] = s * apk + c * aqk;
                 }
+                if (outVec) {
+                    for (let k = 0; k < n; k++) {
+                        const vkp = outVec[k * n + p];
+                        const vkq = outVec[k * n + q];
+                        outVec[k * n + p] = c * vkp - s * vkq;
+                        outVec[k * n + q] = s * vkp + c * vkq;
+                    }
+                }
             }
         }
         if (sweep === 59)
@@ -195,7 +218,7 @@ function symEigenvalues(A, n) {
  *
  * @returns 剩余自由度（0 = 适定）；特征分解不收敛时保守报 0（不阻塞消费方）。
  */
-function computeUnderdeterminedDof(terms, scale, n, x, stateOf) {
+function computeUnderdeterminedDof(terms, scale, n, x, stateOf, outFreeDirs) {
     if (n === 0)
         return 0;
     // 仅约束残差（剔除 penalty 正则行）
@@ -243,14 +266,37 @@ function computeUnderdeterminedDof(terms, scale, n, x, stateOf) {
             Jn[row * n + col] /= d;
     }
     const JtJ = ata(Jn, m, n);
-    const eig = symEigenvalues(JtJ, n);
+    const V = new Array(n * n).fill(0);
+    const eig = symEigenvalues(JtJ, n, V);
     if (!eig)
         return 0; // 保守 fallback（适定假设，不阻塞）
     const lambdaMax = Math.max(...eig.map(Math.abs));
     if (!(lambdaMax > 1e-300))
         return freeCols + n; // 理论不可达；防御
     const rank = eig.filter((v) => Math.abs(v) > lambdaMax * 1e-8).length;
-    return Math.max(0, n - rank);
+    const dof = Math.max(0, n - rank);
+    // P7/D1-4：零空间特征向量（λ < λmax·1e-8 的列）= 欠定自由方向（变量系：
+    // 每成员 6 维 [tx,ty,tz,rx,ry,rz]，列范数已归一）。旋转分量为主的方向对
+    // 位姿判等有意义；调用方按需解释。
+    if (outFreeDirs && dof > 0) {
+        for (let i = 0; i < n; i++) {
+            if (Math.abs(eig[i]) > lambdaMax * 1e-8)
+                continue;
+            const v = new Array(n);
+            for (let r = 0; r < n; r++)
+                v[r] = V[r * n + i];
+            outFreeDirs.push(v);
+        }
+        // 零范数列（约束摸不到的坐标轴方向）也是自由方向，补在后面
+        for (let col = 0; col < n; col++) {
+            if (norms[col] > 1e-12)
+                continue;
+            const v = new Array(n).fill(0);
+            v[col] = 1;
+            outFreeDirs.push(v);
+        }
+    }
+    return dof;
 }
 /**
  * 纯 TS global 求解器入口。
@@ -451,13 +497,31 @@ export function solveGlobal(members, memberNames, constraints, opts) {
     // ── scale = 所有 marker 点的包围盒对角长（CQ B5；marker 近似几何 bbox） ──
     const scale = computeScale(scalePts);
     // ── 自由成员与变量 ──
+    // P8 刚体分组：同组成员共享一个 6 维状态块（子装配在 CQ 语义里是刚体）。
+    // freeIdx 每项是一个块的"代表成员"下标；blockOf 把每个自由成员映射到其块位置 k
+    // （代表自身与跟随者都映射到同一 k——stateOf 按成员直接查块，无需二次 rep 解析）。
     const freeIdx = [];
-    const blockMap = new Map();
+    const blockOf = new Map();
+    const groupOf = new Map(); // member idx -> 代表成员 idx
+    if (opts?.rigidGroups) {
+        for (const g of opts.rigidGroups) {
+            for (const m of g)
+                groupOf.set(m, g[0]);
+        }
+    }
     memberNames.forEach((_, i) => {
-        if (!lockedSet.has(i)) {
-            blockMap.set(i, freeIdx.length);
-            freeIdx.push(i);
+        if (lockedSet.has(i))
+            return;
+        const rep = groupOf.get(i) ?? i;
+        // 组代表被锁：整组随锁（跟随者也不进自由集）。
+        if (lockedSet.has(rep))
+            return;
+        let k = freeIdx.indexOf(rep);
+        if (k < 0) {
+            k = freeIdx.length;
+            freeIdx.push(rep);
         }
+        blockOf.set(i, k);
     });
     const n = freeIdx.length * 6;
     const x = new Array(n).fill(0);
@@ -466,17 +530,45 @@ export function solveGlobal(members, memberNames, constraints, opts) {
         x[6 * k + 4] = R_INIT;
         x[6 * k + 5] = R_INIT;
     }
+    // P8 方案 A（CQ sublocs 语义）：成员建模坐标是装配前本地系，约束 marker 取自
+    // 该本地系；求解器状态是 delta，绝对位姿 = initialPose ∘ delta（penalty 拉
+    // delta→0 = 倾向保持初 loc）。未传 initialPoses 时初位姿为恒等——与旧 delta
+    // 语义完全一致（回归零影响）。
+    // 关键：init 按【成员下标】存，delta 按块共享——刚体组成员初位各不同
+    // （nested_assy：b2 初 (0,4,0)、b3 初 (0,8,0)），同一 delta 下绝对位姿各异；
+    // 若 init 按块存，跟随者会错拿代表的初位（实测 b2 错落 (2,0,0.75)，ref (2,−4,0.75)）。
+    const initT = new Map();
+    const initQ = new Map();
+    if (opts?.initialPoses) {
+        opts.initialPoses.forEach((ip, i) => {
+            if (!ip)
+                return;
+            initT.set(i, [ip.translation[0], ip.translation[1], ip.translation[2]]);
+            initQ.set(i, [ip.rotation[0], ip.rotation[1], ip.rotation[2], ip.rotation[3]]);
+        });
+    }
     const stateOf = (xx, i) => {
         // 世界哨兵 i = -1：identity（世界系 marker 已存字面坐标，不再施加成员变换）
         if (i < 0)
             return { T: [0, 0, 0], R: [0, 0, 0] };
         if (lockedSet.has(i))
             return { T: [0, 0, 0], R: [0, 0, 0] };
-        const k = blockMap.get(i);
-        return {
-            T: [xx[6 * k], xx[6 * k + 1], xx[6 * k + 2]],
-            R: [xx[6 * k + 3], xx[6 * k + 4], xx[6 * k + 5]],
-        };
+        const k = blockOf.get(i);
+        if (k === undefined)
+            return { T: [0, 0, 0], R: [0, 0, 0] };
+        const dT = [xx[6 * k], xx[6 * k + 1], xx[6 * k + 2]];
+        const dR = [xx[6 * k + 3], xx[6 * k + 4], xx[6 * k + 5]];
+        const it = initT.get(i);
+        const iq = initQ.get(i);
+        if (!it || !iq)
+            return { T: dT, R: dR };
+        // absolute = initial ∘ delta：先转 delta 再平移初 loc。
+        const qd = quatFromR(dR[0], dR[1], dR[2]);
+        const at = vadd(it, quatRotate(iq, dT));
+        const aq = quatMultiply(iq, qd);
+        // 绝对四元数 → 旋转向量（pose-from-delta 的 R 约定），供 markerPoint 复用。
+        const Rm = quatToRvec(aq);
+        return { T: at, R: Rm };
     };
     const residual = (xx) => {
         const r = [];
@@ -558,13 +650,25 @@ export function solveGlobal(members, memberNames, constraints, opts) {
     }
     // ── 组装结果 ──
     const transforms = [];
+    // P8 方案 A：发射绝对位姿 = initial ∘ delta（stateOf 终态），不再裸发 delta。
     for (let k = 0; k < freeIdx.length; k++) {
         const i = freeIdx[k];
-        const T = [x[6 * k], x[6 * k + 1], x[6 * k + 2]];
-        const R = [x[6 * k + 3], x[6 * k + 4], x[6 * k + 5]];
-        const pose = { position: T, rotation: quatFromR(R[0], R[1], R[2]) };
+        const st = stateOf(x, i);
+        const pose = { position: st.T, rotation: quatFromR(st.R[0], st.R[1], st.R[2]) };
         transforms.push(poseToAssemblyTransform(pose, [0, 0, 0], i));
     }
+    // P8 刚体分组：跟随成员与组代表共享同一刚体位姿——为每个跟随者补一条
+    // 同 pose 的 transform（index=跟随者），否则 solve-tree 的 recompose 拿不到
+    // 组员的变换（nested_assy 的 b3 叶会缺条目）。
+    for (const [member, rep] of groupOf) {
+        if (member === rep)
+            continue;
+        if (lockedSet.has(member))
+            continue;
+        const st = stateOf(x, rep);
+        const pose = { position: st.T, rotation: quatFromR(st.R[0], st.R[1], st.R[2]) };
+        transforms.push(poseToAssemblyTransform(pose, [0, 0, 0], member));
+    }
     // 逐约束残差（诊断）
     const residuals = [];
     const warnings = [];
@@ -580,13 +684,16 @@ export function solveGlobal(members, memberNames, constraints, opts) {
         if (r > RESIDUAL_WARN * scale)
             warnings.push(`constraint #${cid} residual=${r.toExponential(3)} (> ${RESIDUAL_WARN * scale})`);
     });
-    // P7/D1-2：欠定自由度诊断（剔除 penalty 正则行后按 JᵀJc 特征值秩判定）
-    const underdeterminedDof = computeUnderdeterminedDof(terms, scale, n, x, stateOf);
+    // P7/D1-2/D1-4：欠定自由度诊断 + 零空间自由方向（变量系 6 维块 [tx,ty,tz,rx,ry,rz]）
+    const freeDirs = [];
+    const underdeterminedDof = computeUnderdeterminedDof(terms, scale, n, x, stateOf, freeDirs);
     return {
         transforms,
         dof: 0,
         // P7/D1-3：旧 `dof` 字段语义不变（unsupported 合计的占位），欠定信息走新字段。
-        underdetermined: underdeterminedDof > 0 ? { dof: underdeterminedDof } : undefined,
+        underdetermined: underdeterminedDof > 0
+            ? { dof: underdeterminedDof, freeDirs: freeDirs.map((v) => v.map((c) => Math.abs(c) < 1e-12 ? 0 : +c.toFixed(12))) }
+            : undefined,
         converged: true,
         unsupported,
         residuals,