@faicad/faijs 0.13.0

package/dist/api/internal/dual-form-args.js

@@ -0,0 +1,217 @@
+/**
+ * dual-form-args — D11 参数双形态归一化判别器
+ *
+ * 设计文档：docs/plans/2026-09-03-faijs-brepjs-compat-api.md §4.2 / §4.3.2
+ *
+ * 本文件实现参数双形态归一化（D11）：
+ * - A 类（明显可区分）：单名双形态，函数内部按参数形态切换实现
+ * - B1 类（人类看来不明显）：单名单形态，brepjs options 对象即唯一对象形态
+ * - B2 类（人类看来不明显）：双名，brepjs 形态占正名，faijs 对象形态加描述性后缀
+ *
+ * 判别规则：
+ * 1. 首参是 plain object（Object.getPrototypeOf(a) === Object.prototype）
+ *    且非 Shape、非句柄、非数组 → 对象形态
+ * 2. 否则 → 位置形态
+ *
+ * 对象形态映射：
+ * - 按 params 表（机器参数名）将对象键映射为位置数组
+ * - 缺省键 → undefined
+ * - 对象形态含 params 外未知键 → 抛 E_ARGS_FORM
+ *
+ * B2 条目不走判别器（两个名字各自固定形态）。
+ */
+import { isShape } from '../../shape.js';
+/** 句柄类型守卫（vendored 句柄有 .wrapped 属性）。 */
+function isHandleLike(v) {
+    return typeof v === 'object' && v !== null && 'wrapped' in v;
+}
+/**
+ * 判定参数是否为对象形态。
+ *
+ * 判别式（全仓统一）：
+ * - 首参是 plain object（Object.getPrototypeOf(a) === Object.prototype）
+ * - 且非 Shape、非句柄、非数组
+ *
+ * @param args - 调用参数数组
+ * @returns 是否为对象形态
+ */
+export function isObjectForm(args) {
+    if (args.length === 0)
+        return false;
+    const first = args[0];
+    if (first === null || typeof first !== 'object')
+        return false;
+    if (Array.isArray(first))
+        return false;
+    if (isShape(first))
+        return false;
+    if (isHandleLike(first))
+        return false;
+    return Object.getPrototypeOf(first) === Object.prototype;
+}
+/**
+ * 将对象形态参数归一化为位置数组。
+ *
+ * @param obj - 对象形态参数
+ * @param params - 机器参数名表
+ * @param opName - op 名（错误信息用）
+ * @returns 位置数组（缺省键 → undefined）
+ * @throws E_ARGS_FORM 对象含 params 外未知键时
+ */
+export function normalizeObjectForm(obj, params, opName) {
+    const keys = Object.keys(obj);
+    const unknownKeys = keys.filter(k => !params.includes(k));
+    if (unknownKeys.length > 0) {
+        throw new Error(`[faijs/args] ${opName}: E_ARGS_FORM: unexpected parameter(s): ${unknownKeys.join(', ')}. ` +
+            `Expected: ${params.join(', ')}`);
+    }
+    return params.map(k => obj[k]);
+}
+/**
+ * 参数双形态归一化判别器。
+ *
+ * 根据 args 和 spec 归一化参数：
+ * - B2 条目：直接返回原样（两个名字各自固定形态）
+ * - B1 条目：直接返回原样（brepjs options 对象即唯一对象形态，§4.2「无需判别」）
+ * - 对象形态：按 params 表映射为位置数组
+ * - 位置形态：直接返回原样
+ *
+ * B1 为何原样返回：B1 的 brepjs 位置形态首参本身就是配置对象（如
+ * `thread(options: ThreadOptions)`），对象形态与它在首参上撞型，判别式失效；
+ * 方案 §4.2 B1 的定义即「faijs 侧无独立对象 schema 时，直接以 brepjs options
+ * 对象为唯一对象形态（单名单形态，无需判别）」。若在此处按 params 表归一，
+ * 任何 options 键都会因不在 params 表里而误抛 E_ARGS_FORM。
+ *
+ * @param args - 调用参数数组
+ * @param spec - 参数规格
+ * @returns 归一化后的参数数组
+ * @throws E_ARGS_FORM 形态无法匹配或对象含未知键时
+ */
+export function resolveArgs(args, spec) {
+    // B2 条目不走判别器（两个名字各自固定形态）
+    if (spec.formClass === 'B2') {
+        return args;
+    }
+    // B1 条目：brepjs options 对象即唯一对象形态，无需判别（§4.2）
+    if (spec.formClass === 'B1') {
+        return args;
+    }
+    // 无 params 表时无法归一化对象形态，只能接受位置形态
+    if (!spec.params) {
+        if (isObjectForm(args)) {
+            throw new Error(`[faijs/args] ${spec.name}: E_ARGS_FORM: object form requires params specification`);
+        }
+        return args;
+    }
+    // 判定形态
+    if (isObjectForm(args)) {
+        // 对象形态 → 位置数组
+        return normalizeObjectForm(args[0], spec.params, spec.name);
+    }
+    // 位置形态 → 原样返回
+    return args;
+}
+/**
+ * 参数双形态归一化判别器（带形态信息）。
+ *
+ * 与 resolveArgs 相同，但返回形态信息。
+ *
+ * @param args - 调用参数数组
+ * @param spec - 参数规格
+ * @returns 归一化结果
+ */
+export function resolveArgsWithInfo(args, spec) {
+    if (spec.formClass === 'B2' || spec.formClass === 'B1') {
+        return { args, isObjectForm: false };
+    }
+    if (!spec.params) {
+        if (isObjectForm(args)) {
+            throw new Error(`[faijs/args] ${spec.name}: E_ARGS_FORM: object form requires params specification`);
+        }
+        return { args, isObjectForm: false };
+    }
+    if (isObjectForm(args)) {
+        return {
+            args: normalizeObjectForm(args[0], spec.params, spec.name),
+            isObjectForm: true,
+        };
+    }
+    return { args, isObjectForm: false };
+}
+/** 判定值是否是可作为对象形态形参的 plain object（与 {@link isObjectForm} 同判别式）。 */
+function isPlainObjectValue(v) {
+    if (v === null || typeof v !== 'object')
+        return false;
+    if (Array.isArray(v))
+        return false;
+    if (isShape(v))
+        return false;
+    if (isHandleLike(v))
+        return false;
+    return Object.getPrototypeOf(v) === Object.prototype;
+}
+/**
+ * 位置形态 → 对象形态归一（faijs 特有 dual op 的 D11 反方向）。
+ *
+ * 触发条件：声明了 slotMap 且对象槽位（第 `shapeArity` 个实参）不是
+ * plain object。已是对象形态或实参不足时原样返回（交由 op 自身的断言报错）。
+ *
+ * @param args - 调用参数数组
+ * @param form - slotMap 声明（位置槽→对象键装箱表）
+ * @param name - op 名（错误信息用）
+ * @returns 归一后的参数数组（前置 Shape 原样 + 末尾一个对象形态参数）
+ * @throws E_ARGS_FORM 位置参数个数与声明的槽位不匹配时
+ */
+export function positionalToObject(args, form, name) {
+    const shapeArity = form.shapeArity ?? 0;
+    if (args.length <= shapeArity)
+        return args; // 无位置形参可装箱 → 原样（op 断言报错）
+    if (isPlainObjectValue(args[shapeArity]))
+        return args; // 已是对象形态
+    const rest = args.slice(shapeArity);
+    const obj = {};
+    let i = 0;
+    for (const key of form.keys) {
+        if (i >= rest.length)
+            break;
+        // §6.2 尾参 options：当前实参是 plain object（候选尾参 options）→ 停止装箱
+        // 交给下方 options 合并，不让任何槽位把它吞进拓扑参数
+        // （`box(20,{centered:true})` / `cylinder(5,40,{centered:true})`）。
+        if (isPlainObjectValue(rest[i]))
+            break;
+        if (form.vec3Keys?.includes(key)) {
+            // vec3 槽位：吃掉最多 3 个连续实参（1 个 → 标量，2~3 个 → 数组）。
+            // 若剩余序列最末是 plain object（候选尾参 options），先为它留位，不让
+            // 跨槽 vec3 把 options 吞进拓扑参数（`box(10,20,30,{centered:true})`）。
+            const avail = rest.length - i;
+            const reserveOptions = avail > 1 && isPlainObjectValue(rest[rest.length - 1]) ? 1 : 0;
+            const take = Math.min(3, avail - reserveOptions);
+            const chunk = rest.slice(i, i + take);
+            obj[key] = take === 1 ? chunk[0] : chunk;
+            i += take;
+            continue;
+        }
+        obj[key] = rest[i];
+        i += 1;
+    }
+    // D11 尾参 options 合并（§6.2）：位置槽装箱后，若剩余实参恰好 1 个且为
+    // plain object → 作为 options 并入 args。让 `box(10,20,30,{centered:true})`、
+    // `sphere(5,{at,segments})`、`cylinder(5,40,{centered:true})` 在脚本面可用。
+    if (i < rest.length) {
+        if (rest.length - i === 1 && isPlainObjectValue(rest[i])) {
+            const opts = rest[i];
+            const dup = Object.keys(opts).filter((k) => form.keys.includes(k) || k in obj);
+            if (dup.length > 0) {
+                throw new Error(`[faijs/args] ${name}: E_ARGS_FORM: option key(s) ${dup.join(', ')} ` +
+                    `conflict with positional slot(s) (${form.keys.join(', ')})`);
+            }
+            Object.assign(obj, opts);
+            return [...args.slice(0, shapeArity), obj];
+        }
+        throw new Error(`[faijs/args] ${name}: E_ARGS_FORM: expected ${form.keys.join(', ')} ` +
+            `(${form.keys.length} positional slot(s)); got ${rest.length} value(s): ` +
+            rest.map((a) => (typeof a === 'object' ? '[object]' : String(a))).join(', '));
+    }
+    return [...args.slice(0, shapeArity), obj];
+}
+//# sourceMappingURL=dual-form-args.js.map

