@faicad/faijs 0.13.0

package/dist/api/internal/compat-op.js

@@ -0,0 +1,176 @@
+/**
+ * compat-op — lift an arbitrary brepjs-shaped function into a faijs statement
+ * op, built **on top of** defineOp (single implementation entry, v1).
+ *
+ * Design: docs/plans/2026-09-06-compatop-on-defineop.md §3
+ *
+ * compatOp is NOT a second implementation path parallel to defineOp: every
+ * shared mechanism is owned by defineOp — dispatch (dispatchPath + capability
+ * routing), the Result boundary (runImpl + unwrapResult), product wrapping
+ * (wrapBrepOne / wrapByKeys), `DUAL_OP_META` mounting and
+ * `assertLibConforms` validation. compatOp only does two things:
+ *   - spec pass-through: `CompatSpec` is a combinatorial inheritance of
+ *     `DualOpOptions` (single source of truth, fields auto-sync — §3.1);
+ *   - adapter construction: a brepjs-shaped bridge feeding the brep impl — the
+ *     three bridging steps that cannot be shared (all reuse shared
+ *     infrastructure, §3.2):
+ *       1. borrowDeep — inward borrow: deep walk, any faijs Shape →
+ *          borrowBrepjsShape view (zero-copy; library-private handles pass
+ *          through untouched);
+ *       2. call + unwrap — callBrepjs through the shared unwrapResult
+ *          (`err` throws an OpError carrying the op name + BrepError code);
+ *       3. adoptOut — outward adoption: top-level handle / `outputs`-declared
+ *          fields (single handle or handle array) → adoptEntity
+ *          (unregister finalizer + fromHandle).
+ *
+ * The keep / keepHidden contract is untouched: compatOp neither blocks nor
+ * rewrites it — any function running inside a DirectExecutor context can use
+ * function-body declarations (C1), and call-site declarations override them
+ * (`lang/keep.ts` resolveKeep). The decorated product therefore behaves like
+ * any defineOp product: `keep`-safe, capability-aware, multi-output
+ * (`DUAL_OP_META.outputs` visible).
+ *
+ * No self-invented fields: `CompatSpec` extends `Omit<DualOpOptions, 'mesh' |
+ * 'brep'>` and declares nothing else; the only tweak is `name` tightened
+ * (inherited field, not a new one).
+ *
+ * @module
+ */
+import { defineOp, DUAL_OP_META, } from '../../define-op.js';
+import { isShape } from '../../shape.js';
+import { borrowBrepjsShape, adoptEntity, callBrepjs } from './l3-bridge.js';
+import { unwrapResult } from './result-unwrap.js';
+const MAX_WALK_DEPTH = 4;
+/**
+ * Inward bridging step: deep walk with faijs Shapes replaced by borrowed
+ * brepjs views (zero-copy); everything else passes through.
+ * Class instances are not traversed (defensive); library-private handles
+ * pass through (§4.3.4 of the design).
+ *
+ * @param v - the value to borrow from (plain object, array, or primitive).
+ * @param depth - current traversal depth (guard against deep recursion).
+ * @returns the value with faijs Shapes replaced by borrowed views.
+ */
+export function borrowDeep(v, depth) {
+    if (depth > MAX_WALK_DEPTH || v === null || typeof v !== 'object')
+        return v;
+    if (isShape(v))
+        return borrowBrepjsShape(v);
+    if (Array.isArray(v))
+        return v.map((x) => borrowDeep(x, depth + 1));
+    if (Object.getPrototypeOf(v) !== Object.prototype)
+        return v;
+    const out = {};
+    for (const [k, x] of Object.entries(v))
+        out[k] = borrowDeep(x, depth + 1);
+    return out;
+}
+/**
+ * Statement-boundary unwrap — `err` becomes an execution error carrying the op
+ * name and the `BrepError` code. Delegates to the shared
+ * {@link unwrapResult} so the compat boundary and defineOp's Result boundary
+ * share one leaf implementation (no drift).
+ *
+ * @param r - the Result-like value to unwrap.
+ * @param name - the op name used in error messages.
+ * @returns the unwrapped ok value.
+ */
+export function unwrapOrThrow(r, name) {
+    return unwrapResult(r, name);
+}
+/**
+ * Bridging step: outward adoption — top-level handle or `outputs`-declared
+ * fields → adoptEntity (unregister finalizer + fromHandle). `outputs` may also
+ * name an array field of handles; every element is adopted individually.
+ * Deduplication of already-adopted handles lives inside adoptEntity. A field
+ * already being a faijs Shape passes through untouched (no double adoption).
+ *
+ * @param v - the library product.
+ * @param spec - the compat spec (name + optional `outputs`).
+ * @param segments - caller-provided `segments` (裁决 1,§5.2), forwarded so the
+ *  adopted handles' tessellation honors it.
+ * @returns the adopted record / Shape, or the plain data untouched.
+ */
+function adoptOut(v, spec, segments) {
+    if (isShape(v))
+        return v;
+    if (spec.outputs && typeof v === 'object' && v !== null && !Array.isArray(v)) {
+        const rec = v;
+        for (const f of spec.outputs) {
+            const field = rec[f];
+            rec[f] = Array.isArray(field)
+                ? field.map((x) => adoptEntity(x, spec.name, segments))
+                : adoptEntity(field, spec.name, segments);
+        }
+        return v;
+    }
+    return adoptEntity(v, spec.name, segments);
+}
+/**
+ * Read the caller-supplied tessellation density from a compat op's args.
+ *
+ * 裁决 1：faijs 的 `segments` 显式超集在 brepjs 投影侧也必须可选；这里从调用点
+ * 的尾参 options（或任一 plain-object 实参）抓取 `segments`，在产出句柄被收编为
+ * faijs Shape 时透传给 `fromHandle` 的三角化（§5.2 机制）。默认不传 = 由
+ * handle-bridge 的 64 兜底。
+ */
+function readSegmentsFromArgs(args) {
+    for (let i = args.length - 1; i >= 0; i--) {
+        const a = args[i];
+        if (a !== null &&
+            typeof a === 'object' &&
+            !Array.isArray(a) &&
+            Object.getPrototypeOf(a) === Object.prototype) {
+            const seg = a.segments;
+            if (typeof seg === 'number' && Number.isFinite(seg))
+                return seg;
+        }
+    }
+    return undefined;
+}
+/**
+ * Build the brep-only adapter: borrow inputs → call the vendor function through
+ * the shared unwrap → adopt the product (with the caller's `segments`,
+ * 裁决 1/§5.2). The adapter never dispatches and never mounts metadata —
+ * those are defineOp's.
+ *
+ * @param fn   the brepjs-shaped function (dual-form normalization inside, D11).
+ * @param spec the static op spec (name + options pass-through).
+ * @returns a `BrepImpl` compatible with defineOp's brep-only decl.
+ */
+function buildAdapter(fn, spec) {
+    return async (...args) => {
+        const borrowed = args.map((a) => borrowDeep(a, 0));
+        const value = unwrapOrThrow(callBrepjs(fn, borrowed), spec.name);
+        return adoptOut(value, spec, readSegmentsFromArgs(args));
+    };
+}
+/**
+ * Lift a brepjs-shaped function into a defineOp-decorated op facade (brep-only).
+ *
+ * The decorated product is identical to a defineOp product: same `DUAL_OP_META`
+ * field set (kind 'dual-op', brep impl, name, capabilities, outputs, schema,
+ * slotMap), same dispatch semantics, same Result boundary. The adapter carries
+ * only the brepjs bridging (borrow / call / adopt); every other mechanism
+ * belongs to defineOp.
+ *
+ * @param fn   the brepjs-shaped function.
+ * @param spec the static spec (name required; capabilities/outputs/slotMap/
+ *  schema pass through and take effect).
+ * @returns the compat op facade, carrying dual-op metadata.
+ */
+export function compatOp(fn, spec) {
+    const { outputs, capabilities, schema, slotMap } = spec;
+    // `outputs` flows through defineOp's own wrapping path: the adapter adopts
+    // per declared field, then defineOp wraps — isShape passthrough, so no
+    // double wrapping (§3.2).
+    return defineOp({
+        brep: buildAdapter(fn, spec),
+        name: spec.name,
+        capabilities,
+        outputs,
+        schema,
+        slotMap,
+    });
+}
+//# sourceMappingURL=compat-op.js.map

