pysrc=upstream: docs (CLAUDE.md flag bullet, upstream-py README), sweep results

Broad-sample scoreboard folded into INVENTORY.md: 10/19 example ids MATCH
lite exactly (boxes_on_faces joins), tea_cup end-to-end at ~0.3% sweep
delta, two new open S-items (Edge.make_tangent_arc, make_text kwargs),
clock/joints/key_cap_algebra exceeded the sweep's per-script budget.
Clean rebuild + gate: python-mode, py-runtime, py-src-upstream all green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: zalo

CLAUDE.md

@@ -223,6 +223,20 @@ see `test/b123d-validation/runtime-comparison.md`)**:
   `_list_getitem`/`_property_getter`/`_bit_length` helpers, setattr loops
   instead of `__dict__.update`, and the scipy shim only sets `__path__ = []`
   when missing (MicroPython needs its native STRING `__path__`).
+- **`?pyruntime=micropython&pysrc=upstream`** (experimental PoC, localStorage
+  `cascade-py-src`) additionally swaps the SOURCE layer: the `build123d`
+  package becomes UPSTREAM build123d 0.11.1 Level-A source (builders,
+  build_common, objects_*, operations_*, joints, pack — vendored via
+  `node packages/cascade-core/scripts/fetch-upstream-b123d.cjs`, gitignored
+  `vendor/build123d-0.11.1/`, transformed at load by
+  `packages/cascade-core/src/worker/UpstreamB123d.js`) running over lite's
+  classes re-exported as `build123d.geometry`/`build123d.topology[.*]`
+  (adapters in `packages/cascade-core/upstream-py/`); lite registers as
+  `build123d_lite`. Requires MicroPython; other runtimes reject the flag
+  loudly. Frozen by `test/py-src-upstream.spec.js` (skips when not
+  vendored). The seam-gap ledger + integration-cost estimate live in
+  `experiments/upstream-on-micropython/INVENTORY.md`; compare against lite
+  with `experiments/upstream-on-micropython/compare-examples.mjs`.
 
 **build123d-lite coverage** (vs real build123d 0.11.1 — validated by running
 EVERY runnable script in the upstream `examples/` and `docs/` trees through both,

experiments/upstream-on-micropython/INVENTORY.md

@@ -65,6 +65,8 @@ capability differently — usually as a module-level builder-aware function)
 | B16 | `BoundBox.to_align_offset`, `BoundBox.add` | absent | adapter (ported from upstream geometry) | S |
 | B17 | `LocationList.__mul__/__rmul__` algebra products (`GridLocations(...) * shape`) — upstream's own topology provides this via `Shape.__rmul__` over Location iterables | lite's LocationList has them, but upstream's build_common LocationList (now in charge) didn't | adapter patches upstream's class post-import | S |
 | B18 | `Compound.get_type` see A5 | | | |
+| B19 | `Edge.make_tangent_arc` (canadian_flag) | lite `TangentArc` object | adapter classmethod (not yet written) | open, S |
+| B20 | `Compound.make_text(single_line_width=, ...)` — upstream Text passes kwargs lite's text seam lacks (examples/extrude) | lite `Text`/`make_text` (narrower signature) | open (needs a kwargs audit of the text seam) | open, S–M |
 
 ## C. Enum identity across the seam
 
@@ -127,11 +129,16 @@ Upstream EXAMPLE scripts, lite-vs-upstream measurement diff
 (`compare-examples.mjs`; MATCH = every module variable within 0.5% volume):
 `holes`, `holes_algebra`, `intersecting_chamfers`, `circuit_board`,
 `din_rail`, `lego`, `handle` (multisection sweep!), `loft`, `key_cap`
-(extrude until=NEXT/LAST + taper) all **MATCH**. `tea_cup` runs end-to-end
-but the swept handle differs ~0.3% (upstream path chains `Wire(edges)` where
-lite sweeps its recorded pending path — same MakePipeShell numeric family as
-COMPROMISE(sweep)). Heavy text/Airfoil examples stay out of reach
-(numpy/glyph parity, same as lite's own gaps).
+(extrude until=NEXT/LAST + taper) and `boxes_on_faces` (workplanes on faces)
+all **MATCH** — 10 of the ~19 example ids attempted. `tea_cup` runs
+end-to-end but the swept handle differs ~0.3% (upstream path chains
+`Wire(edges)` where lite sweeps its recorded pending path — same
+MakePipeShell numeric family as COMPROMISE(sweep)). Remaining errors in the
+sample: B19/B20 above (`make_tangent_arc`, text kwargs), and
+`clock`/`joints`/`key_cap_algebra` produced no measurement inside the
+sweep's 120 s per-script budget (uninvestigated — clock is slow in lite
+too). Heavy text/Airfoil examples stay out of reach (numpy/glyph parity,
+same family as lite's own gaps).
 
 ## G. Judgment: cost of the full Level-A integration
 
@@ -149,6 +156,6 @@ themselves demonstrably run verbatim).
 
 Boot cost: the upstream layer adds ~180 ms to MicroPython's boot
 (lite 123 ms → upstream 305 ms libMs in-browser) and ~300 KB of fetched
-Python source (uncompressed; the vendored Level-A files total ~250 KB).
+Python source (uncompressed; the vendored Level-A files total ~340 KB, the committed shims + adapters ~60 KB).
 Model-evaluation speed is indistinguishable in these examples (time lives in
 OCCT, not the interpreter).

packages/cascade-core/upstream-py/README.md

@@ -0,0 +1,33 @@
+# upstream-py — the `?pysrc=upstream` source layer
+
+Python sources for the experimental **upstream-build123d-on-MicroPython**
+mode (`?pyruntime=micropython&pysrc=upstream`): UPSTREAM build123d 0.11.1
+Level-A source runs verbatim (after mechanical transforms) on the MicroPython
+runtime, over build123d-lite's classes re-exported as upstream's
+`build123d.geometry` / `build123d.topology[.*]` seam.
+
+- `shims/` — stdlib shims MicroPython lacks (typing, metaclass-free enum,
+  contextvars, inspect-over-settrace, ...). Registered via `sys.modules`
+  aliasing (MicroPython builtins shadow `/lib`).
+- `build123d/` — the seam adapter package: `geometry.py` and
+  `topology/__init__.py` re-export lite's classes under upstream's names and
+  install the (additive, upstream-boot-only) patches lite needs to serve
+  upstream's call surface; `_finalize.py` populates the package namespace and
+  the worker's reset hook. Every adaptation is catalogued in
+  `experiments/upstream-on-micropython/INVENTORY.md`.
+- `ocp_import_map.json` — the OCP names build123d imports, used to generate
+  inert OCP stubs (`OCP.Standard`/`OCP.StdFail` become real Exception
+  subclasses; `OCP.GccEnt` values ints).
+- `manifest.json` — shim registration order.
+
+The UPSTREAM sources themselves are NOT committed: run
+`node packages/cascade-core/scripts/fetch-upstream-b123d.cjs` (gitignored
+`vendor/build123d-0.11.1/`), then `npm run build` copies everything to
+`dist/upstream-b123d/`. Loader + source transforms:
+`packages/cascade-core/src/worker/UpstreamB123d.js`. Frozen contract:
+`test/py-src-upstream.spec.js` (skips when not vendored).
+
+Iterate in node (no build, semantic mock of the CAD library):
+`node experiments/upstream-on-micropython/upstream-poc.mjs [script.py]`.
+Diff real examples against lite in the browser:
+`CS_TEST_HEADFUL=1 DISPLAY=:99 node experiments/upstream-on-micropython/compare-examples.mjs examples/lego ...`