package/dist/api/internal/dual-form-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dual-form-args.js","sourceRoot":"","sources":["../../../src/api/internal/dual-form-args.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * dual-form-args — D11 参数双形态归一化判别器\n *\n * 设计文档：docs/plans/2026-09-03-faijs-brepjs-compat-api.md §4.2 / §4.3.2\n *\n * 本文件实现参数双形态归一化（D11）：\n * - A 类（明显可区分）：单名双形态，函数内部按参数形态切换实现\n * - B1 类（人类看来不明显）：单名单形态，brepjs options 对象即唯一对象形态\n * - B2 类（人类看来不明显）：双名，brepjs 形态占正名，faijs 对象形态加描述性后缀\n *\n * 判别规则：\n * 1. 首参是 plain object（Object.getPrototypeOf(a) === Object.prototype）\n *    且非 Shape、非句柄、非数组 → 对象形态\n * 2. 否则 → 位置形态\n *\n * 对象形态映射：\n * - 按 params 表（机器参数名）将对象键映射为位置数组\n * - 缺省键 → undefined\n * - 对象形态含 params 外未知键 → 抛 E_ARGS_FORM\n *\n * B2 条目不走判别器（两个名字各自固定形态）。\n */\n\nimport { isShape } from '../../shape'\n\n/** 形态分类。 */\nexport type FormClass = 'A' | 'B1' | 'B2'\n\n/** 参数规格。 */\nexport interface ArgSpec {\n  /** op 名（错误信息用）。 */\n  name: string\n  /** 机器参数名表（按位置顺序），用于对象形态→位置数组映射。 */\n  params?: string[]\n  /** 形态分类。 */\n  formClass: FormClass\n}\n\n/** 句柄类型守卫（vendored 句柄有 .wrapped 属性）。 */\nfunction isHandleLike(v: unknown): boolean {\n  return typeof v === 'object' && v !== null && 'wrapped' in v\n}\n\n/**\n * 判定参数是否为对象形态。\n *\n * 判别式（全仓统一）：\n * - 首参是 plain object（Object.getPrototypeOf(a) === Object.prototype）\n * - 且非 Shape、非句柄、非数组\n *\n * @param args - 调用参数数组\n * @returns 是否为对象形态\n */\nexport function isObjectForm(args: unknown[]): boolean {\n  if (args.length === 0) return false\n  const first = args[0]\n  if (first === null || typeof first !== 'object') return false\n  if (Array.isArray(first)) return false\n  if (isShape(first)) return false\n  if (isHandleLike(first)) return false\n  return Object.getPrototypeOf(first) === Object.prototype\n}\n\n/**\n * 将对象形态参数归一化为位置数组。\n *\n * @param obj - 对象形态参数\n * @param params - 机器参数名表\n * @param opName - op 名（错误信息用）\n * @returns 位置数组（缺省键 → undefined）\n * @throws E_ARGS_FORM 对象含 params 外未知键时\n */\nexport function normalizeObjectForm(\n  obj: Record<string, unknown>,\n  params: string[],\n  opName: string,\n): unknown[] {\n  const keys = Object.keys(obj)\n  const unknownKeys = keys.filter(k => !params.includes(k))\n  if (unknownKeys.length > 0) {\n    throw new Error(\n      `[faijs/args] ${opName}: E_ARGS_FORM: unexpected parameter(s): ${unknownKeys.join(', ')}. ` +\n      `Expected: ${params.join(', ')}`\n    )\n  }\n  return params.map(k => obj[k])\n}\n\n/**\n * 参数双形态归一化判别器。\n *\n * 根据 args 和 spec 归一化参数：\n * - B2 条目：直接返回原样（两个名字各自固定形态）\n * - B1 条目：直接返回原样（brepjs options 对象即唯一对象形态，§4.2「无需判别」）\n * - 对象形态：按 params 表映射为位置数组\n * - 位置形态：直接返回原样\n *\n * B1 为何原样返回：B1 的 brepjs 位置形态首参本身就是配置对象（如\n * `thread(options: ThreadOptions)`），对象形态与它在首参上撞型，判别式失效；\n * 方案 §4.2 B1 的定义即「faijs 侧无独立对象 schema 时，直接以 brepjs options\n * 对象为唯一对象形态（单名单形态，无需判别）」。若在此处按 params 表归一，\n * 任何 options 键都会因不在 params 表里而误抛 E_ARGS_FORM。\n *\n * @param args - 调用参数数组\n * @param spec - 参数规格\n * @returns 归一化后的参数数组\n * @throws E_ARGS_FORM 形态无法匹配或对象含未知键时\n */\nexport function resolveArgs(args: unknown[], spec: ArgSpec): unknown[] {\n  // B2 条目不走判别器（两个名字各自固定形态）\n  if (spec.formClass === 'B2') {\n    return args\n  }\n  // B1 条目：brepjs options 对象即唯一对象形态，无需判别（§4.2）\n  if (spec.formClass === 'B1') {\n    return args\n  }\n\n  // 无 params 表时无法归一化对象形态，只能接受位置形态\n  if (!spec.params) {\n    if (isObjectForm(args)) {\n      throw new Error(\n        `[faijs/args] ${spec.name}: E_ARGS_FORM: object form requires params specification`\n      )\n    }\n    return args\n  }\n\n  // 判定形态\n  if (isObjectForm(args)) {\n    // 对象形态 → 位置数组\n    return normalizeObjectForm(\n      args[0] as Record<string, unknown>,\n      spec.params,\n      spec.name,\n    )\n  }\n\n  // 位置形态 → 原样返回\n  return args\n}\n\n/**\n * 双形态归一化结果。\n *\n * 包含归一化后的参数和是否为对象形态的标记。\n */\nexport interface ResolvedArgs {\n  /** 归一化后的参数数组。 */\n  args: unknown[]\n  /** 是否为对象形态。 */\n  isObjectForm: boolean\n}\n\n/**\n * 参数双形态归一化判别器（带形态信息）。\n *\n * 与 resolveArgs 相同，但返回形态信息。\n *\n * @param args - 调用参数数组\n * @param spec - 参数规格\n * @returns 归一化结果\n */\nexport function resolveArgsWithInfo(args: unknown[], spec: ArgSpec): ResolvedArgs {\n  if (spec.formClass === 'B2' || spec.formClass === 'B1') {\n    return { args, isObjectForm: false }\n  }\n\n  if (!spec.params) {\n    if (isObjectForm(args)) {\n      throw new Error(\n        `[faijs/args] ${spec.name}: E_ARGS_FORM: object form requires params specification`\n      )\n    }\n    return { args, isObjectForm: false }\n  }\n\n  if (isObjectForm(args)) {\n    return {\n      args: normalizeObjectForm(\n        args[0] as Record<string, unknown>,\n        spec.params,\n        spec.name,\n      ),\n      isObjectForm: true,\n    }\n  }\n\n  return { args, isObjectForm: false }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// 反方向：位置形态 → 对象形态（faijs 特有 dual op，impl 原生对象形态）\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * 位置形态声明（D11 反方向，§4.2「归一方向 = 位置→对象」）。\n *\n * faijs 特有 dual op 的 impl 是对象形态原生（`box(width, depth, height)` 经\n * 装箱为 `{ width, depth, height, ... }`，`translate(shape, { offset })`），brepjs 生态\n * 的位置形态（`box(10, 20, 30, { centered: true })` / `translate(shape, 1, 0, 0)`）\n * 需先归一成对象形态。\n * 声明式而非 if 分支：op 作者只列「哪个键吃几个位置参数」，判别与装箱由\n * {@link positionalToObject} 统一完成。\n *\n * 与语句层的 `StatementSummary.positional`（位置实参**值**）以及投影侧的\n * `ArgSpec.params`（对象→位置**参数名表**）是三个不同概念：`SlotMap` 是\n * 位置槽→对象键的**装箱声明**（位置→对象，D11 反方向；§9 命名区分）。\n */\nexport interface SlotMap {\n  /**\n   * 对象形态键名，按位置顺序（只描述 Shape 之后的**非几何**形参）。\n   * 例：`box(10, 20, 30)` → `keys: ['size']`；`cylinder(5, 40)` →\n   * `keys: ['radius', 'height']`。\n   */\n  keys: string[]\n  /**\n   * 哪些键是 vec3 槽位（吃掉最多 3 个连续位置参数）。\n   * 1 个 → 标量（number 或数组原样）；2~3 个 → `[x, y(, z)]` 数组。\n   * 例：`box(10)` → `{ size: 10 }`；`box(10, 20, 30)` → `{ size: [10, 20, 30] }`。\n   */\n  vec3Keys?: string[]\n  /**\n   * 前置 Shape 形参个数（原样透传，不参与装箱），缺省 0。\n   * 例：`translate(shape, 1, 0, 0)` → `shapeArity: 1`。\n   */\n  shapeArity?: number\n}\n\n/** 判定值是否是可作为对象形态形参的 plain object（与 {@link isObjectForm} 同判别式）。 */\nfunction isPlainObjectValue(v: unknown): boolean {\n  if (v === null || typeof v !== 'object') return false\n  if (Array.isArray(v)) return false\n  if (isShape(v)) return false\n  if (isHandleLike(v)) return false\n  return Object.getPrototypeOf(v) === Object.prototype\n}\n\n/**\n * 位置形态 → 对象形态归一（faijs 特有 dual op 的 D11 反方向）。\n *\n * 触发条件：声明了 slotMap 且对象槽位（第 `shapeArity` 个实参）不是\n * plain object。已是对象形态或实参不足时原样返回（交由 op 自身的断言报错）。\n *\n * @param args - 调用参数数组\n * @param form - slotMap 声明（位置槽→对象键装箱表）\n * @param name - op 名（错误信息用）\n * @returns 归一后的参数数组（前置 Shape 原样 + 末尾一个对象形态参数）\n * @throws E_ARGS_FORM 位置参数个数与声明的槽位不匹配时\n */\nexport function positionalToObject(args: unknown[], form: SlotMap, name: string): unknown[] {\n  const shapeArity = form.shapeArity ?? 0\n  if (args.length <= shapeArity) return args // 无位置形参可装箱 → 原样（op 断言报错）\n  if (isPlainObjectValue(args[shapeArity])) return args // 已是对象形态\n\n  const rest = args.slice(shapeArity)\n  const obj: Record<string, unknown> = {}\n  let i = 0\n  for (const key of form.keys) {\n    if (i >= rest.length) break\n    // §6.2 尾参 options：当前实参是 plain object（候选尾参 options）→ 停止装箱\n    // 交给下方 options 合并，不让任何槽位把它吞进拓扑参数\n    // （`box(20,{centered:true})` / `cylinder(5,40,{centered:true})`）。\n    if (isPlainObjectValue(rest[i])) break\n    if (form.vec3Keys?.includes(key)) {\n      // vec3 槽位：吃掉最多 3 个连续实参（1 个 → 标量，2~3 个 → 数组）。\n      // 若剩余序列最末是 plain object（候选尾参 options），先为它留位，不让\n      // 跨槽 vec3 把 options 吞进拓扑参数（`box(10,20,30,{centered:true})`）。\n      const avail = rest.length - i\n      const reserveOptions = avail > 1 && isPlainObjectValue(rest[rest.length - 1]) ? 1 : 0\n      const take = Math.min(3, avail - reserveOptions)\n      const chunk = rest.slice(i, i + take)\n      obj[key] = take === 1 ? chunk[0] : chunk\n      i += take\n      continue\n    }\n    obj[key] = rest[i]\n    i += 1\n  }\n  // D11 尾参 options 合并（§6.2）：位置槽装箱后，若剩余实参恰好 1 个且为\n  // plain object → 作为 options 并入 args。让 `box(10,20,30,{centered:true})`、\n  // `sphere(5,{at,segments})`、`cylinder(5,40,{centered:true})` 在脚本面可用。\n  if (i < rest.length) {\n    if (rest.length - i === 1 && isPlainObjectValue(rest[i])) {\n      const opts = rest[i] as Record<string, unknown>\n      const dup = Object.keys(opts).filter((k) => form.keys.includes(k) || k in obj)\n      if (dup.length > 0) {\n        throw new Error(\n          `[faijs/args] ${name}: E_ARGS_FORM: option key(s) ${dup.join(', ')} ` +\n          `conflict with positional slot(s) (${form.keys.join(', ')})`\n        )\n      }\n      Object.assign(obj, opts)\n      return [...args.slice(0, shapeArity), obj]\n    }\n    throw new Error(\n      `[faijs/args] ${name}: E_ARGS_FORM: expected ${form.keys.join(', ')} ` +\n        `(${form.keys.length} positional slot(s)); got ${rest.length} value(s): ` +\n        rest.map((a) => (typeof a === 'object' ? '[object]' : String(a))).join(', ')\n    )\n  }\n  return [...args.slice(0, shapeArity), obj]\n}\n"]}

package/dist/api/internal/l3-bridge.d.ts

@@ -0,0 +1,94 @@
+/**
+ * L3 bridge — faijs Shape ⇄ vendored brepjs shape（生成层共用，E5 模板）
+ *
+ * 设计文档：docs/plans/2026-09-02-faijs-api-surface-completion.md §E5
+ *
+ * 桥接事实（2026-09-02 实测）：
+ * - faijs 的 brep slot（`brepOf(shape)` → `slot.solid`）运行时是 occt-wasm 的
+ *   shape 句柄（number，见 `brep/engine/types.ts` 的 `BrepHandle` 注释）；
+ * - vendored brepjs 的 `ShapeHandle.wrapped`（`core/disposal.ts`）运行时也是
+ *   同一 occt-wasm 实例的 shape 句柄 —— D10 单实例（`api/occt-kernel-bridge.ts`）
+ *   保证两者共享同一 wasm，句柄空间一致，**零拷贝互操作**。
+ *
+ * 因此投影一个 brepjs op 只需三件事：
+ *   1. faijs Shape → brepjs 输入：`createBorrowedHandle(brepOf(s))`（借入，不转移所有权）；
+ *   2. 调 vendored 函数（Result 语义由各 op 处理：`ok` 取值 / `err` 抛错）；
+ *   3. brepjs 产物 → faijs Shape：取 `.wrapped`（owned handle）→ `fromHandle()`
+ *      （meshHandle + 身份槽登记，所有权转入 faijs）。
+ *
+ * 依赖约束（同 `brep/handle-bridge.ts`）：只允许 import runtime-state / shape /
+ * handle-bridge / vendored disposal 的类型与借入工具 / vendored occtWasm helpers
+ * 的句柄视图工厂（`handle`/`isOcctWasmHandle`，纯对象工厂无 wasm 依赖）/ `api/`
+ * 层的内核桥读取器（`getBrepjsKernel`），保持 dist/sdk.js 零 heavy 依赖。
+ */
+import type { Shape } from '../../mesh/types.js';
+import type { ShapeHandle } from '../../vendored/brepjs/core/disposal.js';
+/**
+ * Borrow a faijs Shape's OCCT handle as a vendored brepjs shape handle.
+ *
+ * No ownership transfer: the brepjs-side borrow is a no-op-dispose view of the
+ * same occt-wasm shape, valid while the faijs Shape owns it. Pass the result to
+ * vendored functions that take `Shapeable<T>` / `AnyShape`.
+ *
+ * `brepOf` is a numeric arena id at runtime (occt-wasm's own `ShapeHandle` is a
+ * branded number), but the vendored code consumes `KernelShape` as an *object*
+ * (the shapeTypeCache WeakMap key, `isOcctWasmHandle` discriminant, direct
+ * `shape.type` reads in `topologyOps.shapeType`) — a raw number crashes there
+ * ("Invalid value used as weak map key"). The id is therefore wrapped into a
+ * structurally valid `OcctWasmHandle` view: the type is queried from the bound
+ * kernel through the numeric fallback branch of `topologyOps.shapeType`, and
+ * the `handle()` factory keeps `delete` a no-op (non-owning view — the arena
+ * slot and its ownership are untouched).
+ *
+ * @param s - the faijs Shape whose brep slot is borrowed.
+ * @returns a vendored brepjs ShapeHandle view of the same occt shape.
+ * @throws when the Shape has no live BREP slot (mesh-only input on a brep op).
+ */
+export declare function borrowBrepjsShape(s: Shape): ShapeHandle;
+/**
+ * Adopt a vendored brepjs product into a faijs Shape.
+ *
+ * Unwraps the owned occt handle (`.wrapped`) and registers it into faijs'
+ * identity slot via `fromHandle` — ownership transfers to faijs, and the brepjs
+ * wrapper must not dispose it afterwards (projected ops return it directly).
+ *
+ * @param product - a vendored brepjs shape (ShapeHandle / AnyShape family).
+ * @param segments - optional tessellation segments (brepjs 投影侧 `segments?`，
+ *   裁决 1；透传给 `fromHandle` 的三角化，默认 32 → 64 由 handle-bridge 兜底).
+ * @returns the faijs Shape wrapping the same occt solid.
+ */
+export declare function adoptBrepjsProduct(product: unknown, segments?: number): Shape;
+/**
+ * Call a vendored brepjs function with a rebuilt positional argument list.
+ *
+ * Generated wrappers build `__args` positionally (borrowing geometry inputs,
+ * passing value params through); a plain `fn(...args: unknown[])` spread fails
+ * TS2556 against brepjs' fixed-arity signatures, so the call goes through this
+ * rest-typed bridge that preserves the function's own `ReturnType` (so a
+ * `Result` return keeps `.ok`/`.value` for the generated unwrap code).
+ *
+ * @param fn   the vendored brepjs function.
+ * @param args the rebuilt positional argument list (borrowed handles + value params).
+ * @returns whatever the vendored function returns (typed via ReturnType).
+ */
+export declare function callBrepjs<F extends (...a: never[]) => unknown>(fn: F, args: unknown[]): ReturnType<F>;
+/**
+ * Adopt a vendored handle as a faijs Shape (compatOp step 5's only adoption
+ * entry point).
+ *
+ * ① pure data (no `.wrapped`) → pass through unchanged (query/data functions);
+ * ② sub-shape kinds (face/edge/wire/vertex/shell) → throw E_SUBSHAPE_BOUNDARY
+ *    (v1 boundary rejection, R4; the brand is a compile-time phantom type —
+ *    shapeTypes.ts:93-95 — so the runtime kind is read from the occt-wasm
+ *    handle's own `type` field, same as the kernel getShapeType helpers.ts:77-79);
+ * ③ entities (solid/compound) → unregisterFromCleanup (★ R1: drop the
+ *    finalizer, otherwise disposal.ts:117-124 disposes the slot faijs has
+ *    already adopted when the wrapping object gets GC'd) → adoptBrepjsProduct.
+ *
+ * @param product - the vendored result (handle or plain data record).
+ * @param opName - the op name (error messages).
+ * @param segments - optional tessellation segments (compat `segments?`).
+ * @returns the adopted faijs Shape, or the plain data untouched.
+ */
+export declare function adoptEntity(product: unknown, opName: string, segments?: number): unknown;
+//# sourceMappingURL=l3-bridge.d.ts.map

package/dist/api/internal/l3-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"l3-bridge.d.ts","sourceRoot":"","sources":["../../../src/api/internal/l3-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAM7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAA;AAKzE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,GAAG,WAAW,CAYvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,CAa7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,KAAK,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAEtG;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAkBxF"}

package/dist/api/internal/l3-bridge.js

@@ -0,0 +1,143 @@
+/**
+ * L3 bridge — faijs Shape ⇄ vendored brepjs shape（生成层共用，E5 模板）
+ *
+ * 设计文档：docs/plans/2026-09-02-faijs-api-surface-completion.md §E5
+ *
+ * 桥接事实（2026-09-02 实测）：
+ * - faijs 的 brep slot（`brepOf(shape)` → `slot.solid`）运行时是 occt-wasm 的
+ *   shape 句柄（number，见 `brep/engine/types.ts` 的 `BrepHandle` 注释）；
+ * - vendored brepjs 的 `ShapeHandle.wrapped`（`core/disposal.ts`）运行时也是
+ *   同一 occt-wasm 实例的 shape 句柄 —— D10 单实例（`api/occt-kernel-bridge.ts`）
+ *   保证两者共享同一 wasm，句柄空间一致，**零拷贝互操作**。
+ *
+ * 因此投影一个 brepjs op 只需三件事：
+ *   1. faijs Shape → brepjs 输入：`createBorrowedHandle(brepOf(s))`（借入，不转移所有权）；
+ *   2. 调 vendored 函数（Result 语义由各 op 处理：`ok` 取值 / `err` 抛错）；
+ *   3. brepjs 产物 → faijs Shape：取 `.wrapped`（owned handle）→ `fromHandle()`
+ *      （meshHandle + 身份槽登记，所有权转入 faijs）。
+ *
+ * 依赖约束（同 `brep/handle-bridge.ts`）：只允许 import runtime-state / shape /
+ * handle-bridge / vendored disposal 的类型与借入工具 / vendored occtWasm helpers
+ * 的句柄视图工厂（`handle`/`isOcctWasmHandle`，纯对象工厂无 wasm 依赖）/ `api/`
+ * 层的内核桥读取器（`getBrepjsKernel`），保持 dist/sdk.js 零 heavy 依赖。
+ */
+import { brepOf } from '../../shape.js';
+import { fromHandle } from '../../brep/handle-bridge.js';
+import { createBorrowedHandle } from '../../vendored/brepjs/core/disposal.js';
+import { unregisterFromCleanup } from '../../vendored/brepjs/core/disposal.js';
+import { handle as occtWasmHandleView, isOcctWasmHandle } from '../../vendored/brepjs/kernel/occtWasm/helpers.js';
+import { getBrepjsKernel } from '../occt-kernel-bridge.js';
+import { OpError } from './result-unwrap.js';
+/**
+ * Borrow a faijs Shape's OCCT handle as a vendored brepjs shape handle.
+ *
+ * No ownership transfer: the brepjs-side borrow is a no-op-dispose view of the
+ * same occt-wasm shape, valid while the faijs Shape owns it. Pass the result to
+ * vendored functions that take `Shapeable<T>` / `AnyShape`.
+ *
+ * `brepOf` is a numeric arena id at runtime (occt-wasm's own `ShapeHandle` is a
+ * branded number), but the vendored code consumes `KernelShape` as an *object*
+ * (the shapeTypeCache WeakMap key, `isOcctWasmHandle` discriminant, direct
+ * `shape.type` reads in `topologyOps.shapeType`) — a raw number crashes there
+ * ("Invalid value used as weak map key"). The id is therefore wrapped into a
+ * structurally valid `OcctWasmHandle` view: the type is queried from the bound
+ * kernel through the numeric fallback branch of `topologyOps.shapeType`, and
+ * the `handle()` factory keeps `delete` a no-op (non-owning view — the arena
+ * slot and its ownership are untouched).
+ *
+ * @param s - the faijs Shape whose brep slot is borrowed.
+ * @returns a vendored brepjs ShapeHandle view of the same occt shape.
+ * @throws when the Shape has no live BREP slot (mesh-only input on a brep op).
+ */
+export function borrowBrepjsShape(s) {
+    const solid = brepOf(s);
+    if (solid === undefined) {
+        throw new Error('[faijs/l3-bridge] E_BREP_ONLY_INPUT: operation requires a BREP-backed shape ' +
+            '(mesh-only input cannot run on the brep path)');
+    }
+    const kernelShape = isOcctWasmHandle(solid)
+        ? solid
+        : occtWasmHandleView(getBrepjsKernel().shapeType(solid), solid);
+    return createBorrowedHandle(kernelShape);
+}
+/**
+ * Adopt a vendored brepjs product into a faijs Shape.
+ *
+ * Unwraps the owned occt handle (`.wrapped`) and registers it into faijs'
+ * identity slot via `fromHandle` — ownership transfers to faijs, and the brepjs
+ * wrapper must not dispose it afterwards (projected ops return it directly).
+ *
+ * @param product - a vendored brepjs shape (ShapeHandle / AnyShape family).
+ * @param segments - optional tessellation segments (brepjs 投影侧 `segments?`，
+ *   裁决 1；透传给 `fromHandle` 的三角化，默认 32 → 64 由 handle-bridge 兜底).
+ * @returns the faijs Shape wrapping the same occt solid.
+ */
+export function adoptBrepjsProduct(product, segments) {
+    if (product === null || typeof product !== 'object' || !('wrapped' in product)) {
+        throw new Error('[faijs/l3-bridge] E_BAD_PRODUCT: expected a shape handle from the vendored engine');
+    }
+    // vendored `wrapped` may be an OcctHandle (`{id}`) or a raw numeric id;
+    // faijs' kernel meshShape expects the numeric shape id (fromHandle).
+    const wrappedAny = product.wrapped;
+    const rawId = typeof wrappedAny === 'object' && wrappedAny !== null && 'id' in wrappedAny
+        ? wrappedAny.id
+        : wrappedAny;
+    const wrapped = rawId;
+    return fromHandle(wrapped, segments === undefined ? undefined : { segments });
+}
+/**
+ * Call a vendored brepjs function with a rebuilt positional argument list.
+ *
+ * Generated wrappers build `__args` positionally (borrowing geometry inputs,
+ * passing value params through); a plain `fn(...args: unknown[])` spread fails
+ * TS2556 against brepjs' fixed-arity signatures, so the call goes through this
+ * rest-typed bridge that preserves the function's own `ReturnType` (so a
+ * `Result` return keeps `.ok`/`.value` for the generated unwrap code).
+ *
+ * @param fn   the vendored brepjs function.
+ * @param args the rebuilt positional argument list (borrowed handles + value params).
+ * @returns whatever the vendored function returns (typed via ReturnType).
+ */
+export function callBrepjs(fn, args) {
+    return fn(...args);
+}
+// ─── adoption (compatOp step 5; R1 fix) ──────────────────────────────────────
+/** Already-adopted handle dedup table: the same vendored handle adopted twice →
+ *  the same faijs Shape (prevents double ownership / double dispose, R6). */
+const adoptedMap = new WeakMap();
+/**
+ * Adopt a vendored handle as a faijs Shape (compatOp step 5's only adoption
+ * entry point).
+ *
+ * ① pure data (no `.wrapped`) → pass through unchanged (query/data functions);
+ * ② sub-shape kinds (face/edge/wire/vertex/shell) → throw E_SUBSHAPE_BOUNDARY
+ *    (v1 boundary rejection, R4; the brand is a compile-time phantom type —
+ *    shapeTypes.ts:93-95 — so the runtime kind is read from the occt-wasm
+ *    handle's own `type` field, same as the kernel getShapeType helpers.ts:77-79);
+ * ③ entities (solid/compound) → unregisterFromCleanup (★ R1: drop the
+ *    finalizer, otherwise disposal.ts:117-124 disposes the slot faijs has
+ *    already adopted when the wrapping object gets GC'd) → adoptBrepjsProduct.
+ *
+ * @param product - the vendored result (handle or plain data record).
+ * @param opName - the op name (error messages).
+ * @param segments - optional tessellation segments (compat `segments?`).
+ * @returns the adopted faijs Shape, or the plain data untouched.
+ */
+export function adoptEntity(product, opName, segments) {
+    if (product === null || typeof product !== 'object' || !('wrapped' in product))
+        return product;
+    const h = product;
+    const prev = adoptedMap.get(h);
+    if (prev)
+        return prev;
+    const type = h.wrapped.type;
+    if (type !== undefined && type !== 'solid' && type !== 'compound') {
+        throw new OpError(opName, 'E_SUBSHAPE_BOUNDARY', `[faijs/brepjs-compat] ${opName}: E_SUBSHAPE_BOUNDARY: sub-shape handle ('${type}') ` +
+            'must not cross the library boundary; return entity solids or plain data');
+    }
+    unregisterFromCleanup(h); // ★ R1: one-line fix replacing gear-lib-demo's pinned array
+    const s = adoptBrepjsProduct(h, segments); // fromHandle: tessellation + identity + BREP slots
+    adoptedMap.set(h, s);
+    return s;
+}
+//# sourceMappingURL=l3-bridge.js.map

package/dist/api/internal/l3-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"l3-bridge.js","sourceRoot":"","sources":["../../../src/api/internal/l3-bridge.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * L3 bridge — faijs Shape ⇄ vendored brepjs shape（生成层共用，E5 模板）\n *\n * 设计文档：docs/plans/2026-09-02-faijs-api-surface-completion.md §E5\n *\n * 桥接事实（2026-09-02 实测）：\n * - faijs 的 brep slot（`brepOf(shape)` → `slot.solid`）运行时是 occt-wasm 的\n *   shape 句柄（number，见 `brep/engine/types.ts` 的 `BrepHandle` 注释）；\n * - vendored brepjs 的 `ShapeHandle.wrapped`（`core/disposal.ts`）运行时也是\n *   同一 occt-wasm 实例的 shape 句柄 —— D10 单实例（`api/occt-kernel-bridge.ts`）\n *   保证两者共享同一 wasm，句柄空间一致，**零拷贝互操作**。\n *\n * 因此投影一个 brepjs op 只需三件事：\n *   1. faijs Shape → brepjs 输入：`createBorrowedHandle(brepOf(s))`（借入，不转移所有权）；\n *   2. 调 vendored 函数（Result 语义由各 op 处理：`ok` 取值 / `err` 抛错）；\n *   3. brepjs 产物 → faijs Shape：取 `.wrapped`（owned handle）→ `fromHandle()`\n *      （meshHandle + 身份槽登记，所有权转入 faijs）。\n *\n * 依赖约束（同 `brep/handle-bridge.ts`）：只允许 import runtime-state / shape /\n * handle-bridge / vendored disposal 的类型与借入工具 / vendored occtWasm helpers\n * 的句柄视图工厂（`handle`/`isOcctWasmHandle`，纯对象工厂无 wasm 依赖）/ `api/`\n * 层的内核桥读取器（`getBrepjsKernel`），保持 dist/sdk.js 零 heavy 依赖。\n */\n\nimport type { Shape } from '../../mesh/types'\nimport { brepOf } from '../../shape'\nimport { fromHandle } from '../../brep/handle-bridge'\nimport type { BrepHandle } from '../../brep/engine/types'\nimport { createBorrowedHandle } from '../../vendored/brepjs/core/disposal.js'\nimport { unregisterFromCleanup } from '../../vendored/brepjs/core/disposal.js'\nimport type { ShapeHandle } from '../../vendored/brepjs/core/disposal.js'\nimport { handle as occtWasmHandleView, isOcctWasmHandle } from '../../vendored/brepjs/kernel/occtWasm/helpers.js'\nimport { getBrepjsKernel } from '../occt-kernel-bridge'\nimport { OpError } from './result-unwrap'\n\n/**\n * Borrow a faijs Shape's OCCT handle as a vendored brepjs shape handle.\n *\n * No ownership transfer: the brepjs-side borrow is a no-op-dispose view of the\n * same occt-wasm shape, valid while the faijs Shape owns it. Pass the result to\n * vendored functions that take `Shapeable<T>` / `AnyShape`.\n *\n * `brepOf` is a numeric arena id at runtime (occt-wasm's own `ShapeHandle` is a\n * branded number), but the vendored code consumes `KernelShape` as an *object*\n * (the shapeTypeCache WeakMap key, `isOcctWasmHandle` discriminant, direct\n * `shape.type` reads in `topologyOps.shapeType`) — a raw number crashes there\n * (\"Invalid value used as weak map key\"). The id is therefore wrapped into a\n * structurally valid `OcctWasmHandle` view: the type is queried from the bound\n * kernel through the numeric fallback branch of `topologyOps.shapeType`, and\n * the `handle()` factory keeps `delete` a no-op (non-owning view — the arena\n * slot and its ownership are untouched).\n *\n * @param s - the faijs Shape whose brep slot is borrowed.\n * @returns a vendored brepjs ShapeHandle view of the same occt shape.\n * @throws when the Shape has no live BREP slot (mesh-only input on a brep op).\n */\nexport function borrowBrepjsShape(s: Shape): ShapeHandle {\n  const solid = brepOf(s) as BrepHandle | undefined\n  if (solid === undefined) {\n    throw new Error(\n      '[faijs/l3-bridge] E_BREP_ONLY_INPUT: operation requires a BREP-backed shape ' +\n        '(mesh-only input cannot run on the brep path)',\n    )\n  }\n  const kernelShape = isOcctWasmHandle(solid)\n    ? solid\n    : occtWasmHandleView(getBrepjsKernel().shapeType(solid as never), solid as never)\n  return createBorrowedHandle(kernelShape as never)\n}\n\n/**\n * Adopt a vendored brepjs product into a faijs Shape.\n *\n * Unwraps the owned occt handle (`.wrapped`) and registers it into faijs'\n * identity slot via `fromHandle` — ownership transfers to faijs, and the brepjs\n * wrapper must not dispose it afterwards (projected ops return it directly).\n *\n * @param product - a vendored brepjs shape (ShapeHandle / AnyShape family).\n * @param segments - optional tessellation segments (brepjs 投影侧 `segments?`，\n *   裁决 1；透传给 `fromHandle` 的三角化，默认 32 → 64 由 handle-bridge 兜底).\n * @returns the faijs Shape wrapping the same occt solid.\n */\nexport function adoptBrepjsProduct(product: unknown, segments?: number): Shape {\n  if (product === null || typeof product !== 'object' || !('wrapped' in product)) {\n    throw new Error('[faijs/l3-bridge] E_BAD_PRODUCT: expected a shape handle from the vendored engine')\n  }\n  // vendored `wrapped` may be an OcctHandle (`{id}`) or a raw numeric id;\n  // faijs' kernel meshShape expects the numeric shape id (fromHandle).\n  const wrappedAny = (product as { wrapped: unknown }).wrapped\n  const rawId =\n    typeof wrappedAny === 'object' && wrappedAny !== null && 'id' in wrappedAny\n      ? (wrappedAny as { id: number }).id\n      : (wrappedAny as number)\n  const wrapped = rawId as BrepHandle\n  return fromHandle(wrapped, segments === undefined ? undefined : { segments })\n}\n\n/**\n * Call a vendored brepjs function with a rebuilt positional argument list.\n *\n * Generated wrappers build `__args` positionally (borrowing geometry inputs,\n * passing value params through); a plain `fn(...args: unknown[])` spread fails\n * TS2556 against brepjs' fixed-arity signatures, so the call goes through this\n * rest-typed bridge that preserves the function's own `ReturnType` (so a\n * `Result` return keeps `.ok`/`.value` for the generated unwrap code).\n *\n * @param fn   the vendored brepjs function.\n * @param args the rebuilt positional argument list (borrowed handles + value params).\n * @returns whatever the vendored function returns (typed via ReturnType).\n */\nexport function callBrepjs<F extends (...a: never[]) => unknown>(fn: F, args: unknown[]): ReturnType<F> {\n  return fn(...(args as never[])) as ReturnType<F>\n}\n\n// ─── adoption (compatOp step 5; R1 fix) ──────────────────────────────────────\n\n/** Already-adopted handle dedup table: the same vendored handle adopted twice →\n *  the same faijs Shape (prevents double ownership / double dispose, R6). */\nconst adoptedMap = new WeakMap<object, Shape>()\n\n/**\n * Adopt a vendored handle as a faijs Shape (compatOp step 5's only adoption\n * entry point).\n *\n * ① pure data (no `.wrapped`) → pass through unchanged (query/data functions);\n * ② sub-shape kinds (face/edge/wire/vertex/shell) → throw E_SUBSHAPE_BOUNDARY\n *    (v1 boundary rejection, R4; the brand is a compile-time phantom type —\n *    shapeTypes.ts:93-95 — so the runtime kind is read from the occt-wasm\n *    handle's own `type` field, same as the kernel getShapeType helpers.ts:77-79);\n * ③ entities (solid/compound) → unregisterFromCleanup (★ R1: drop the\n *    finalizer, otherwise disposal.ts:117-124 disposes the slot faijs has\n *    already adopted when the wrapping object gets GC'd) → adoptBrepjsProduct.\n *\n * @param product - the vendored result (handle or plain data record).\n * @param opName - the op name (error messages).\n * @param segments - optional tessellation segments (compat `segments?`).\n * @returns the adopted faijs Shape, or the plain data untouched.\n */\nexport function adoptEntity(product: unknown, opName: string, segments?: number): unknown {\n  if (product === null || typeof product !== 'object' || !('wrapped' in product)) return product\n  const h = product as ShapeHandle\n  const prev = adoptedMap.get(h)\n  if (prev) return prev\n  const type = (h.wrapped as { type?: string }).type\n  if (type !== undefined && type !== 'solid' && type !== 'compound') {\n    throw new OpError(\n      opName,\n      'E_SUBSHAPE_BOUNDARY',\n      `[faijs/brepjs-compat] ${opName}: E_SUBSHAPE_BOUNDARY: sub-shape handle ('${type}') ` +\n        'must not cross the library boundary; return entity solids or plain data',\n    )\n  }\n  unregisterFromCleanup(h) // ★ R1: one-line fix replacing gear-lib-demo's pinned array\n  const s = adoptBrepjsProduct(h, segments) // fromHandle: tessellation + identity + BREP slots\n  adoptedMap.set(h, s)\n  return s\n}\n"]}