package/dist/api/internal/compat-op.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compat-op.js","sourceRoot":"","sources":["../../../src/api/internal/compat-op.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * compat-op — lift an arbitrary brepjs-shaped function into a faijs statement\n * op, built **on top of** defineOp (single implementation entry, v1).\n *\n * Design: docs/plans/2026-09-06-compatop-on-defineop.md §3\n *\n * compatOp is NOT a second implementation path parallel to defineOp: every\n * shared mechanism is owned by defineOp — dispatch (dispatchPath + capability\n * routing), the Result boundary (runImpl + unwrapResult), product wrapping\n * (wrapBrepOne / wrapByKeys), `DUAL_OP_META` mounting and\n * `assertLibConforms` validation. compatOp only does two things:\n *   - spec pass-through: `CompatSpec` is a combinatorial inheritance of\n *     `DualOpOptions` (single source of truth, fields auto-sync — §3.1);\n *   - adapter construction: a brepjs-shaped bridge feeding the brep impl — the\n *     three bridging steps that cannot be shared (all reuse shared\n *     infrastructure, §3.2):\n *       1. borrowDeep — inward borrow: deep walk, any faijs Shape →\n *          borrowBrepjsShape view (zero-copy; library-private handles pass\n *          through untouched);\n *       2. call + unwrap — callBrepjs through the shared unwrapResult\n *          (`err` throws an OpError carrying the op name + BrepError code);\n *       3. adoptOut — outward adoption: top-level handle / `outputs`-declared\n *          fields (single handle or handle array) → adoptEntity\n *          (unregister finalizer + fromHandle).\n *\n * The keep / keepHidden contract is untouched: compatOp neither blocks nor\n * rewrites it — any function running inside a DirectExecutor context can use\n * function-body declarations (C1), and call-site declarations override them\n * (`lang/keep.ts` resolveKeep). The decorated product therefore behaves like\n * any defineOp product: `keep`-safe, capability-aware, multi-output\n * (`DUAL_OP_META.outputs` visible).\n *\n * No self-invented fields: `CompatSpec` extends `Omit<DualOpOptions, 'mesh' |\n * 'brep'>` and declares nothing else; the only tweak is `name` tightened\n * (inherited field, not a new one).\n *\n * @module\n */\n\nimport {\n  defineOp,\n  DUAL_OP_META,\n  type DualOpMeta,\n  type DualOpOptions,\n  type BrepImpl,\n  type BrepProduct,\n} from '../../define-op'\nimport { isShape } from '../../shape'\nimport { borrowBrepjsShape, adoptEntity, callBrepjs } from './l3-bridge'\nimport { unwrapResult } from './result-unwrap'\nimport type { Shape } from '../../mesh/types'\n\n/** compatOp's static spec: combinatorial inheritance (single source of truth). */\nexport interface CompatSpec extends Omit<DualOpOptions, 'mesh' | 'brep'> {\n  /** Op name (error messages + metadata; required, unlike defineOp's optional name). */\n  name: string\n}\n\nconst MAX_WALK_DEPTH = 4\n\n/**\n * Inward bridging step: deep walk with faijs Shapes replaced by borrowed\n * brepjs views (zero-copy); everything else passes through.\n * Class instances are not traversed (defensive); library-private handles\n * pass through (§4.3.4 of the design).\n *\n * @param v - the value to borrow from (plain object, array, or primitive).\n * @param depth - current traversal depth (guard against deep recursion).\n * @returns the value with faijs Shapes replaced by borrowed views.\n */\nexport function borrowDeep(v: unknown, depth: number): unknown {\n  if (depth > MAX_WALK_DEPTH || v === null || typeof v !== 'object') return v\n  if (isShape(v)) return borrowBrepjsShape(v)\n  if (Array.isArray(v)) return v.map((x) => borrowDeep(x, depth + 1))\n  if (Object.getPrototypeOf(v) !== Object.prototype) return v\n  const out: Record<string, unknown> = {}\n  for (const [k, x] of Object.entries(v)) out[k] = borrowDeep(x, depth + 1)\n  return out\n}\n\n/**\n * Statement-boundary unwrap — `err` becomes an execution error carrying the op\n * name and the `BrepError` code. Delegates to the shared\n * {@link unwrapResult} so the compat boundary and defineOp's Result boundary\n * share one leaf implementation (no drift).\n *\n * @param r - the Result-like value to unwrap.\n * @param name - the op name used in error messages.\n * @returns the unwrapped ok value.\n */\nexport function unwrapOrThrow(r: unknown, name: string): unknown {\n  return unwrapResult(r, name)\n}\n\n/**\n * Bridging step: outward adoption — top-level handle or `outputs`-declared\n * fields → adoptEntity (unregister finalizer + fromHandle). `outputs` may also\n * name an array field of handles; every element is adopted individually.\n * Deduplication of already-adopted handles lives inside adoptEntity. A field\n * already being a faijs Shape passes through untouched (no double adoption).\n *\n * @param v - the library product.\n * @param spec - the compat spec (name + optional `outputs`).\n * @param segments - caller-provided `segments` (裁决 1,§5.2), forwarded so the\n *  adopted handles' tessellation honors it.\n * @returns the adopted record / Shape, or the plain data untouched.\n */\nfunction adoptOut(v: unknown, spec: CompatSpec, segments?: number): unknown {\n  if (isShape(v)) return v\n  if (spec.outputs && typeof v === 'object' && v !== null && !Array.isArray(v)) {\n    const rec = v as Record<string, unknown>\n    for (const f of spec.outputs) {\n      const field = rec[f]\n      rec[f] = Array.isArray(field)\n        ? field.map((x) => adoptEntity(x, spec.name, segments))\n        : adoptEntity(field, spec.name, segments)\n    }\n    return v\n  }\n  return adoptEntity(v, spec.name, segments)\n}\n\n/**\n * Read the caller-supplied tessellation density from a compat op's args.\n *\n * 裁决 1：faijs 的 `segments` 显式超集在 brepjs 投影侧也必须可选；这里从调用点\n * 的尾参 options（或任一 plain-object 实参）抓取 `segments`，在产出句柄被收编为\n * faijs Shape 时透传给 `fromHandle` 的三角化（§5.2 机制）。默认不传 = 由\n * handle-bridge 的 64 兜底。\n */\nfunction readSegmentsFromArgs(args: unknown[]): number | undefined {\n  for (let i = args.length - 1; i >= 0; i--) {\n    const a = args[i]\n    if (\n      a !== null &&\n      typeof a === 'object' &&\n      !Array.isArray(a) &&\n      Object.getPrototypeOf(a) === Object.prototype\n    ) {\n      const seg = (a as Record<string, unknown>).segments\n      if (typeof seg === 'number' && Number.isFinite(seg)) return seg\n    }\n  }\n  return undefined\n}\n\n/**\n * Build the brep-only adapter: borrow inputs → call the vendor function through\n * the shared unwrap → adopt the product (with the caller's `segments`,\n * 裁决 1/§5.2). The adapter never dispatches and never mounts metadata —\n * those are defineOp's.\n *\n * @param fn   the brepjs-shaped function (dual-form normalization inside, D11).\n * @param spec the static op spec (name + options pass-through).\n * @returns a `BrepImpl` compatible with defineOp's brep-only decl.\n */\nfunction buildAdapter(fn: (...args: unknown[]) => unknown, spec: CompatSpec): BrepImpl<unknown[]> {\n  return async (...args: unknown[]): Promise<BrepProduct> => {\n    const borrowed = args.map((a) => borrowDeep(a, 0))\n    const value = unwrapOrThrow(callBrepjs(fn as never, borrowed), spec.name)\n    return adoptOut(value, spec, readSegmentsFromArgs(args)) as BrepProduct\n  }\n}\n\n/** Carrier of the DualOpMeta mounted by defineOp (same shape as defineOp's). */\ntype MetaCarrier = { [DUAL_OP_META]?: DualOpMeta }\n\n/**\n * Lift a brepjs-shaped function into a defineOp-decorated op facade (brep-only).\n *\n * The decorated product is identical to a defineOp product: same `DUAL_OP_META`\n * field set (kind 'dual-op', brep impl, name, capabilities, outputs, schema,\n * slotMap), same dispatch semantics, same Result boundary. The adapter carries\n * only the brepjs bridging (borrow / call / adopt); every other mechanism\n * belongs to defineOp.\n *\n * @param fn   the brepjs-shaped function.\n * @param spec the static spec (name required; capabilities/outputs/slotMap/\n *  schema pass through and take effect).\n * @returns the compat op facade, carrying dual-op metadata.\n */\nexport function compatOp(\n  fn: (...args: unknown[]) => unknown,\n  spec: CompatSpec,\n): ((...args: unknown[]) => Promise<Shape>) & MetaCarrier {\n  const { outputs, capabilities, schema, slotMap } = spec\n  // `outputs` flows through defineOp's own wrapping path: the adapter adopts\n  // per declared field, then defineOp wraps — isShape passthrough, so no\n  // double wrapping (§3.2).\n  return defineOp({\n    brep: buildAdapter(fn, spec),\n    name: spec.name,\n    capabilities,\n    outputs,\n    schema,\n    slotMap,\n  }) as unknown as ((...args: unknown[]) => Promise<Shape>) & MetaCarrier\n}"]}

package/dist/api/internal/compat-projection.d.ts

@@ -0,0 +1,53 @@
+/**
+ * compat-projection — the single BREP-TS projection wrapper factory (P23, §4.2).
+ *
+ * Design: docs/plans/2026-09-03-faijs-brepjs-compat-api.md §4.2 / §4.3.2
+ *
+ * Every symbol on the TS compat face and every generated `compatOp` op funnels
+ * through {@link projectBrepOp}. That is what makes the generated face and the
+ * hand-curated `api/brepjs-compat` face one mechanism rather than two:
+ *
+ *   1. single-kernel assert (D10) — library code never installs a kernel;
+ *   2. D11 dual-form normalization — object form → positional form, in the
+ *      exported function (§4.2 「归一化位置」), not in a script-side adapter;
+ *   3. the vendored call itself, through `callBrepjs` (Result shape preserved).
+ *
+ * P21's `api/brepjs-compat` used a private copy of steps 1–3 (`wrapDual`); P23 lifts it
+ * here so `gen-l3-surface.ts` can emit one `compatOp(projectBrepOp(…), …)` line
+ * per symbol instead of re-expanding the template for each op.
+ *
+ * @module
+ */
+import { type FormClass } from './dual-form-args.js';
+/**
+ * Assert that a BREP kernel is bound before invoking a compat op.
+ *
+ * Reads the configured backend's kernel slot, guarding against the throw that
+ * `getBackends()` performs before host configuration. Falls back to the
+ * occt-kernel binding flag when nothing is configured.
+ *
+ * @param name - op name, used in the guiding error message.
+ * @throws when no BREP kernel is bound (the message tells the host what to do,
+ * because library code must never install a kernel itself — §4.2 rule 1).
+ */
+export declare function assertKernelBound(name: string): void;
+/** Signature of a projected compat op (inputs normalized before the call). */
+export type CompatProjection = (...args: unknown[]) => unknown;
+/**
+ * Project a vendored brepjs function onto the faijs TS compat face.
+ *
+ * The returned function is brepjs-shaped: positional arguments in, `Result`
+ * (or whatever the vendored function returns) out — no faijs `Shape`, no
+ * adoption. Adoption and the statement-boundary unwrap are `compatOp`'s job
+ * (§4.3.2 steps 4/5), which is why the script face can wrap the very same
+ * projection the TS face exports.
+ *
+ * @param name      - op name (error messages + D11 discriminant context).
+ * @param params    - machine parameter-name table (object form → positional).
+ * @param formClass - D11 form class (A single-name dual-form / B1 options-only /
+ *                    B2 two names).
+ * @param impl      - the vendored function.
+ * @returns the projected compat op.
+ */
+export declare function projectBrepOp(name: string, params: string[], formClass: FormClass, impl: (...args: never[]) => unknown): CompatProjection;
+//# sourceMappingURL=compat-projection.d.ts.map

package/dist/api/internal/compat-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compat-projection.d.ts","sourceRoot":"","sources":["../../../src/api/internal/compat-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAK9D;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAapD;AAED,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GAClC,gBAAgB,CAMlB"}

package/dist/api/internal/compat-projection.js

@@ -0,0 +1,72 @@
+/**
+ * compat-projection — the single BREP-TS projection wrapper factory (P23, §4.2).
+ *
+ * Design: docs/plans/2026-09-03-faijs-brepjs-compat-api.md §4.2 / §4.3.2
+ *
+ * Every symbol on the TS compat face and every generated `compatOp` op funnels
+ * through {@link projectBrepOp}. That is what makes the generated face and the
+ * hand-curated `api/brepjs-compat` face one mechanism rather than two:
+ *
+ *   1. single-kernel assert (D10) — library code never installs a kernel;
+ *   2. D11 dual-form normalization — object form → positional form, in the
+ *      exported function (§4.2 「归一化位置」), not in a script-side adapter;
+ *   3. the vendored call itself, through `callBrepjs` (Result shape preserved).
+ *
+ * P21's `api/brepjs-compat` used a private copy of steps 1–3 (`wrapDual`); P23 lifts it
+ * here so `gen-l3-surface.ts` can emit one `compatOp(projectBrepOp(…), …)` line
+ * per symbol instead of re-expanding the template for each op.
+ *
+ * @module
+ */
+import { resolveArgs } from './dual-form-args.js';
+import { callBrepjs } from './l3-bridge.js';
+import { isOcctKernelBound } from '../occt-kernel-bridge.js';
+import { getBackends } from '../../runtime-state.js';
+/**
+ * Assert that a BREP kernel is bound before invoking a compat op.
+ *
+ * Reads the configured backend's kernel slot, guarding against the throw that
+ * `getBackends()` performs before host configuration. Falls back to the
+ * occt-kernel binding flag when nothing is configured.
+ *
+ * @param name - op name, used in the guiding error message.
+ * @throws when no BREP kernel is bound (the message tells the host what to do,
+ * because library code must never install a kernel itself — §4.2 rule 1).
+ */
+export function assertKernelBound(name) {
+    let kernelBound = false;
+    try {
+        kernelBound = getBackends().kernel.brep != null;
+    }
+    catch {
+        // backends not configured yet — that is not an error, just no kernel
+    }
+    if (!kernelBound && !isOcctKernelBound()) {
+        throw new Error(`[compat:${name}] no BREP kernel bound; run host init/bind (e.g. initOcct + bindOcctKernel) ` +
+            `before the first compat.${name} call. Library code must not install kernels itself.`);
+    }
+}
+/**
+ * Project a vendored brepjs function onto the faijs TS compat face.
+ *
+ * The returned function is brepjs-shaped: positional arguments in, `Result`
+ * (or whatever the vendored function returns) out — no faijs `Shape`, no
+ * adoption. Adoption and the statement-boundary unwrap are `compatOp`'s job
+ * (§4.3.2 steps 4/5), which is why the script face can wrap the very same
+ * projection the TS face exports.
+ *
+ * @param name      - op name (error messages + D11 discriminant context).
+ * @param params    - machine parameter-name table (object form → positional).
+ * @param formClass - D11 form class (A single-name dual-form / B1 options-only /
+ *                    B2 two names).
+ * @param impl      - the vendored function.
+ * @returns the projected compat op.
+ */
+export function projectBrepOp(name, params, formClass, impl) {
+    return (...args) => {
+        assertKernelBound(name);
+        const positional = resolveArgs(args, { name, params, formClass });
+        return callBrepjs(impl, positional);
+    };
+}
+//# sourceMappingURL=compat-projection.js.map

package/dist/api/internal/compat-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compat-projection.js","sourceRoot":"","sources":["../../../src/api/internal/compat-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAkB,MAAM,kBAAkB,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEjD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,WAAW,GAAG,KAAK,CAAA;IACvB,IAAI,CAAC;QACH,WAAW,GAAG,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAA;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;IACvE,CAAC;IACD,IAAI,CAAC,WAAW,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,8EAA8E;YAC3F,2BAA2B,IAAI,sDAAsD,CACxF,CAAA;IACH,CAAC;AACH,CAAC;AAKD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,MAAgB,EAChB,SAAoB,EACpB,IAAmC;IAEnC,OAAO,CAAC,GAAG,IAAe,EAAE,EAAE;QAC5B,iBAAiB,CAAC,IAAI,CAAC,CAAA;QACvB,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAA;QACjE,OAAO,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IACrC,CAAC,CAAA;AACH,CAAC","sourcesContent":["/**\n * compat-projection — the single BREP-TS projection wrapper factory (P23, §4.2).\n *\n * Design: docs/plans/2026-09-03-faijs-brepjs-compat-api.md §4.2 / §4.3.2\n *\n * Every symbol on the TS compat face and every generated `compatOp` op funnels\n * through {@link projectBrepOp}. That is what makes the generated face and the\n * hand-curated `api/brepjs-compat` face one mechanism rather than two:\n *\n *   1. single-kernel assert (D10) — library code never installs a kernel;\n *   2. D11 dual-form normalization — object form → positional form, in the\n *      exported function (§4.2 「归一化位置」), not in a script-side adapter;\n *   3. the vendored call itself, through `callBrepjs` (Result shape preserved).\n *\n * P21's `api/brepjs-compat` used a private copy of steps 1–3 (`wrapDual`); P23 lifts it\n * here so `gen-l3-surface.ts` can emit one `compatOp(projectBrepOp(…), …)` line\n * per symbol instead of re-expanding the template for each op.\n *\n * @module\n */\n\nimport { resolveArgs, type FormClass } from './dual-form-args'\nimport { callBrepjs } from './l3-bridge'\nimport { isOcctKernelBound } from '../occt-kernel-bridge'\nimport { getBackends } from '../../runtime-state'\n\n/**\n * Assert that a BREP kernel is bound before invoking a compat op.\n *\n * Reads the configured backend's kernel slot, guarding against the throw that\n * `getBackends()` performs before host configuration. Falls back to the\n * occt-kernel binding flag when nothing is configured.\n *\n * @param name - op name, used in the guiding error message.\n * @throws when no BREP kernel is bound (the message tells the host what to do,\n * because library code must never install a kernel itself — §4.2 rule 1).\n */\nexport function assertKernelBound(name: string): void {\n  let kernelBound = false\n  try {\n    kernelBound = getBackends().kernel.brep != null\n  } catch {\n    // backends not configured yet — that is not an error, just no kernel\n  }\n  if (!kernelBound && !isOcctKernelBound()) {\n    throw new Error(\n      `[compat:${name}] no BREP kernel bound; run host init/bind (e.g. initOcct + bindOcctKernel) ` +\n        `before the first compat.${name} call. Library code must not install kernels itself.`\n    )\n  }\n}\n\n/** Signature of a projected compat op (inputs normalized before the call). */\nexport type CompatProjection = (...args: unknown[]) => unknown\n\n/**\n * Project a vendored brepjs function onto the faijs TS compat face.\n *\n * The returned function is brepjs-shaped: positional arguments in, `Result`\n * (or whatever the vendored function returns) out — no faijs `Shape`, no\n * adoption. Adoption and the statement-boundary unwrap are `compatOp`'s job\n * (§4.3.2 steps 4/5), which is why the script face can wrap the very same\n * projection the TS face exports.\n *\n * @param name      - op name (error messages + D11 discriminant context).\n * @param params    - machine parameter-name table (object form → positional).\n * @param formClass - D11 form class (A single-name dual-form / B1 options-only /\n *                    B2 two names).\n * @param impl      - the vendored function.\n * @returns the projected compat op.\n */\nexport function projectBrepOp(\n  name: string,\n  params: string[],\n  formClass: FormClass,\n  impl: (...args: never[]) => unknown,\n): CompatProjection {\n  return (...args: unknown[]) => {\n    assertKernelBound(name)\n    const positional = resolveArgs(args, { name, params, formClass })\n    return callBrepjs(impl, positional)\n  }\n}\n"]}

package/dist/api/internal/dual-form-args.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 条目不走判别器（两个名字各自固定形态）。
+ */
+/** 形态分类。 */
+export type FormClass = 'A' | 'B1' | 'B2';
+/** 参数规格。 */
+export interface ArgSpec {
+    /** op 名（错误信息用）。 */
+    name: string;
+    /** 机器参数名表（按位置顺序），用于对象形态→位置数组映射。 */
+    params?: string[];
+    /** 形态分类。 */
+    formClass: FormClass;
+}
+/**
+ * 判定参数是否为对象形态。
+ *
+ * 判别式（全仓统一）：
+ * - 首参是 plain object（Object.getPrototypeOf(a) === Object.prototype）
+ * - 且非 Shape、非句柄、非数组
+ *
+ * @param args - 调用参数数组
+ * @returns 是否为对象形态
+ */
+export declare function isObjectForm(args: unknown[]): boolean;
+/**
+ * 将对象形态参数归一化为位置数组。
+ *
+ * @param obj - 对象形态参数
+ * @param params - 机器参数名表
+ * @param opName - op 名（错误信息用）
+ * @returns 位置数组（缺省键 → undefined）
+ * @throws E_ARGS_FORM 对象含 params 外未知键时
+ */
+export declare function normalizeObjectForm(obj: Record<string, unknown>, params: string[], opName: string): unknown[];
+/**
+ * 参数双形态归一化判别器。
+ *
+ * 根据 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 declare function resolveArgs(args: unknown[], spec: ArgSpec): unknown[];
+/**
+ * 双形态归一化结果。
+ *
+ * 包含归一化后的参数和是否为对象形态的标记。
+ */
+export interface ResolvedArgs {
+    /** 归一化后的参数数组。 */
+    args: unknown[];
+    /** 是否为对象形态。 */
+    isObjectForm: boolean;
+}
+/**
+ * 参数双形态归一化判别器（带形态信息）。
+ *
+ * 与 resolveArgs 相同，但返回形态信息。
+ *
+ * @param args - 调用参数数组
+ * @param spec - 参数规格
+ * @returns 归一化结果
+ */
+export declare function resolveArgsWithInfo(args: unknown[], spec: ArgSpec): ResolvedArgs;
+/**
+ * 位置形态声明（D11 反方向，§4.2「归一方向 = 位置→对象」）。
+ *
+ * faijs 特有 dual op 的 impl 是对象形态原生（`box(width, depth, height)` 经
+ * 装箱为 `{ width, depth, height, ... }`，`translate(shape, { offset })`），brepjs 生态
+ * 的位置形态（`box(10, 20, 30, { centered: true })` / `translate(shape, 1, 0, 0)`）
+ * 需先归一成对象形态。
+ * 声明式而非 if 分支：op 作者只列「哪个键吃几个位置参数」，判别与装箱由
+ * {@link positionalToObject} 统一完成。
+ *
+ * 与语句层的 `StatementSummary.positional`（位置实参**值**）以及投影侧的
+ * `ArgSpec.params`（对象→位置**参数名表**）是三个不同概念：`SlotMap` 是
+ * 位置槽→对象键的**装箱声明**（位置→对象，D11 反方向；§9 命名区分）。
+ */
+export interface SlotMap {
+    /**
+     * 对象形态键名，按位置顺序（只描述 Shape 之后的**非几何**形参）。
+     * 例：`box(10, 20, 30)` → `keys: ['size']`；`cylinder(5, 40)` →
+     * `keys: ['radius', 'height']`。
+     */
+    keys: string[];
+    /**
+     * 哪些键是 vec3 槽位（吃掉最多 3 个连续位置参数）。
+     * 1 个 → 标量（number 或数组原样）；2~3 个 → `[x, y(, z)]` 数组。
+     * 例：`box(10)` → `{ size: 10 }`；`box(10, 20, 30)` → `{ size: [10, 20, 30] }`。
+     */
+    vec3Keys?: string[];
+    /**
+     * 前置 Shape 形参个数（原样透传，不参与装箱），缺省 0。
+     * 例：`translate(shape, 1, 0, 0)` → `shapeArity: 1`。
+     */
+    shapeArity?: number;
+}
+/**
+ * 位置形态 → 对象形态归一（faijs 特有 dual op 的 D11 反方向）。
+ *
+ * 触发条件：声明了 slotMap 且对象槽位（第 `shapeArity` 个实参）不是
+ * plain object。已是对象形态或实参不足时原样返回（交由 op 自身的断言报错）。
+ *
+ * @param args - 调用参数数组
+ * @param form - slotMap 声明（位置槽→对象键装箱表）
+ * @param name - op 名（错误信息用）
+ * @returns 归一后的参数数组（前置 Shape 原样 + 末尾一个对象形态参数）
+ * @throws E_ARGS_FORM 位置参数个数与声明的槽位不匹配时
+ */
+export declare function positionalToObject(args: unknown[], form: SlotMap, name: string): unknown[];
+//# sourceMappingURL=dual-form-args.d.ts.map

package/dist/api/internal/dual-form-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dual-form-args.d.ts","sourceRoot":"","sources":["../../../src/api/internal/dual-form-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,YAAY;AACZ,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;AAEzC,YAAY;AACZ,MAAM,WAAW,OAAO;IACtB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,YAAY;IACZ,SAAS,EAAE,SAAS,CAAA;CACrB;AAOD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAQrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,EAAE,CAUX;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,EAAE,CAgCrE;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,IAAI,EAAE,OAAO,EAAE,CAAA;IACf,eAAe;IACf,YAAY,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,YAAY,CA0BhF;AAMD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,OAAO;IACtB;;;;OAIG;IACH,IAAI,EAAE,MAAM,EAAE,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAoD1F"}