FreeCADWasmDev/docs/current/part-primitives-projection-checkpoint.md

# Part Primitives And Projection Checkpoint

Batch: `4aa3ea5e85f9c4b3e4412ba2`. Selected requirements:
`Part:desktop:Part_Primitives`, `Part:desktop:Part_ProjectionOnSurface`.
Checkpoint date: 2026-09-17.

## Latest Continuation: Active Part Membership (10:42 UTC)

This section supersedes the earlier next-action and remaining-primitives notes
below; the earlier Wedge/link-failure history is preserved.

Implemented the mounted primitive task's Active Part selector. New primitives
can be created at document root or within an existing current-document
`App::Part`, including nested Parts. The Part adapter forwards
`primitiveContainer`; the facade rejects malformed identifiers and use during
edits. DocumentProbe validates the container before opening the transaction and
updates its real native Group property in the same transaction as creation.
Snapshots expose `groupMembers`. Editing a primitive preserves its membership.
No new geometry backend or frontend geometry algorithm was introduced.

Desktop source reused: `freecad-source/src/Mod/Part/Gui/DlgPrimitives.cpp:66`,
`getAutoGroupCommandStr`, which adds new objects to the active Part.
The existing primitive panel is already mounted by `workbench-shell.tsx`; no
shared dispatcher or shell change was needed.

Files changed in this continuation:

- `freecad-source/src/WebAssembly/FreeCADCoreProbe/DocumentProbe.cpp`
- `web/src/part-document-facade.ts`
- `web/src/part-desktop-adapter.ts`
- `web/src/part-primitives-task.tsx`
- `tools/part-primitive-container-business-cases.mjs` (new)
- `tools/part-primitive-business-cases.mjs` (selected entry now runs container gap)

Focused `FreeCADWebDocumentProbe` build completed successfully under
`tools/web_build_lock.py`, `-j2`. JS, WASM and worker JS were synchronized from
`freecad-source/build-web/configure/bin/` to `web/public/kernel/`.
`web/node_modules/.bin/tsc --noEmit -p web/tsconfig.json` passed, as did scoped
`git diff --check`. The first tsc invocation with a working-directory-relative
path failed to locate the executable; the repository-relative command above
was used successfully. No full build, parity/API gate or deployment ran.

Acceptance runner invoked only `Part:desktop:Part_Primitives`, with `--reuse`.
First run reached FCStd restoration and failed an exact comparison on a one-bit
attachment quaternion difference. The case now compares persisted numeric data
with absolute tolerance 1e-9 while requiring identical structure, strings and
membership. Earlier transaction/error comparisons remain exact.
First-run evidence is preserved:
`docs/current/business-evidence/13fb362e5bcf598a7f1f90a6-20260917T104119898549.json`.

Final focused runner evidence:
`docs/current/business-evidence/13fb362e5bcf598a7f1f90a6-20260917T104214880624.json`.
Both native and browser assertion groups completed successfully in 19.979 s.
Native checks cover analytic box volume, Part membership, nested groups, unique
names, root creation, unchanged existing geometry, membership-preserving edits,
atomic undo/redo, adapter/direct-native invalid inputs, cancellation, another
document, FCStd save/open and subsequent creation. Browser checks use the mounted
selector, creation, undo/redo, real OPFS save, reload/file-open and native group
state, plus mobile bounds and page-error checks.
Artifacts: `docs/current/part-primitive-container-business/2026-09-17T10-41-55-217Z/`.
The mobile screenshot was visually inspected; the selector fits its panel.
Native initialization took approximately 0.418 s; native cases completed before
cleanup at 10:42:06.300 UTC; browser completed at 10:42:14.426 UTC. Worker threads
and the test browser were cleaned up.

Overall runner status remains `acceptance_incomplete`, selected result
`not_implemented`, passed business records zero. This is intentional partial
evidence, not completed Part_Primitives acceptance. No passing ledger statuses,
contract, verifier, proof requirements, acceptance machinery or covers tags were
edited. Original/supplemental requirements and IFC semantic contract remain in
force; no IFC work or revalidation occurred.

### Next Work And Boundaries

1. Projection's recorded first error remains `Projection source must be a Part
   feature`. The exact read of `PartProjectionDocument.h` was again rejected as
   outside current packet dependencies. It exists and is included by
   DocumentProbe, but was not read via another route, changed or retested.
   Make that required source anchor available in a future packet, then repair
   linked support/source resolution and run the existing focused linked case.
2. Active-Part membership is implemented and exercised for identity container
   placements. Transformed-container viewport geometry still needs completion:
   `DocumentProbe.cpp:2062` copies `feature->Shape.getValue()` for topology,
   edges and point output, using local feature placement. Inspect the mesh path
   and native global-placement API before editing; retain local editable
   placement while rendering global native geometry. Do not silently claim this
   boundary is covered by the identity-container cases.
3. Cylinder skew, circle-from-three-points interaction, desktop expression
   binding and live task lifecycle remain. Helix/Spiral and placement code/cases
   already exist; the prior selected export ran `runPrimitivePlacementCases`.
   Reuse those implementations and evidence instead of rebuilding them.
4. Projection still needs preview activation/live updates/accept/reject rollback
   and viewport subelement selection gates, in addition to linked objects.

The scoped reader also rejected `freecad-source/src/App/Part.h`; that denial is
not a missing-source conclusion. Existing native Group property types were
used and exercised. The earlier unrestricted git status attempt was rejected;
the scoped check was used. No agents, schedulers, pushes or external messages
were started.

Existing server remains available at
`http://127.0.0.1:5180/workbench.html?module=Part&command=Part_Primitives`.
Do not replay this unchanged focused case solely to refresh evidence; proceed
to the next missing behavior and retain all historical cases.

