c454a3af10
* feat(skill): replace skill-pack with per-harness conditional compiler
skillbuild compiles the skill tree into per-target harness builds:
- <!-- skill:if omp,!claude --> blocks include text only for matching
targets; name-list conditions only, no else/nesting, fail-loud on
unknown targets and unpaired/nested directives
- fence-aware: directive-looking lines inside code fences are literal
- layout is the filesystem; tree root configured in skillproj.toml
- post-build assertion: zero directive residue, SKILL.md frontmatter
name check
Migration to the new model:
- docs/skill/ becomes the self-contained source root (SKILL.md,
references/, generated api/stdlib/core/guides now under
references/docs/; SDK_OVERVIEW/LICENSE/inspect are ordinary tree
files)
- auto_docs_gen output redirected into the tree (docs/api ->
docs/skill/references/docs/api, likewise stdlib)
- skills/simplecadapi/ is now the compiled omp target output;
dist/generic/simplecadapi the generic target
- dropped skill-pack entry point (plus dangling evolve/make-export
entries and their orphaned test), release workflow builds via
skillbuild + tar; README updated
First real conditional block: harness reading paths in SKILL.md
(skill:// mount on omp vs disk-relative on generic).
Verified: 59 tests pass (skillbuild 31, auto_docs_gen 19, persistence
regression 9); both targets build; outputs residue-clean; full suite
collects (1376 tests).
* refactor(tools): auto_docs_gen moves out of the installed package
tools/ scripts are repo-checkout dev scripts, not packaged CLIs:
- auto_docs_gen.py now lives in tools/ beside the other generators;
auto_tools/ package removed entirely
- path resolution simplifies: repo root = parent of tools/, fail-loud
if pyproject.toml missing; site-packages/cwd fallback branches were
dead code once the script stopped shipping in the wheel
- auto-docs-gen console script dropped from [project.scripts];
release.yml and README invoke python tools/auto_docs_gen.py
- MANIFEST.in stale src/auto_tools include removed; CadQuery-free
runtime scan no longer needs the auto_tools filter
- run_examples.py retired (user removal): README example-runner text
updated to direct examples/ scripts; dangling runner-contract test
(runpy.run_path into the deleted script) removed
Verified: 53 tests pass (auto_docs_gen + skill_build + ocp runtime
scan) and test_example_model_contract passes; regeneration from
tools/ is byte-identical (zero docs drift).
* refactor(skill): strip harness and build-tool content from the skill tree
The skill is plain harness-neutral content again:
- SKILL.md 'Reading skill files' section removed (the omp skill://
mount block and its !omp complement were the only conditional
blocks; the tree compiles identically for every target now)
- references/README.md: build-tool meta removed ('per-harness
conditional compilation', skillbuild packaging/validation claims —
link validation was never implemented, so the claim was false)
- live test now asserts the tree stays harness-neutral (zero blocks)
- skillproj.toml targets aligned with the user's output table
(omp -> skills/simplecadapi-omp, opencode -> skills/simplecadapi-opencode;
leftover 'generic' entry had no output and failed the build)
- compiled outputs are regenerable artifacts: skills/simplecadapi/
untracked from git, skills/simplecadapi-*/ gitignored, release.yml
and README build via skillbuild and tar the omp output directly
(bsdtar has no --transform; inner dir keeps its suffixed name)
Verified: 49 tests pass; both targets build 372 files with zero
conditional blocks; no omp/conditional/directive residue in the tree
or outputs.
* chore(docs): drop stale architecture review and design notes
130 lines
6.4 KiB
Markdown
130 lines
6.4 KiB
Markdown
# SimpleCADAPI 2.0.4b3 Update Notes
|
|
|
|
[Chinese](2.0.4b3.zh-CN.md)
|
|
|
|
> **Beta release notice:** Validate generated definitions, assembly constraints,
|
|
> and manufacturing geometry before production use.
|
|
|
|
SimpleCADAPI 2.0.4b3 adds reproducible product build boundaries and a persistent,
|
|
crash-safe cache spanning whole parts and incremental assembly solves.
|
|
|
|
## 1. Durable part and assembly definitions
|
|
|
|
`@scad.part` builds exactly one physical single-solid part and returns a
|
|
`PartBuildResult`: runtime `Part`, `PartDefinition`, graph/session state, model
|
|
and session JSON, interface differences, and a per-build `CacheReport`. Its
|
|
content-derived key covers normalized arguments, builder source, declared file
|
|
inputs, revision, tolerance profile, and generator/ABI profile.
|
|
|
|
`@scad.assemble` requires explicit external `PartDefinition` or nested
|
|
`AssemblyDefinition` inputs. Repeated instances share immutable definitions;
|
|
closed validation rejects missing, unused, cyclic, conflicting, or incompatible
|
|
references. Definitions round-trip independently from process-local runtime
|
|
objects.
|
|
|
|
## 2. Incremental assembly solve
|
|
|
|
Assembly state records component dependencies and public connector interfaces.
|
|
Changes to geometry, connectors, connector bindings, material, or a nested
|
|
assembly's public connector declaration propagate only through affected dependency paths.
|
|
Unchanged component placements can be restored from cache, but every restored
|
|
placement still passes constraint-residual verification before it is accepted.
|
|
|
|
## 3. PRT reuse
|
|
|
|
In `read_only` and `read_write` modes, calls to the same decorated `@scad.part`
|
|
builder and build key reuse one runtime PRT with zero cache I/O. Concurrent
|
|
same-key calls share one build. `off` and `refresh` preserve their explicit
|
|
rebuild semantics.
|
|
|
|
Durable whole-part bundles remain the cross-run boundary. A newly decorated
|
|
builder or later process restores an unchanged PRT from its validated bundle and
|
|
creates fresh runtime graph provenance. Corrupt records or objects degrade to
|
|
misses and are quarantined before recomputation.
|
|
|
|
## 4. Crash-safe content store and policy
|
|
|
|
The shared CAS uses canonical closed records, SHA-256 objects, atomic writes,
|
|
per-key locks, stale-lock recovery, and object deduplication.
|
|
|
|
One `CachePolicy` controls part and assembly caching. Precedence is explicit API
|
|
argument, environment, `[tool.simplecadapi.cache]`, then defaults. The supported
|
|
modes are `off`, `read_only`, `read_write`, and `refresh`.
|
|
|
|
## 5. Cache diagnostics CLI
|
|
|
|
The new `simplecad-cache` command emits stable JSON:
|
|
|
|
```text
|
|
simplecad-cache status [--namespace NAME]
|
|
simplecad-cache verify [--namespace NAME] [--repair]
|
|
simplecad-cache prune [--apply]
|
|
simplecad-cache clear [--namespace NAME] --yes
|
|
```
|
|
|
|
Inspection and default prune are read-only. Explicit `--repair`, `--apply`, or
|
|
`--yes` is required to mutate state. `verify` always validates record identity,
|
|
object presence, byte length, and SHA-256. Namespace clearing preserves objects
|
|
still referenced elsewhere.
|
|
|
|
## 6. Product-package CAD translation
|
|
|
|
Validated `.scadpkg` definition closures now translate to one editable FreeCAD
|
|
document or one XCAF-backed AP242 STEP file. FreeCAD output uses a
|
|
dependency-first definition registry so repeated parts, nested assemblies,
|
|
occurrence names, solved placements, materials, connectors, constraints,
|
|
grounding, revision, and content hashes survive in native document structure.
|
|
|
|
AP242 output uses `AP242_MANAGED_MODEL_BASED_3D_ENGINEERING`, preserves evaluated
|
|
BREP and product occurrences, and writes materials, colors, density, plus named
|
|
definition/occurrence properties. The property descriptions contain canonical
|
|
sorted JSON for durable IDs and semantics. Feature history is not reconstructed
|
|
as AP242 features; `.scadpkg` remains the canonical replayable artifact.
|
|
|
|
Product mesh export now shares one direct OpenCASCADE tessellation of evaluated
|
|
BREP solids. OBJ and binary STL contain the same oriented triangles; OBJ keeps
|
|
shared vertex indices while STL stores independent facets. The public accuracy
|
|
controls are `linear_deflection`, `angular_deflection_degrees`, and `relative`.
|
|
No remeshing dependency or Python 3.11 version gate is involved, so mesh export
|
|
works across the package's complete supported Python range.
|
|
|
|
The scripts in `examples/12_ap242_gmsh_volume_mesh/` build one `.scadpkg` and
|
|
demonstrate every package exporter and translator as independent downstream
|
|
commands: AP242 STEP, STL, OBJ, FCStd, FreeCAD, Fusion 360, and SolidWorks.
|
|
The optional Gmsh stage continues from AP242 STEP to a tetrahedral `.msh`
|
|
without adding Gmsh to the core runtime dependency set.
|
|
|
|
## 7. Native render crash isolation
|
|
|
|
On macOS, VTK 9.5's Cocoa offscreen backend can terminate the interpreter with
|
|
`SIGSEGV` after repeated or concurrent render-window use. Inspection and SDK
|
|
screenshot calls now tessellate in the caller, then render through one-shot VTK
|
|
workers guarded by a cross-process lock. Completion markers distinguish a
|
|
finished image from a partial native crash; incomplete workers retry, while a
|
|
post-write teardown crash cannot terminate the modeling or test process.
|
|
|
|
## 8. Verification
|
|
|
|
|
|
Regression coverage exercises artifact schema closure, deterministic IDs and
|
|
hashes, atomic concurrent write deduplication, corruption quarantine, all cache
|
|
modes, in-process same-key PRT reuse, concurrent PRT build deduplication,
|
|
cross-wrapper persistent part restore, interface invalidation, assembly
|
|
definition DAGs, incremental dependency propagation, residual verification,
|
|
nested connector changes, translator backend contracts, and generated API docs.
|
|
|
|
The nested package smoke writes and reads a native FreeCAD hierarchy with shared
|
|
definitions and solved placements. AP242 round-trip checks the managed-model
|
|
schema, five-level product explorer records, material and color data, plus seven
|
|
named metadata property items for three definitions and four occurrences. The
|
|
Gmsh smoke imports AP242 as one 3D volume and generates a non-empty tetrahedral
|
|
mesh.
|
|
|
|
## Related documentation
|
|
|
|
- [Persistent cache and product build workflow](../skill/references/docs/guides/cache-build-workflow.md)
|
|
- [Product package STEP/STL export APIs](../skill/references/docs/api/export_product_package_to_step.md)
|
|
- [Editable FreeCAD product package API](../skill/references/docs/api/translate_product_package_to_fcstd.md)
|
|
- [Modeling workflows](../../skills/simplecadapi/references/MODELING_WORKFLOWS.md)
|
|
- [Previous 2.0.4b2 update notes](2.0.4b2.md)
|