package/dist/api/internal/result-unwrap.d.ts

@@ -0,0 +1,101 @@
+/**
+ * result-unwrap — the single Result→throw bridge shared by every faijs
+ * statement boundary (D1).
+ *
+ * Design: docs/plans/2026-09-03-faijs-brepjs-compat-api.md §5.1 / §5.2
+ *
+ * Three-layer error semantics (§5.1):
+ *   library internals / TS compat face → `Result<T>` native (BrepError)
+ *   statement boundary                 → `err` unwrapped into a throw
+ *   faijs-specific op impls            → may return `Result`; same unwrap
+ *
+ * This module is a **leaf**: it imports nothing, so both the SDK layer
+ * (`src/define-op.ts`, whose `dist/sdk.js` must stay free of heavy static
+ * imports) and the compat bridge (`api/internal/compat-op.ts`) can share one
+ * implementation. Having two copies would let the two boundaries drift.
+ *
+ * @module
+ */
+/** Structural shape of the vendored `Ok`/`Err` records (`vendored/brepjs/core/result.ts:12-21`). */
+export type ResultLike = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: {
+        code?: string;
+        message?: string;
+    };
+};
+/**
+ * Statement-boundary op failure (D1 unwrap / compat adoption).
+ *
+ * An `err` Result unwrapped at the statement boundary used to be thrown as a
+ * plain `Error`, which `CadRuntime.runWithFailureHandling` (recognizing only
+ * `BrepUnsupportedError`/`MeshUnsupportedError` by `instanceof`) re-threw out
+ * of `execute()` instead of converting it into `ExecutionResult.failedAt`.
+ * This class is the engine-recognizable carrier: defined in this leaf module
+ * (zero imports) so both `define-op` and the compat bridge can throw it while
+ * CadRuntime can catch it without importing anything heavier.
+ *
+ * A thrown `Error` that is *not* an `OpError` keeps its old meaning: an
+ * unexpected implementation bug that must propagate (Result 体系 — expected
+ * failures are `err` values, exceptions are bugs).
+ */
+export declare class OpError extends Error {
+    /** The op name that produced the failure. */
+    readonly op: string;
+    /** The `BrepError.code`, or `'E_OP_FAILED'` when the library sent none. */
+    readonly code: string;
+    constructor(op: string, code: string, message: string);
+}
+/**
+ * Structural test for a Result value.
+ *
+ * Only the `ok: boolean` discriminant is checked — the vendored `Result` is a
+ * plain record, so no `instanceof` and no import is needed (which is what keeps
+ * this module a leaf).
+ *
+ * @param v - the candidate value.
+ * @returns true when `v` looks like an Ok/Err record.
+ */
+export declare function isResultLike(v: unknown): v is ResultLike;
+/**
+ * Render an error thrown by (or returned from) an implementation as a
+ * statement-level failure.
+ *
+ * The op name and the `BrepError.code` (when present) are always kept so the
+ * engine's statement-level catch reports the same shape the plan's trace A/B
+ * describe (`[faijs/brepjs-compat] <op>: <CODE>: <message>`).
+ *
+ * @param name - the op name.
+ * @param err  - the thrown value (Error or anything else).
+ * @returns an Error carrying the op context.
+ */
+export declare function toOpError(name: string, err: unknown): Error;
+/**
+ * Wrap an implementation-thrown exception as an {@link OpError} (statement-
+ * level failure carrier). Used by `define-op.ts` `runImpl` so that
+ * `CadRuntime.directFailedAtOrThrow` recognizes the error as an op failure
+ * (not a bug to re-throw).
+ *
+ * @param name - the op name.
+ * @param err  - the thrown value.
+ * @returns an OpError carrying the op context and code.
+ */
+export declare function toOpFailure(name: string, err: unknown): OpError;
+/**
+ * Statement-boundary unwrap (D1).
+ *
+ * - a non-Result product → returned untouched (plain-data ops, mesh products);
+ * - `ok`  → `.value`;
+ * - `err` → throws an {@link OpError} carrying the op name and BrepError code
+ *   (the engine converts `OpError` into `ExecutionResult.failedAt`).
+ *
+ * @param r    - the implementation product.
+ * @param name - the op name (error messages).
+ * @returns the unwrapped value, or the input when it was not a Result.
+ * @throws an {@link OpError} when `r` is an `Err`.
+ */
+export declare function unwrapResult(r: unknown, name: string): unknown;
+//# sourceMappingURL=result-unwrap.d.ts.map

package/dist/api/internal/result-unwrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-unwrap.d.ts","sourceRoot":"","sources":["../../../src/api/internal/result-unwrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,oGAAoG;AACpG,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC5B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAA;AAE7D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,OAAQ,SAAQ,KAAK;IAChC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBACT,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAMtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,UAAU,CAExD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,KAAK,CAO3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAO/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAU9D"}