## Newly Implemented And Executed

Wedge is available in the existing mounted Part primitives task. The document
facade and native `DocumentProbe.cpp` now accept all ten native Wedge coordinates,
including negative coordinates. Base intervals must exceed native confusion
tolerance; end intervals may collapse to a line or point. Creation uses the
existing `Part::Wedge`, transactions, native property serialization and OCCT
geometry. No surrogate geometry was introduced.

`tools/part-wedge-business-cases.mjs` executed through the acceptance runner:
analytic volume of initial and edited shapes; valid collapsed ends; six invalid
inputs through both adapter and direct native calls; unchanged objects/history
after errors; unique names; preserved existing objects; document isolation;
undo/redo; FCStd save/close/open/edit; mounted browser create/edit; OPFS save,
reload/open/edit/history; desktop/mobile canvas pixels and overflow checks.
Both recorded assertion groups completed. Mobile screenshot was also inspected.

Evidence, written by the acceptance runner:
`docs/current/business-evidence/13fb362e5bcf598a7f1f90a6-20260917T085440494693.json`.
Case artifacts:
`docs/current/part-wedge-business/2026-09-17T08-54-27-244Z/`.
Overall command remains `not_implemented`; no passing requirement status was
claimed or edited. The runner completed in 13.968 seconds.

Build completed:
`cmake --build freecad-source/build-web/configure --target FreeCADWebDocumentProbe -j2`.
The resulting JS, WASM and worker JS were copied from the build bin directory
to `web/public/kernel/`. Existing server responds at `http://127.0.0.1:5180`.

## First Unresolved Error

Added `tools/part-linked-projection-business-cases.mjs`, a focused native/browser
case for translated `App::Link` support and source objects. It checks actual
projected coordinates, retained link identity/dependencies, recomputation after
link placement edits, invalid subelements, FCStd restoration, and mounted task
selection. The first native create currently fails before any assertion group
completes:

`document_operation_failed: Projection source must be a Part feature`

Input: support `SupportLink.Face1`, source `SourceLink.Edge1`, direction
`[0,0,-1]`, mode `Edges`, height/offset zero. The linked support is a 20-by-20
plane translated to Z=2. The source is an edge from (2,3,7) to (6,3,7), linked
with translation (1,2,0). Expected projected endpoints are (3,5,2) and (7,5,2).

Runner evidence:
`docs/current/business-evidence/7eb5ff3f52f792bd7cf89e8e-20260917T085805452906.json`.
This focused execution took 3.228 seconds. Do not retry unchanged input until
the native rejection is repaired. A later test-only edit keeps linked-object
coverage explicitly in `remaining` until every native/browser assertion succeeds;
it was not used to rerun the unchanged failure.

## Next Source Anchors

1. `freecad-source/src/WebAssembly/FreeCADCoreProbe/PartProjectionDocument.h`:
   validation emitting `Projection source must be a Part feature`. This is the
   necessary next read. The reader rejected this file as outside current packet
   dependencies, despite the existing projection case identifying it. Preserve
   that distinction: source exists, but its contents were not available this turn.
   Resolve and validate native links while retaining original link references.
2. `freecad-source/src/WebAssembly/FreeCADCoreProbe/DocumentProbe.cpp:1920`:
   snapshot geometry currently enters a `dynamic_cast<Part::Feature*>(item)`
   branch. Linked geometry likely needs resolved topology for the mounted
   projection chooser. Obtain a bounded window before editing. That window was
   denied after the 32-window/96000-byte turn allowance was exhausted.
3. `freecad-source/src/Mod/Part/App/FeatureProjectOnSurface.cpp:108`:
   `getSupportFace()` obtains `SupportFace.getValue<Part::Feature*>()` before
   calling `Feature::getTopoShape` with ResolveLink/Transform. Verify retained
   link placement semantics using the new numeric assertions. Source projection
   resolution already calls `getTopoShape` on the stored document objects.

After a concrete fix, incrementally rebuild the affected native target, sync
its artifacts, then run:
`python3 tools/run_business_acceptance.py --module Part --ids Part:desktop:Part_ProjectionOnSurface --reuse`.

## Preserved Boundaries

Primitives still require Helix, Spiral, placement/orientation and active-container
controls, cylinder skew, and circle-from-three-points interaction.
Projection still requires linked-object completion, desktop preview transaction
semantics (activation/live updates/accept/reject rollback), and viewport
subelement selection gates.

Existing primitive and projection case bodies remain available as
`runLegacyPrimitiveTaskCases`, `runAdditionalPrimitiveCases`, and
`runLegacyProjectionCases`. Current selected entry points execute the new Wedge
and linked-projection gaps only, deferring previously verified cases per user
direction. No broad regression or stale-evidence refresh was performed.

No acceptance contract, proof requirements, verifier, acceptance runner, IFC
semantic contract, IFC evidence, or pass statuses were modified. IFC was not
selected and was not revalidated. No deployment, push, external messages, new
agents, or schedulers were started.