solidcore is a port of NVIDIA's SMLib B-rep kernel (C++, Apache-2.0) to idiomatic safe
Rust. Upstream is cloned (gitignored) at upstream/, pinned to v1.0.1, commit 3fd5b95
(scripts/upstream-pin.env is the single source of truth for scripts, CI and the site). Many
agents work here at once: read this whole file before your first change.
crates/solidcore the kernel (pure Rust, no unsafe, wasm-ok) owner: unit porters
crates/solidcore-ffi extern "C" bindings to the C++ kernel (feature cpp)
crates/difftest side-by-side Rust vs C++ runner
harness/cpp C++ reference build (build.sh -> bin/cpp) + shim/<unit>.cpp
plan/ units/<id>.toml, findings/<slug>.md, upstream-issues/<slug>.md (one file each), STATUS.md, order.md
Licence. Read only upstream/source/SMLib, upstream/source/SM_API,
upstream/tests/SM_API_test, upstream/tests/prog_test, upstream/TestFiles/pt_TestFiles,
upstream/AGENTS.md, upstream/.agents/ (skip any file about OCCT or USD). Never open,
read or build OCCT_BREP_*, SM_API_USD, BREP_SM_USD, BREP_USD_DATA, HYDRA_USD_BREP,
USD_BREP_UTILS, schema, SmPyLib, SmPyDevLib or proposals/. Never read GPL/LGPL code
anywhere (including dependencies; deny.toml bans copyleft crates).
Library code (crates/solidcore).
- No
unsafe(#![forbid(unsafe_code)]). Onlysolidcore-ffimay use it. - No
unwrap/expect/panic!/todo!/unchecked[i]indexing (denied by lints; tests are exempt). Use.get(), iterators,?andSolidError. - Deterministic: no clock, no hashing of addresses, no
HashMapiteration order in results (useVec,BTreeMap, or sort), randomness only fromkernel.rng. - No global or
static mut/thread_localstate. Everything lives inKernel. - Must build for
wasm32-unknown-unknown: no threads, filesystem orstd::time. - Never allocate from an input-declared size unchecked (file headers, counts in data):
use checked arithmetic and call
DatabaseReader::ensure_available(count, min_bytes, op)before allocating, asBSplineSurface::read_from_dbdoes. Upstreammallocfails softly; Rust aborts. Never pre-reserve (Vec::with_capacity,vec![x; n]) from a count read out of a file: an in-memory item is often far larger than its minimum on-disk size. Grow the collection as items are actually read. - Polymorphic readers that can nest (
Curve::read_from_db, and the surface/topology dispatchers when ported) calldb.enter_nested(op)?before dispatching anddb.leave_nested()after, so crafted files cannot recurse without bound. - Recursion. wasm32 has no stack guard page: a stack overflow there silently
corrupts memory instead of aborting. Any recursion whose depth depends on input
(subdivision, refinement, tree/topology walks, nested geometry) carries an explicit
depth parameter or counter and returns
SolidErrorpast a documented bound that is well above anything upstream fixtures reach. Converting to a loop with an explicit stack is allowed only if it visits in exactly the same order. Note each bound in the file header's Deviations line.audit.recursion(last unit) sweeps the whole crate.
Correctness gate. A unit is green only when difftest runs the Rust and the C++
(via FFI) on the same inputs and topology is identical and every value agrees within
1e-9 relative (|a-b| <= 1e-9 * max(|a|,|b|); an absolute floor only where a unit
documents one per key in abs_floors(), recorded in its report). Never loosen a tolerance to get green. The harness never feeds C++ outputs or C++ process state into the Rust side (crates/difftest/README.md, No C++ state reaches the Rust side). A disagreement you cannot fix
goes in a new plan/findings/<slug>.md (unit, inputs, both values, suspected cause) and the unit
stays blocked. Sole exception: a case where the C++ reference is verified wrong (a confirmed
plan/upstream-issues/ entry) is listed with cpp_defect = "<id>" in its known-mismatch entry
and is parked: not run in the gate, not counted as a pass, and does not block green; removing
the marker runs it again (crates/difftest/README.md); never use it for a Rust divergence.
Git. Work happens through pull requests to github.com/tangency-labs/solidcore. Never
push to main directly, never force-push shared branches, never rewrite main's
history, never reset/checkout/restore files you did not write. Stage explicit
paths only (never git add -A/git add .). End every commit message with your
tool's attribution, e.g. for Claude Code:
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Processes. Kill only processes you started, by PID. Never pkill/pgrep -f.
Deleting. Delete directories and build output with cargo xtask rm <path>... (and
worktrees with cargo xtask worktree-rm <dir>), never rm -rf: agent harnesses hold rm -rf
for a human's approval even with permissions bypassed, which stalls unattended runs. The
xtask only deletes inside the worktree root, bin/, reports/ and the temp dir.
8 cores / 16 threads shared by every agent.
export CARGO_BUILD_JOBS=2 RUSTC_WRAPPER=sccache # sccache is installed in ~/.cargo/bin
nice -n 10 cargo test -p solidcore # every cargo/C++ command under nice- C++ reference:
scripts/fetch-cpp.shdownloads the prebuilt libraries for the current harness key (no compiling); it falls back tonice -n 10 harness/cpp/build.sh --jobs 6when no prebuilt matches. Only refetch/rebuild ifbin/cpp/libis missing or the harness changed; one sharedbin/cppserves all worktrees (below). WithRUSTC_WRAPPER=sccachethe shims solidcore-ffi compiles are cached by sccache too. - Run it from the main tree; worktrees reuse that build by exporting
SOLIDCORE_CPP_DIR=$HOME/github/solidcore/bin/cpp(the CMake build dir is keyed by source tree, so a worktree run gets its own build dir but installs to the samelib/). - Before claiming a unit, check load:
cut -d' ' -f1 /proc/loadavg. If > 24, do not claim; finish or wait. - After merging, delete your worktree's
bin/(each worktree has its own cargo target). - Unset
RUSTC_WRAPPERif sccache is missing; the repo never requires it.
Port faithfully, write idiomatically. Keep upstream numerics: same formulas, same
operation order, same iteration order, same branch structure for tolerance tests and
degenerate cases. Do not "simplify" a*b + c into mul_add, reorder sums, swap in
hypot/midpoint, or replace loops with library calls that change rounding. The C++
reference is built with -ffp-contract=off, so matching order gives matching bits.
Everything else is Rust-first:
- Data model. Topology lives in
topology::Breparenas addressed by typed ids (FaceId,EdgeId,VertexId,LoopId,ShellId,BrepId); no pointers,Rc, orRefCellgraphs. Geometry is concreteenums (Curve,Surface) over structs, not trait objects. Points/vectors aremath::Vec3(Point3is an alias, as upstream). - Kernel. Tolerances, RNG and caches are fields of
kernel::Kernel(upstreamSmContext). Take&Kernel(or&mut Kernelwhen using rng/caches); it must staySend. - APIs. Return values, not out-params (tuples or small structs for multiple
outputs). Fallible fns return
solidcore::Result<T>; buildSolidErrorwith theoperationpath (e.g."nurbs::knots::insert") and entity id. Many optional arguments become an options struct withDefault. UpstreamSmStatuscodes with no matching variant map toSolidError::Upstream { code, .. }. - Names. Drop
NL_/Sm/SM_/smgu_/Hungarian prefixes; snake_case fns, CamelCase types (SmBSplineCurve->BSplineCurve,NL_KnotInsert->knot_insert). - Organisation. A unit's
rust_module(nurbs::knots) lives atcrates/solidcore/src/nurbs/knots.rs, declared withpub mod knots;innurbs.rs(nomod.rs). Keepmodlines sorted, one per line, so parallel merges conflict cleanly. Unit tests go in the same file (#[cfg(test)] mod tests). - Docs. Every public item has a doc comment (
missing_docswarns; CI uses-D warnings). Lints are in rootCargo.toml[workspace.lints]; do not add#[allow]for denied lints in library code.
Every ported file starts with:
//! One-line summary of what the module does.
//!
//! Upstream: `source/SMLib/src/NL_KnotVec.cpp`, `source/SMLib/inc/NL_KnotVec.h`.
//!
//! | Rust | Upstream |
//! |-------------------------|----------------------------------|
//! | [`KnotVector`] | `NL_KNOTVECTOR` |
//! | [`KnotVector::insert`] | `NL_KnotInsert` |
//! | `find_span` (private) | `nl_FindSpan` |
//!
//! Deviations: <anything not 1:1, e.g. out-param -> return value, rand() -> kernel.rng>.
Unit list and states: plan/units/<unit id>.toml, one file per unit (format:
plan/modules.schema.md, order: plan/order.md). The checklist is generated
from main by the Pages workflow (harness/plan/progress.py; not committed). Any todo unit or unclaimed completion task can be claimed. A claim reserves
its stated scope, not every future change to the unit. Missing functions, back-edge
wiring, exact runner imports, fixtures and demonstrated parity bugs remain useful
work in partial and green units; inspect source and reports, not status alone.
A unit is ready when its depends_on are all
green or partial (soft_depends_on never blocks; see section 4a); ready units are
the easiest, lowest layer first. Claiming a unit that is not ready is fine:
- Calls into a missing dependency are stubbed (
UNPORTED(<unit>), cases deferred; 4a). - If you need a type (struct, enum variant, base class) from a missing dependency,
port the minimum of it yourself and record it in that unit's
notesinplan/units/<that unit>.tomlasCO-PORTED in <your unit> (PR #n): <C++ symbols> -> <Rust path>so its eventual porter extends your code instead of duplicating it. - If that dependency has an open
port:PR, do not port the same code twice: build on that PR's branch (merge it into yours) or agree on the split in that PR's comments.
One-time setup (per machine): clone this repo, clone upstream at the pinned commit
into upstream/ (see README), then run scripts/fetch-cpp.sh, or
nice -n 10 harness/cpp/build.sh --jobs 6 to build from source.
-
Claim = a scoped draft PR. Search open PR titles and bodies for the unit, symbols and affected paths, including
wire:,fix:anddifftest:work; a title search forport:alone misses completion work. Branch from the latestmain. Do not editplan/units/to claim. Initial whole-unit ports keep the titleport: <unit id>. For completion work, use a descriptive title such aswire: <unit id> — <function group>and name the unit in the body. An empty claim commit is sufficient to open a draft.Include this scope in the PR body (update it as the work changes):
Units: In scope: upstream symbols, Rust functions and intended behavior Expected edits: paths and shared interfaces Evidence: failing/deferred case IDs or missing branches; validation planned Related PRs / dependencies: Available follow-ups: independent work others can take Status / blockers / next step:For overlapping whole-unit
port:claims, the lowest-numbered open PR wins. For completion tasks, the earliest open claim wins only for overlapping work. Non-overlapping work in the same unit is welcome. Link the related PR and state the boundary before starting; independent work need not wait for a whole-unit owner to reply. If work changes the same function or shared interface, agree on a split in the existing PR first, or build on its branch and document the dependency. If the boundary is unclear, ask there and take a different independent task meanwhile. Never implement a competing version of an actively claimed change.Push WIP or post a concrete progress update at least daily while implementing. After 24 h without either, comment with the exact scope you propose to take over and allow 12 h for a response; then continue from published WIP, crediting its author. Do not take over a PR merely because it awaits review or CI: offer review, conflict resolution or a coordinated follow-up instead. A blocker update should identify what is blocked and release independent work, rather than reserve the whole unit indefinitely. When pausing, release the scope and link the WIP. Existing PR authors retain their active scope; this is not a reset of claims. If the unit's notes mention a WIP branch, inspect it before starting.
-
Port the upstream functions the unit owns (listed in
harness/callgraph/units.json) into itsrust_module, plus the C++ shim (harness/cpp/shim/<unit_id_with_underscores>.cpp, functionssc_<unit>_<fn>, plain C data only), itssolidcore-ffibinding, and its difftest runner and fixtures, followingcrates/difftest/README.md. Inputs: the unit's upstreamtests, plus fixed-seed generated and edge cases (degenerate, boundary, tolerance limits). -
Wire back-edges (section 4a): replace
UNPORTED(<unit id>)stubs elsewhere with real calls and re-run the difftest of every unit you touched. -
Verify (
export CARGO_BUILD_JOBS=2 RUSTC_WRAPPER=sccache, everything undernice -n 10):cargo fmt --all --check cargo clippy --workspace --all-targets -- -D warnings cargo test -p solidcore cargo check -p solidcore --target wasm32-unknown-unknown cargo run --profile difftest -p difftest --features cpp -- --unit <unit id> # and every unit you touched cargo run --profile difftest -p difftest --features cpp -- --green --jobs 4 # what CI runs (with --jobs 0)
--jobs Nruns N units at a time, each in its own process (0= every core; the output and reports are the same as a serial run). On a shared machine stay within the section 2 budget:--jobs 4at most, fewer when the load is high. CI also enforces the 75% value-share floor and exact-base artifact ratchet (crates/difftest/README.md, Regression gate). Missing/expired baseline artifacts fail closed; do not extract historical committed reports or waive lost coverage to make a run pass. Local--baselineruns must use matching seeds and no filter. -
Before you mark a PR ready, check each item. Earlier PRs passed CI yet still disagreed with the C++ because of these:
- Default arguments match upstream (e.g.
IsDegenerate()defaults toSM_EFF_ZERO, not a zone tolerance). - No parameter dropped or hard-coded (e.g.
0.0passed instead of the caller's value). - Every upstream special-case branch ported (e.g. cylinder reparametrisation for a line parallel to the axis).
- Statuses upstream relies on are honoured (e.g.
Unitize()turning a zero vector into(0,0,1)). - The shim builds every geometry kind the code branches on (real
SmEllipse/SmCircle/SmLine/..., not B-spline stand-ins), or those branches are never compared. - FFI guards reject exactly the inputs that are undefined or crash in C++: no more (valid inputs stay covered), no fewer (no garbage or segfaults).
- Generated cases cover degenerate, boundary, tolerance-limit, huge/tiny-scale and sub-domain inputs, and most cases compare real values, not just an error status.
- No panics on extreme caller input: bound derivative orders and counts; file readers bound header counts; input-driven recursion is bounded (section 1).
UNPORTEDstubs only for calls into units that are notgreen/partial, tagged with the owning unit fromharness/callgraph/units.json; co-ports are recorded asCO-PORTEDin that unit'splan/units/<id>.tomlnotes.
- Default arguments match upstream (e.g.
-
Finish the PR: merge the latest
origin/maininto your branch (never rebase a pushed branch), re-verify, set the unit'sstatusto"green"or"partial"inplan/units/<unit id>.tomlwith case/deferred counts innotes(plus the files of any units you promoted), commit, push, and mark the PR ready. Put the difftest summary lines in the PR description. CI runs fmt, clippy, tests, wasm, difftest on every green or partial unit, and the difftest runner tests. CI is the merge gate. Once CI is green, a maintainer adds the PR to the merge queue after a quick check (stub tags, no loosened tolerance, no case dropped), and the queue re-runs CI on the PR merged with the latestmain. Deep adversarial review happens after merge; anything it finds comes back as a follow-up issue or PR, so keep the step-5 checklist honest.
Shared files (avoid merge conflicts). Every open PR touches the same plan, so:
- Edit only
plan/units/<id>.tomlof your unit (and of units you promote or co-port into). There is no sharedplan/modules.tomlany more. - Never commit
reports/difftest/(gitignored). difftest still writes your reports there locally; CI regenerates them, uploads main's set as thedifftest-reportsartifact, and the site and its checklist read that (scripts/fetch-reports.shdownloads it). Quote your summary lines in the PR instead. - Never append to a shared file. Every finding and every upstream issue is its own
new file:
plan/findings/<slug>.mdandplan/upstream-issues/<slug>.md(formats in each directory'sREADME.md). Records are never edited after they merge (like ADRs): an update is an addendum file. The old sharedplan/findings.mdandplan/upstream-issues.mdwere split into those directories; CI fails if either comes back. Two PRs that each add a file never conflict. Known difftest mismatches likewise live incrates/difftest/known_mismatches/<unit id>.toml(one file per unit; seecrates/difftest/src/known.rs), and SolidCraft cases infixtures/solidcraft/<issue>-<slug>.json(one file per issue). The same goes for anything new you design: a registry or log is a directory of per-entry files that tools read in sorted order, never one file everybody appends to. - Branches from before the per-unit split (they edit
plan/modules.tomlor commit reports): merge main, then run the migration, which moves yourmodules.tomledits intoplan/units/*.tomland untracks your reports:It reports agit fetch origin && git merge origin/main; scripts/units-migrate-branch.sh && git commit --no-edit
CONFLICTfor a field main also changed (it keeps yours; check it) and lists any other conflicted files for you to resolve before committing.
Blocked (gate cannot be met, upstream behaviour unclear): record details in
plan/findings/<slug>.md, set status = "blocked" with a reason in notes, and open the PR
with just that so others can see it. Never sit on a draft PR you have stopped working
on: close it, and say where the WIP is.
For new ports and completion changes, include the completion evidence checklist
in the PR description. The evidence table is required for wire: PRs that remove
UNPORTED stubs, including when existing fixtures do not reach the continuation. Identify the owned functions and branches implemented, which
operations actually complete successfully against C++, and which remain unreachable.
A passing status or empty result is evidence for that case, not proof that the
operation's successful construction or mutation path works.
A dependency stub replaces the missing call only. Port the upstream logic following it as well, preserving control flow and operation order; do not omit the continuation and present the function as complete. If an incremental PR deliberately leaves an owned body or continuation missing, list the exact symbols and remaining work. Report that limitation even if existing fixtures never reach it. Unit status follows the existing gate; it does not certify complete function or branch coverage.
When a dependency is wired, rerun the affected callers and add cases that reach the previously blocked continuations. Keep newly exposed mismatches visible. Review runner skips, stand-in geometry and absent-entity cases before claiming coverage. Record independent harness follow-ups with reproducible evidence and check existing PRs before implementing them. This checklist supplements the existing correctness gate; it does not change tolerances, outcomes or status accounting.
The kernel core is one big call cycle, so the plan dropped ~2,300 calls as back-edges
(listed in each unit's notes: cycle back-edges (...): <unit>(<calls>)). Rules:
- Soft dependencies.
soft_depends_onlists dependencies a unit calls at most twice and needs no type from (generated byharness/plan/soften.pyfrom the call graph). They do not block claiming: treat every call into a soft dependency that is notgreen/partialyet exactly like a back-edge below. Onlydepends_onblocks. - Calling unported code. A call into a unit that is not
green/partialyet goes throughErr(SolidError::Unported { upstream: "<C++ symbol>", unit: "<unit id>" }). Never panic, never fake a result. Every such site carries the comment// UNPORTED(<unit id>): <C++ symbol>so the target's porter can find it with grep. - Difftest with back-edges. Cases whose C++ path reaches an unported callee are
classified
deferred(the Rust side returnsUnported); they are neither pass nor fail. A unit with all non-deferred cases passing and >=1 deferred case ispartial. With zero deferred cases it isgreen.partialsatisfiesdepends_onfor scheduling only; it is never reported as green. - Wiring back-edges when you port a unit. After your unit passes, grep
UNPORTED(<your unit id>)acrosscrates/solidcore, replace each stub with the real call, and re-run difftest for every unit you touched. Any unit whose deferred count drops to 0 and passes becomesgreen; record this in the same commit. - Local swarms only: when several agents share one clone, everything that writes
that clone's
mainruns underflock .git/swarm.lock -c '<commands>'.
Every unit is ported; most new work fixes SMLib defects in the port. The long-term policy is still open in #1018. Until it is settled, the interim rule is the one in that thread:
- Default = the C++ reference. Default behaviour matches the pinned C++ (usd-brep v1.0.1 since #1277), and difftest keeps gating it at parity.
- Result-changing fixes are opt-in. A fix that changes a result is a
Kernel::fixes(UpstreamFixes) field, off by default, with a regression test of the issue's case and an addendum inplan/upstream-issues/naming the field. Examples: #1233, #1285, #1287. - Crash, UB, hang and nondeterminism fixes are unconditional, e.g. #1160 for UB-87.
- Check that the issue is still open work before you claim it. Many issues were
fixed by a PR that did not close them (see #1206). Search merged PRs for the issue
number, the upstream symbol and the
WR-/UB-/HANG-record id, and grepplan/upstream-issues/and theUpstreamFixesdocs. Issues about fork-only features that are not in SMLib or SM_API at the pin (e.g. the screw sweep, #1162/#1163) are out of scope. - A fixing PR uses a closing keyword (
Fixes #n) so the issue closes when it merges.
plan/units/<id>.toml: one unit's plan entry (status, claims, notes). Edit only your unit's file. Every tool reads them throughharness/plan/units.py(Rust:crates/difftest/src/plan.rs).plan/findings/<slug>.md, one file per finding: Rust-vs-C++ disagreements, upstream bugs, nondeterminism (e.g. upstreamsrand(time(NULL))), anything a later agent must know. A reference toplan/findings.md: <heading>(older code comments): grep the heading underplan/findings/.plan/upstream-issues/<slug>.md, one file per issue: upstream C++ defects (problems only, with location, trigger, how found and whether the C++ build confirmed it). The site reads them all. Aplan/upstream-issues.mdID: grep it under that directory.reports/difftest/<unit>.json: difftest output. Not committed: CI uploads main's set as an artifact;scripts/fetch-reports.shdownloads it.- Checklist: generated on the site
by
harness/plan/progress.py(local runs write the gitignoredplan/PROGRESS.md). plan/STATUS.md: overall progress summary and handoff notes.bin/: all build output (cargotarget-dir,bin/cpp/for C++). Gitignored. Never commit build output or anything underupstream/.