Shaperef Lineage

Adding a new reference kind

The four existing kinds (face, edge, vertex, derived) share one contract. To add a fifth, work through this checklist against the real files. Follow the export-surface mechanics in the adding-operations sibling skill — a new create*/resolve* pair must flow through the same six export surfaces plus the brepjs/shapeRef subpath.

1. Types — in shapeRefTypes.ts add XRef, its XHint, ResolvedXRef (with a confidence), and BrokenXRef. Decide the failure taxonomy up front: it can report deleted only if it tracks its own face hash; if it names itself by neighbour roles (the recommended pattern), its reason is 'ambiguous' | 'not-found' like edge/vertex.
2. Functions — new xRefFns.ts with createXRef (capture the hint on the pre-edit shape) and resolveXRef. Follow the established pattern: resolve neighbour roles via roleLookup.ts helpers (facesForRole, roleOfFace), disambiguate with the hint, apply an ambiguity margin. Return early not-found when facesForRole yields [].
3. Dispatch — in refResolveFns.ts add an isXRef structural guard and a branch in resolveLineageRef, and extend the LineageRef union (and ResolvedEntity if it resolves to a new entity type). Guard ordering is load-bearing: guards discriminate structurally, most-specific first. Current order is derived (betweenRoles + op) → edge (faceRoles.length === 2) → vertex (faceRoles.length >= 3) → face (role is a string). Place a new guard so it can't be shadowed by a looser one.
4. Barrels — export from src/topology/shapeRef/index.ts, src/shapeRef.ts, and src/index.ts. Once it's in the LineageRef union and the guards, it auto-flows through resolveRefParams and history replay for free.
5. Recursion caveat — resolveRefParams descends via isPlainOptions, which skips arrays it already handled, non-plain-prototype objects, and anything with a wrapped key. Keep the new ref a plain serializable object (like the others); a class instance would be silently skipped by the walker.
6. Test — add tests/shapeRefXReplay.test.ts gated to occt-wasm. Use the divergence-skip mechanics owned by the writing-tests sibling skill (currentKernelId, shouldSkipSuite, describe.skipIf).

How history replay resolves refs

Replay lets a stored selection survive an upstream parameter edit. The engine is src/operations/historyFns.ts (ModelHistory / OperationStep are pure data; OperationRegistry maps op name → OperationFn).

• resolveStepParams(params, inputs) resolves refs only for single-input, 3D steps — it calls resolveRefParams against the sole input. Multi-input, ref-free, or non-3D steps are left raw: with several inputs the target input is ambiguous, and resolving against the wrong input would silently return a wrong-shape entity.
• Called from both replayHistory and replayFrom before invoking the OperationFn.
• The stored step keeps its raw refs; resolution happens fresh at each replay. A ShapeRef is plain JSON, so it survives serializeHistory/deserializeHistory.
• modifyStep(stepId, newParams) is the parametric-edit loop: it updates the params then replayFroms that step.
• tests/historyRefReplay.test.ts is the canonical worked example (re-targets an edge after a box-height edit; multi-input leaves the ref raw).

Replay errors are Result.Err with codes REPLAY_UNKNOWN_OP / REPLAY_MISSING_INPUT / REPLAY_STEP_FAILED / REPLAY_STEP_NOT_FOUND / MODIFY_STEP_NOT_FOUND.

Where evolution comes from

ShapeEvolution = { modified, generated, deleted } (src/kernel/types.ts) is built in src/kernel/occt/evolutionOps.ts and produced by the *WithHistory kernel methods in src/kernel/occt/historyOps.ts (wired via makeHistoryOps). Fillet/chamfer go through BRepFilletAPI_MakeFillet/MakeChamfer; the plumbing populates generated, but on occt-wasm those Generated() results don't map to final-shape faces — the empty/never-live reality above. For anything kernel-side (adding a *WithHistory method, adapter capability differences), defer to the kernel-abstraction sibling skill; for the embind enum/hash-code details underlying evolutionOps.ts, defer to wasm-interop.

Worked examples in the test suite

tests/shapeRefEditReplay.test.ts (modified-face tracking + split-fragment disambiguation), tests/shapeRefDerivedReplay.test.ts (fillet/chamfer normal-blend, occt-wasm-gated), tests/shapeRefEdgeReplay.test.ts, tests/shapeRefVertexReplay.test.ts, tests/historyRefReplay.test.ts, and the unit/integration pair tests/shapeRef.test.ts + tests/shapeRefIntegration.test.ts.

Sibling skills

• adding-operations — the six export surfaces + function-lookup.md gate a new create*/resolve* pair must pass through.
• kernel-abstraction — kernel-side evolution, *WithHistory methods, adapters, capability differences.
• wasm-interop — embind enum .value, Uint32Array conversion, and hash-code details underlying evolutionOps.ts.
• writing-tests — the kernel-divergence skip pattern for gating a new ref-kind test to occt-wasm.