feat: prepare FreeCAD private naming worker linkage

native/occt-history/CMakeLists.txt

@@ -13,6 +13,18 @@ find_package(OpenCASCADE REQUIRED CONFIG PATHS "${OCCT_DIR}" NO_DEFAULT_PATH)
 add_executable(bitbybit_occt_history occt_history.cpp)
 target_include_directories(bitbybit_occt_history PRIVATE "${OCCT_DIR}/include/opencascade")
 target_link_libraries(bitbybit_occt_history PRIVATE TKDESTEP TKXSBase TKDE TKBO TKBRep TKTopAlgo TKPrim TKShHealing TKGeomAlgo TKGeomBase TKG3d TKG2d TKMath TKernel)
+if(FREECAD_WASM_SDK_DIR)
+  if(NOT FREECAD_NAMING_BRIDGE_SOURCE OR NOT EXISTS "${FREECAD_NAMING_BRIDGE_SOURCE}")
+    message(FATAL_ERROR "FREECAD_NAMING_BRIDGE_SOURCE must point to the verified FreeCAD private naming bridge source.")
+  endif()
+  if(NOT FREECAD_NAMING_INCLUDE_DIRS OR NOT FREECAD_NAMING_LIBRARIES)
+    message(FATAL_ERROR "FREECAD_NAMING_INCLUDE_DIRS and FREECAD_NAMING_LIBRARIES are required for a FreeCAD-linked Worker.")
+  endif()
+  target_sources(bitbybit_occt_history PRIVATE "${FREECAD_NAMING_BRIDGE_SOURCE}")
+  target_include_directories(bitbybit_occt_history PRIVATE ${FREECAD_NAMING_INCLUDE_DIRS})
+  target_link_libraries(bitbybit_occt_history PRIVATE ${FREECAD_NAMING_LIBRARIES})
+  target_compile_definitions(bitbybit_occt_history PRIVATE BITBYBIT_FREECAD_NAMING_LINKED=1)
+endif()
 target_compile_options(bitbybit_occt_history PRIVATE -fexceptions -O2)
 target_link_options(bitbybit_occt_history PRIVATE
   --bind

native/occt-history/README.md

@@ -19,6 +19,35 @@ The build also publishes the JS/WASM pair to
 clean checkout must run the build after restoring the pinned OCCT source and
 Emscripten toolchain.
 
+## FreeCAD private naming build boundary
+
+The default build is intentionally OCCT-only. It does not export
+`freecadNamingAbiVersion`, `freecadNamingCapabilitiesJson`, or
+`freecadNamingEvidenceJson`, and it must not be described as exact FreeCAD
+naming support.
+
+A separate fail-closed build lane is available for an actual FreeCAD WASM SDK:
+
+```bash
+FREECAD_WASM_SDK_DIR=/absolute/path/to/sdk ./npmw run check:freecad-naming-sdk
+FREECAD_WASM_SDK_DIR=/absolute/path/to/sdk ./npmw run build:freecad-naming-worker
+./npmw run check:occt-history-artifact
+```
+
+The SDK layout is defined by `freecad-wasm-sdk-manifest.example.json`. The
+checker requires the locked FreeCAD 1.1.1 commit, Emscripten 3.1.69, wasm Qt
+and Python targets, private App headers, hashed static FreeCAD/Part/Qt/Python
+libraries, and a hashed bridge source exporting all three callbacks. If any
+input is absent, `build:freecad-naming-worker` exits before rebuilding or
+publishing the OCCT-only artifact. A successful artifact probe still only
+establishes ABI linkage; exact promotion additionally requires valid
+MappedNameRef, StringHasher, ElementMap2, stage history, and round-trip evidence.
+
+The versioned JSON request carries document `objectId`, stable positive
+`objectTag`, prior naming evidence, result object identity, result tag, stage
+DAG, STEP/BRep, and OCCT Generated/Modified/Deleted history. No Web fallback is
+allowed to synthesize a FreeCAD private token.
+
 The exported `booleanHistory(object, tool, operation)` function supports
 `fuse`, `cut`, and `common`. It returns the native result shape, per-input
 `modified`/`generated`/`deleted` records, a validity/topology/quality summary,

native/occt-history/build.sh

@@ -7,6 +7,15 @@ OCCT_BUILD_DIR="${OCCT_BUILD_DIR:-${ROOT_DIR}/.cache/bitbybit/occt-history-build
 DIST_DIR="${OCCT_HISTORY_DIST_DIR:-${ROOT_DIR}/native/occt-history/dist}"
 PUBLIC_DIR="${OCCT_HISTORY_PUBLIC_DIR:-${ROOT_DIR}/public/native/occt-history}"
 JOBS="${JOBS:-$(nproc)}"
+FREECAD_WASM_SDK_DIR="${FREECAD_WASM_SDK_DIR:-}"
+
+if [[ "${FREECAD_WASM_NAMING_REQUIRED:-0}" == "1" && -z "${FREECAD_WASM_SDK_DIR}" ]]; then
+  echo "FREECAD_WASM_SDK_DIR is required for build:freecad-naming-worker; refusing to produce an OCCT-only artifact." >&2
+  exit 1
+fi
+if [[ -n "${FREECAD_WASM_SDK_DIR}" ]]; then
+  FREECAD_WASM_SDK_DIR="${FREECAD_WASM_SDK_DIR}" node "${ROOT_DIR}/scripts/check-freecad-naming-sdk.mjs" >/dev/null
+fi
 
 if [[ ! -f "${OCCT_SOURCE_DIR}/CMakeLists.txt" ]]; then
   echo "OCCT source checkout not found: ${OCCT_SOURCE_DIR}" >&2
@@ -47,7 +56,19 @@ cmake --build "${OCCT_BUILD_DIR}" --target \
   --parallel "${JOBS}"
 mkdir -p "${DIST_DIR}"
 
-em++ "${ROOT_DIR}/native/occt-history/occt_history.cpp" \
+SOURCES=("${ROOT_DIR}/native/occt-history/occt_history.cpp")
+INCLUDES=("-I${OCCT_BUILD_DIR}/include/opencascade" "-I${OCCT_SOURCE_DIR}/src")
+DEFINES=()
+FREECAD_LIBRARIES=()
+if [[ -n "${FREECAD_WASM_SDK_DIR}" ]]; then
+  BRIDGE_SOURCE="$(node -e 'const fs=require("node:fs"); const p=require("node:path"); const m=JSON.parse(fs.readFileSync(p.resolve(process.argv[1],"manifest.json"),"utf8")); console.log(p.isAbsolute(m.namingBridge.source) ? m.namingBridge.source : p.resolve(process.argv[1],m.namingBridge.source))' "${FREECAD_WASM_SDK_DIR}")"
+  SOURCES+=("${BRIDGE_SOURCE}")
+  while IFS= read -r include_dir; do INCLUDES+=("-I${include_dir}"); done < <(node -e 'const fs=require("node:fs"); const p=require("node:path"); const root=p.resolve(process.argv[1]); const m=JSON.parse(fs.readFileSync(p.resolve(root,"manifest.json"),"utf8")); for (const d of m.includeDirs) console.log(p.isAbsolute(d) ? d : p.resolve(root,d))' "${FREECAD_WASM_SDK_DIR}")
+  while IFS= read -r library; do FREECAD_LIBRARIES+=("${library}"); done < <(node -e 'const fs=require("node:fs"); const p=require("node:path"); const root=p.resolve(process.argv[1]); const m=JSON.parse(fs.readFileSync(p.resolve(root,"manifest.json"),"utf8")); for (const l of m.libraries) console.log(p.isAbsolute(l.path) ? l.path : p.resolve(root,l.path))' "${FREECAD_WASM_SDK_DIR}")
+  DEFINES+=("-DBITBYBIT_FREECAD_NAMING_LINKED=1")
+fi
+
+em++ "${SOURCES[@]}" "${INCLUDES[@]}" "${DEFINES[@]}" \
   -I"${OCCT_BUILD_DIR}/include/opencascade" \
   -I"${OCCT_SOURCE_DIR}/src" \
   -std=c++17 -O2 -fexceptions --bind \
@@ -69,6 +90,7 @@ em++ "${ROOT_DIR}/native/occt-history/occt_history.cpp" \
   "${OCCT_BUILD_DIR}/lin32/clang/lib/libTKG2d.a" \
   "${OCCT_BUILD_DIR}/lin32/clang/lib/libTKMath.a" \
   "${OCCT_BUILD_DIR}/lin32/clang/lib/libTKernel.a" \
+  "${FREECAD_LIBRARIES[@]}" \
   -Wl,--end-group \
   -sMODULARIZE=1 -sEXPORT_ES6=1 -sENVIRONMENT=web,worker,node \
   -sALLOW_MEMORY_GROWTH=1 -sINITIAL_MEMORY=134217728 -sMAXIMUM_MEMORY=2147483648 \

native/occt-history/freecad-wasm-sdk-manifest.example.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "freecadVersion": "1.1.1",
+  "sourceCommit": "0108fd4b4850cc46e625b60e53cea7a7bbe69f8d",
+  "emscriptenVersion": "3.1.69",
+  "qtTarget": "wasm32-emscripten",
+  "pythonTarget": "wasm32-emscripten",
+  "includeDirs": [
+    "include",
+    "include/FreeCAD"
+  ],
+  "libraries": [
+    { "name": "FreeCADBase", "path": "lib/libFreeCADBase.a", "sha256": "replace-with-64-lowercase-hex-digits" },
+    { "name": "FreeCADApp", "path": "lib/libFreeCADApp.a", "sha256": "replace-with-64-lowercase-hex-digits" },
+    { "name": "Part", "path": "lib/libPart.a", "sha256": "replace-with-64-lowercase-hex-digits" },
+    { "name": "QtCore", "path": "lib/libQt6Core.a", "sha256": "replace-with-64-lowercase-hex-digits" },
+    { "name": "Python", "path": "lib/libpython3.a", "sha256": "replace-with-64-lowercase-hex-digits" }
+  ],
+  "namingBridge": {
+    "source": "src/freecad_naming_bridge.cpp",
+    "sha256": "replace-with-64-lowercase-hex-digits",
+    "exports": [
+      "freecadNamingAbiVersion",
+      "freecadNamingCapabilitiesJson",
+      "freecadNamingEvidenceJson"
+    ]
+  }
+}