Files
make-cad/docs/updates/2.1.3b1.md
T
NiJingzhe e9d5749f7c fix(windows): unblock builds — binary opens, guarded dir fsync, evidence-based stale locks
Reported by the OmniSim evaluation of the public u-link example
(2026-09-11): pip install + export.py on Windows died three times in
the build layer before any geometry was built.

- Binary-mode opens: every byte-exact os.open site now sets O_BINARY
  via _internal/os_compat.with_binary_flag. autocrlf=true clones read
  builder sources in text mode, stripped CR, and aborted with a false
  file_input_changed (25579-byte u_link.py read back as 25092); the
  same hazard expanded LF on cache writes and would corrupt CAS
  hashes. Sites: build/dependencies.py, artifacts/feature_graph.py,
  scene/archive.py, cache/store.py (object/record writes, lock
  create), artifacts/interface.py (lock create).
- Directory fsync is POSIX-only: os.open(<dir>)+fsync raised
  PermissionError on Windows in cache/store.py and
  artifacts/interface.py; both now no-op off POSIX via one helper.
- Stale-lock recovery by evidence: a lock whose recorded owner pid is
  provably dead is recovered immediately (unreadable owners still wait
  out the age gate, live owners are never broken). Windows liveness
  probing uses OpenProcess/GetExitCodeProcess — os.kill(pid, 0) maps
  to TerminateProcess there and kills the process being probed.
- Console hardening at import: non-UTF strict streams are reconfigured
  to backslashreplace so a cp1252 console cannot raise
  UnicodeEncodeError from a diagnostic print inside an error handler
  and mask the real failure.
- .gitattributes: byte-exact by default, LF pinned for text formats,
  so builder-source digests stop depending on core.autocrlf.

Tests: test_os_compat.py (15) + dead-owner immediate recovery in
test_cache_store.py; full suite 1799 passed, 5 skipped. ty: zero new
diagnostics.
2026-09-11 20:55:14 +08:00

6.3 KiB

2.1.3b1 Update Notes

Release notice: Pre-release (beta). Validate generated definitions, assembly constraints, and manufacturing geometry before production use.

Addon ecosystem: sca addon manager CLI

A new sca console script installs third-party addon packages — skill + tooling repositories that add non-modeling capabilities (simulation, analysis, downstream tooling) by consuming .scadpkg products:

sca addon init                     # once per machine: home + registry + config
sca addon add owner/repo@v1.2.0    # install from GitHub (tag/commit pin)
sca addon add ./my-addon           # install a local checkout (pre-publish test)
sca addon update [name]            # re-fetch one addon or all
sca addon remove name
sca addon list                     # registry contents + on-disk drift
  • Descriptor sca-addon.toml (repository root) with strict validation — unknown tables and keys are rejected and every failure names the field: addon identity, [compat] sca version range (range-not-pin: comma-separated == != >= <= > < clauses, pre-release suffixes sort before their release, missing trailing components pad with zero, contradictory clauses are rejected), a closed six-value platform enum (macos-arm64, macos-x86_64, linux-x86_64, linux-aarch64, windows-x86_64, windows-arm64), and a check_cmd runtime probe (exit 0 means usable, shell pinned to sh -c / cmd /c, about two seconds, no network/license/GUI; a failing probe warns loudly but never blocks the install).
  • Hard gates vs warnings: an invalid descriptor, [compat] sca mismatch, unsupported platform, name collision, or a foreign skill directory aborts the install naming the exact cause; a failing probe or a version downgrade on update is a loud warning.
  • Install layout: addon home plus ~/.sca/config.toml resolution chain (flag > SCA_ADDON_HOME/SCA_SKILLS_DIR env > config > defaults ~/.sca/addons and ~/.agents/skills; the CLI never writes shell profiles), a registry.json recording what was installed where, skills copied (never symlinked) as sca-<name>, GitHub sources fetched as tarballs by default (no git binary needed; --method clone for private repositories) with symlink/traversal guards on extraction.

The contract after review: the recommended default is the language-agnostic process boundary (addons consume .scadpkg files and process tooling; dependency conflicts are structurally impossible); in-process SDK use inside the addon's own environment is explicitly allowed — the builtin exporters and the package readers (read_product_package, load_product_package) exist for exactly this kind of downstream consumer, with [compat] sca governing which SDK releases that dependency may resolve to. In both modes the addon is not installed into the environment that models the geometry.

.scadpkg consumer format spec

docs/skill/references/scadpkg-format.md documents the durable package format for consumers: member layout (package.json manifest, definitions, occurrence graph, scene projection, content-addressed blobs/), the sha256 resolution rule (reference path is a logical name — resolve through the manifest by sha256), the interface.* tag channel (name_index maps a public name to same-kind entities; a missing required name is a loud failure, never a geometric guess), and two minimal readers — in-process SDK and pure ZIP+JSON for any language. Both code samples are executed against a real package. The addon authoring guide (references/domains/addon-development.md, routed from the skill) points exporters at it; the normative JSON Schemas ship inside the wheel at simplecadapi/contracts/.

Windows build and cache correctness

Reported by the OmniSim evaluation of the public u-link example (2026-09-11): installing the SDK on Windows and running examples/u_link_motor_mount/export.py hit three build-layer blockers before any geometry was built. All three are fixed, plus two latent hazards found alongside:

  • Binary-mode opens. Every byte-exact os.open site now sets O_BINARY through one helper (_internal/os_compat.py). A Windows clone made with core.autocrlf=true used to read builder sources in text mode, strip every CR, and abort with a false file_input_changed before the first feature (measured: a 25579-byte u_link.py read back as 25092). The same text-mode hazard silently expanded LF on cache writes, which would corrupt CAS object hashes. Covered sites: builder source reads (build/dependencies.py, artifacts/feature_graph.py), scene archive member reads (scene/archive.py), and every cache write/lock create (cache/store.py, artifacts/interface.py).
  • Directory fsync is POSIX-only. os.open(<dir>) + fsync raised PermissionError on Windows in two places (cache store, latest-part state), and the first failure stranded a lock file that made every retry time out. Directory fsync is now a guarded no-op off POSIX.
  • Stale-lock recovery by evidence. A lock whose recorded owner pid is provably dead is recovered immediately; unreadable owners still wait out the age threshold and live owners are never broken. The Windows liveness probe uses OpenProcess/GetExitCodeProcess — os.kill(pid, 0) maps to TerminateProcess there and would kill the very process being probed.
  • Console diagnostics cannot mask failures. Importing the SDK now reconfigures non-UTF strict streams to backslashreplace: a cp1252 console used to raise UnicodeEncodeError from a Chinese-language warning printed inside an error handler, replacing the real failure with an unrelated "wire is open" fault.
  • A root-cause .gitattributes ships with the fix — byte-exact by default, LF pinned for text formats — so every platform checks out identical bytes and builder-source digests stop depending on core.autocrlf.

Housekeeping

  • Removed the dead product-package-2.schema.json contract: the loader only ever validated against product-package-3.schema.json, and no code or tooling read the v2 file.

Compatibility notes

  • The new sca console script is additive; no SDK API changed in this release.
  • The v2 schema file's removal only affects the wheel's static payload; packages produced by current SDK versions (schema 3.0) are unaffected.