sandboxedjs 0.2.11 → 0.2.13

package/dist/python/runtime.json

@@ -18,9 +18,9 @@
   "artifacts": {
     "moduleUrl": "./python.js",
     "hashes": {
-      "python.js": "sha256-ba225e5b4900449d493f213dc67263ed1afa7497f36582c43d778ccc282fe749",
-      "python.wasm": "sha256-a971913c97e671ec281c92c2922e0c64b3e2c9565c58a466a9dda78df5bb8e7a",
-      "python.data": "sha256-98d1fd943b6530e6ac7dd816420efe81082510da14c49bdc06fa60f5b08b924e",
+      "python.js": "sha256-2077b7c944097fa32fd80ffdd2575d5877a75bea77a0083f3dce93e7d2ab2976",
+      "python.wasm": "sha256-03f5cb9889a26d5f0b5a3e9d7310e2c5d9f2e8d1c4f9673b061ee19fcbe759c1",
+      "python.data": "sha256-c6e6bcf4afd43d12b50c6a0d013d400868434bbfd37341d4642ea40ad69cacd3",
       "python.worker.js": "sha256-63bb1df52c4e3a95eae7b2d77c98554188fcc5925e72628ea0c34d5c573977a5"
     }
   },

package/dist/python-worker.js

@@ -802,6 +802,7 @@ async function runPythonProcess(start, port) {
   )).default;
   let exitCode = 0;
   let guestMemory;
+  let threadBridgeName;
   const guestHeap = () => {
     const exported = config.HEAPU8;
     if (exported && exported.byteLength > 0) return exported;
@@ -886,6 +887,7 @@ async function runPythonProcess(start, port) {
           if (!guestMemory && result.instance.exports.memory instanceof WebAssembly.Memory) {
             guestMemory = result.instance.exports.memory;
           }
+          threadBridgeName = result.instance.exports.sbx_thread_bridge_name;
           receiveInstance(result.instance, result.module);
         } catch (error) {
           config.onAbort?.(error);
@@ -903,6 +905,13 @@ async function runPythonProcess(start, port) {
       mountContainer(config.FS, client, start.mounts, config.ERRNO_CODES ?? {});
       bindStdio(config.FS, client, start.isTty);
       for (const [key, value] of Object.entries(start.env)) config.ENV[key] = value;
+      if (start.threadChannel && typeof threadBridgeName === "function") {
+        const bytes = new TextEncoder().encode(start.threadChannel + "\0");
+        if (bytes.length > 128) throw new Error("Python thread channel name is too long");
+        guestHeap().set(bytes, threadBridgeName());
+        port.postMessage({ type: "thread-memory", memory: guestMemory });
+        config.ENV.SBX_THREAD_HOST_CALLS = "1";
+      }
       try {
         config.FS.chdir(start.cwd);
       } catch {

package/dist/service-worker.js

@@ -530,7 +530,8 @@ var PreviewRouter = class {
       this.options.onStale?.(clientId);
     }
     const headers = new Headers(result.headers);
-    const body = this.options.injectSockets === false ? result.body : withSockets(result.body, headers);
+    const bodyless = request.method === "HEAD" || [204, 205, 304].includes(result.status);
+    const body = bodyless ? null : this.options.injectSockets === false ? result.body : withSockets(result.body, headers);
     headers.set("Cross-Origin-Resource-Policy", "cross-origin");
     headers.set("Cross-Origin-Embedder-Policy", "require-corp");
     return new Response(body, { status: result.status, statusText: result.statusText, headers });
@@ -656,7 +657,7 @@ worker.addEventListener("fetch", (event) => {
   const claimed = router.claimedPort(url.pathname);
   if (claimed !== null && event.request.mode === "navigate") {
     router.bind(event.resultingClientId || event.clientId, claimed);
-    event.respondWith(router.fetch(claimed, "/", event.request, event.resultingClientId || event.clientId));
+    event.respondWith(router.fetch(claimed, router.containerPath(url.pathname, url.search), event.request, event.resultingClientId || event.clientId));
     return;
   }
   const port = router.portForRequest(url.pathname, event.clientId);

package/docs/agent/COMMANDS.md

@@ -0,0 +1,85 @@
+# Command catalog
+
+Run commands from `/Users/shazi/Projects/SandboxedJs` unless stated otherwise.
+Use focused commands first. Keep long logs out of model context:
+
+```sh
+some-command > /tmp/sbx-native-build.log 2>&1
+tail -n 120 /tmp/sbx-native-build.log
+```
+
+Do not use the redirection form when editing source files; it is for disposable
+logs only.
+
+## Cheap inspection
+
+```sh
+git status --short
+git diff --cached --check
+git diff --cached --stat
+python3 -m json.tool python-runtime/abi/extension-abi.json >/dev/null
+```
+
+## Build prerequisites and runtime
+
+```sh
+make -C python-runtime doctor
+make -C python-runtime python PROFILE=dynamic
+make -C python-runtime package PROFILE=dynamic
+npm run build
+```
+
+Do not rebuild CPython when the runtime and ABI inputs have not changed and the
+required output already exists.
+
+## Extension fixtures and index
+
+```sh
+python3 python-runtime/scripts/build_extension.py \
+  python-runtime/fixtures/sbx_setuptools_probe/recipe.json
+python3 python-runtime/scripts/build_extension.py \
+  python-runtime/fixtures/sbx_cython_probe/recipe.json
+python3 python-runtime/scripts/build_extension.py \
+  python-runtime/fixtures/sbx_rust_probe/recipe.json
+python3 python-runtime/scripts/build_index.py
+```
+
+If a wheel changes, rebuild `index.json` before runtime tests or its digest will
+correctly be stale.
+
+## Focused tests
+
+```sh
+npx vitest run test/python-runtime/extensions.test.ts
+npx vitest run test/python-runtime/resolver.test.ts
+npx vitest run test/python-runtime/extension-abi.test.ts
+npm run typecheck
+```
+
+Run `npm run check` only at milestone gates. Network-enabled suites are not a
+default native-package check.
+
+## Wheel inspection
+
+```sh
+python3 -m zipfile -l path/to/package.whl
+python3 python-runtime/scripts/build_index.py --wheels path/to/wheel-directory
+```
+
+Prefer adding a small reusable inspection script over repeatedly embedding
+complex Python in shell commands.
+
+## Logs
+
+Use one log per active failure under `/tmp`, named with the task and package.
+Keep only:
+
+- the exact command;
+- toolchain versions when relevant;
+- first causal error;
+- final 80-150 lines;
+- exit code.
+
+Warnings are not tasks unless they identify incorrect output or a future
+failure covered by the current milestone.
+

package/docs/agent/DECISION-TREE.md

@@ -0,0 +1,84 @@
+# Failure classification and decisions
+
+Classify an observed failure by its earliest decisive symptom.
+
+## Resolver says no usable distribution
+
+1. Inspect candidate filenames and tags.
+2. If a pure wheel exists, fix resolver/tag/metadata behavior; do not compile.
+3. If a matching SandboxedJS wheel exists, inspect index `abiId`, digest, and
+   dependency metadata.
+4. If only an sdist or host-native wheels exist, route to the external
+   cross-builder. Do not let the runtime installer build source yet.
+
+## Build frontend cannot start
+
+- Missing host Python module: classify as a build requirement.
+- Unpinned requirement: add an exact version and hash acquisition path.
+- Unsupported backend: add a backend adapter, not a package conditional.
+- Network failure: preserve the command and request network approval; do not
+  substitute an unverified archive.
+
+## Compiler uses host headers or compiler
+
+- Inspect generated cross-sysconfig and command line.
+- Fix host/target environment separation.
+- Never solve this by renaming a produced artifact.
+
+## Header or library not found
+
+1. Determine whether it is a Python dependency or a native target library.
+2. For a target library, require a declared, pinned native dependency.
+3. Build it into the ABI/profile-specific sysroot.
+4. Expose sysroot include/library paths through the cross environment.
+5. Add a reduced fixture proving the dependency mechanism before retrying a
+   large real package.
+
+## Configure test compiles, then tries to execute
+
+This is a cross-compilation probe problem. Prefer, in order:
+
+1. upstream-supported cross-file/cache variables;
+2. a generic build-backend cross configuration;
+3. a visible package patch providing the target fact.
+
+Never execute target WebAssembly as if it were a host binary. If executing a
+probe under a controlled runner is proposed, stop for architectural review.
+
+## Linker failure
+
+- Missing `Py*` symbols can remain unresolved in a side module if supplied by
+  the main module; confirm rather than blindly adding `-lpython`.
+- Missing native-library symbols require target dependency/link-order work.
+- Shared-memory, PIC, exception, relocation, or atomics errors are ABI issues;
+  inspect `INVARIANTS.md` and escalate before changing flags.
+- Duplicate symbols often indicate a static library linked twice; inspect the
+  complete link line.
+
+## Wheel builds but validation fails
+
+- Not `\0asm`: host compiler leakage.
+- No `dylink`: side-module link mode was lost.
+- Missing `PyInit_*`: module naming/export problem.
+- Wrong tag or ABI: wheel construction problem. Rebuild; never retag.
+
+## Install succeeds but import fails
+
+- Missing Python wrapper files: wheel assembly/layout defect.
+- Missing dependent shared/static symbols: target dependency closure defect.
+- Init symbol mismatch: derive the module name from installed path.
+- Trap, memory corruption, or exception failure: ABI mismatch until disproven.
+
+## Import succeeds but behavior fails
+
+Classify whether the package needs an unavailable OS capability, contains a
+32-bit assumption, exceeds memory, or has a package defect. Record an honest
+compatibility limitation when the platform capability is genuinely absent.
+
+## Test hangs
+
+Do not immediately increase timeouts. Determine whether the process is waiting
+on input, network, a child process, a pthread, or a host ABI response. Capture a
+bounded stack/process snapshot where possible. Kill only the exact process you
+started.
+

package/docs/agent/INVARIANTS.md

@@ -0,0 +1,40 @@
+# Non-negotiable invariants
+
+Read this before changing ABI, wheel, resolver, or compiler behavior.
+
+1. `python-runtime/abi/extension-abi.json` is the source of truth for target
+   identity and compile/link compatibility. Recipes cannot override ABI flags.
+2. A host-native ELF, Mach-O, `.node`, or other binary is never accepted or
+   relabeled as WebAssembly.
+3. A native wheel must match both its Python wheel tag and SandboxedJS
+   `abiId`.
+4. Build tools run on the build machine. Target code and target libraries are
+   compiled for wasm32. Never put target artifacts on the host interpreter's
+   import path.
+5. Build, host, Python-runtime, and native-target dependencies are separate
+   concepts and must be represented separately.
+6. Sources and build-tool artifacts are version-pinned and hash-verifiable.
+7. Generic behavior lives in generic machinery. Package-specific behavior is
+   visible in a recipe and/or patch, never hidden behind `if package == ...`.
+8. The package's own metadata is authoritative. Recipes may constrain or add
+   target facts, but must not silently duplicate drifting `Requires-Dist` data.
+9. Installer operations remain transactional. Failed resolution, download, or
+   installation must not leave a partial environment.
+10. A build is supported only after the wheel installs and its compiled module
+    executes under the owned SandboxedJS CPython runtime.
+11. Browser compatibility remains mandatory. Runtime TypeScript must not gain
+    unconditional Node builtin imports.
+12. Unsupported operating-system capabilities fail honestly. Package success
+    must not be manufactured by fake sockets, fake processes, or silent skips.
+
+## Forbidden shortcuts
+
+- Weakening `verify_side_module` or ABI checks to make a fixture pass.
+- Adding arbitrary recipe compiler/link flags.
+- Copying metadata solely from a handwritten recipe when upstream metadata can
+  be generated.
+- Installing unpinned build requirements from the network in a release build.
+- Treating "wheel file exists" as an acceptance result.
+- Starting with NumPy-specific branches in the generic pipeline.
+- Running full tests repeatedly when a focused test identifies the defect.
+

package/docs/agent/LAUNCH-PROMPT.md

@@ -0,0 +1,37 @@
+# Prompt to launch or resume Claude Opus
+
+Copy the text below into the coding task. Do not paste the rest of this folder
+into the prompt; the agent should read files on demand.
+
+```text
+You are the sole implementation agent for the SandboxedJS native Python
+package platform. The project controller is:
+
+agent-projects/python-package-platform/README.md
+
+Begin by reading only README.md, STATE.md, and the current task named in
+STATE.md. Follow LOOP.md. Execute commands and make decisions from their actual
+outputs. Continue through tasks while gates pass and context remains healthy.
+Keep STATE.md current so another task can resume without chat history.
+
+Preserve all pre-existing and staged work. Do not commit, publish, deploy,
+discard changes, weaken ABI validation, or change the ABI contract unless I
+explicitly authorize it. Use focused tests before broad suites. Keep long build
+logs in /tmp and bring only decisive excerpts into context.
+
+If a stop condition in LOOP.md occurs, stop with a compact escalation packet.
+The goal is a general package platform; NumPy is a later acceptance case, not a
+package-specific architecture target.
+
+Do not merely review or propose a plan. Work autonomously: inspect, edit,
+execute focused commands, diagnose their outputs, verify exit gates, update
+STATE.md, and advance to the next task. Do not ask for confirmation between
+ordinary in-scope steps. Continue until a documented stop condition requires my
+decision or all roadmap gates are complete.
+```
+
+## Execution policy
+
+This workflow assumes one Claude Opus agent. Do not delegate work to other
+models or create subagents. Use the stop conditions and ask the user for one
+concrete decision only when necessary.

package/docs/agent/LOOP.md

@@ -0,0 +1,84 @@
+# Agent execution loop
+
+Use this loop exactly. It is designed for a smaller model that can act well
+when each decision is grounded in the previous command's output.
+
+## 1. Orient
+
+Read `README.md`, `STATE.md`, and the current task only. Inspect `git status
+--short` before editing. Treat all pre-existing changes as user-owned.
+
+State the current hypothesis in one sentence. A hypothesis must predict an
+observable result, for example: "the linker cannot find `libxml2` because the
+dynamic sysroot is absent from target link flags."
+
+## 2. Choose the cheapest discriminating command
+
+Run the smallest command that can disprove the hypothesis. Prefer, in order:
+
+1. static inspection of one relevant file;
+2. one unit test or one fixture build;
+3. one runtime import test;
+4. the focused suite;
+5. the full suite only at a milestone gate.
+
+Never rerun a long build unchanged. If a command failed, inspect its decisive
+error first and change either the hypothesis or the implementation.
+
+## 3. Classify the result
+
+Use `DECISION-TREE.md`. Every failure must be classified before code changes.
+If there is not enough evidence, gather more evidence rather than guessing.
+
+## 4. Make one coherent change
+
+Change the smallest architectural seam that removes the demonstrated failure
+class. Do not add a package-name conditional to the generic builder. A package
+patch belongs in an explicit recipe patch directory, with a comment explaining
+the upstream assumption it replaces.
+
+Use `apply_patch` for hand edits. Do not overwrite files with shell redirects.
+Do not alter generated ABI files directly.
+
+## 5. Verify in layers
+
+Run the focused check that failed. If it passes, run the task's exit gate.
+Compilation is never the final gate for an extension: install and import it in
+the owned CPython runtime and exercise at least one native behavior.
+
+## 6. Record and advance
+
+Update `STATE.md` with compact evidence. If the task exit gate passes, set its
+checkboxes, point `Current task` to the next task in `ROADMAP.md`, and continue
+if budget remains.
+
+## Stop conditions
+
+Stop and request a user decision when:
+
+- the next action requires credentials, deployment, paid infrastructure, or
+  publishing outside the repository;
+- fulfilling the task requires changing the ABI contract rather than fixing a
+  consumer of it;
+- an upstream license is unclear or incompatible;
+- a destructive action, history rewrite, or discard of existing work appears
+  necessary;
+- the same failure class survives three evidence-driven attempts;
+- a design choice changes public API or materially increases shipped runtime
+  size without an already-stated budget.
+
+When stopping, preserve logs and state the smallest exact decision needed.
+
+## Escalation packet for the user
+
+When a stop condition is reached, prepare a compact packet containing:
+
+- intended invariant;
+- exact command;
+- final 80-150 relevant log lines;
+- files and functions involved;
+- three attempted hypotheses and what disproved each;
+- the decision required.
+
+Do not send entire build logs or the full repository history. Wait for the
+user's decision, record it in `STATE.md`, and then resume this same loop.

package/docs/agent/README.md

@@ -0,0 +1,77 @@
+# SandboxedJS native Python package platform
+
+This folder is an executable work specification for a coding agent. Its goal is
+not to port NumPy. Its goal is to make native Python packages a platform
+capability of SandboxedJS, with NumPy eventually serving as one demanding
+acceptance case.
+
+## Start here
+
+At the beginning of every turn, read only these files:
+
+1. `README.md` (this file).
+2. `STATE.md`.
+3. The one task file named by `STATE.md`.
+
+Do not reread every document on every turn. Open `INVARIANTS.md`,
+`DECISION-TREE.md`, or `COMMANDS.md` only when the current task points to them
+or an observed failure requires them. This is intentional: the folder is also
+a context and token budget.
+
+Then execute the loop in `LOOP.md`. Continue until the current task's exit gate
+passes or a stop condition requires the user or a stronger model.
+
+## Product objective
+
+The eventual user experience is:
+
+```sh
+pip install some-package
+```
+
+The implementation may obtain a pure wheel, install an already-built
+SandboxedJS wheel, or ask an external build system to create and cache a wheel.
+It must never install a host-native artifact by relabeling it, silently omit a
+dependency, or claim support because compilation alone succeeded.
+
+## Current baseline
+
+The working tree already contains staged, uncommitted work produced in an
+earlier session:
+
+- a generic setuptools cross environment;
+- package-owned `setup.py` and `pyproject.toml` builds;
+- C and Cython fixtures;
+- the existing PyO3 path;
+- side-module validation and runtime import tests;
+- `docs/python/cross-build.md`, which records ten known assumptions.
+
+Preserve those staged changes. Do not unstage, discard, rewrite wholesale, or
+commit them unless the user explicitly requests it. First verify them and
+record the result in `STATE.md`.
+
+## Scope boundary
+
+This project owns:
+
+- reproducible cross-build inputs;
+- build/host/target dependency separation;
+- package build-backend execution;
+- ABI-valid wheel construction and metadata;
+- wheel indexing, resolution, installation, and runtime verification;
+- explicit recipes and patches for irreducibly package-specific behavior;
+- compatibility evidence.
+
+This project does not own, unless the user separately authorizes it:
+
+- a hosted public build service;
+- cloud accounts, deployment, billing, or package signing infrastructure;
+- pretending raw sockets, subprocesses, GPU APIs, or unavailable operating
+  system capabilities exist;
+- broad unrelated cleanup of SandboxedJS.
+
+## Definition of success
+
+Success is a general pipeline demonstrated by several independent package
+shapes, not one famous package. The final gate is described in `ROADMAP.md`.
+

package/docs/agent/ROADMAP.md

@@ -0,0 +1,37 @@
+# Capability roadmap
+
+Advance only when the current task's exit gate passes. Each task must leave a
+focused regression test.
+
+| Order | Task | Capability produced |
+| --- | --- | --- |
+| 00 | `tasks/00-verify-inherited-work.md` | trusted baseline for the staged generic builder |
+| 01 | `tasks/01-authoritative-metadata.md` | wheel metadata derived from the package |
+| 02 | `tasks/02-native-dependencies.md` | declared target libraries and profile sysroot |
+| 03 | `tasks/03-reproducible-inputs.md` | hashed sources, build tools, patches, provenance |
+| 04 | `tasks/04-build-frontends.md` | explicit backend interface beyond setuptools/PyO3 |
+| 05 | `tasks/05-registry-integration.md` | reproducible build output consumable by `pip` |
+| 06 | `tasks/06-package-cohorts.md` | evidence across independent package shapes |
+| 07 | `tasks/07-build-on-miss-boundary.md` | local protocol/spec for an eventual build service |
+
+## Platform completion gate
+
+The platform milestone is complete when all of the following are true:
+
+- Pure wheels continue to install directly and transactionally.
+- Three native language/build shapes work without package-name branches.
+- At least one extension links a separately built native target library.
+- At least one package needs and cleanly carries a visible target patch.
+- Wheel metadata and dependency resolution come from authoritative package
+  metadata plus explicit target constraints.
+- Every indexed artifact is source-pinned, hash-verifiable, ABI-identified,
+  installable, importable, and behavior-tested in the owned runtime.
+- A compatibility report distinguishes supported, recipe-required,
+  platform-blocked, and not-yet-attempted packages.
+- The external build-on-miss interface is specified without embedding a
+  compiler toolchain in the browser runtime.
+
+NumPy may be attempted after tasks 00-05. It is evidence for native dependency,
+build-probe, memory, and scientific-stack behavior; it is not itself the
+definition of platform completion.
+

package/docs/agent/STATE.md

@@ -0,0 +1,93 @@
+# Execution state
+
+Keep under roughly 120 lines. Replace stale detail instead of appending.
+
+## Status
+
+- Phase: `complete`
+- Blocker: none
+- User decision required: none outstanding
+
+## Repository layout (restructured)
+
+    src/
+      kernel/ fs/ net/ shell/     the linux-mimicking core
+      node/      module shims, commonjs engine, esm transform
+      python/    cpython, syscalls, pip, resolver, worker, abi, local-builder
+      worker/    pods, sync channel, worker host
+      tools/     esbuild, rolldown, ffmpeg hosts
+      container/ pkg/ agent/ preview/ hosting/
+    docs/        every markdown file: agent/, python/, handoff.md
+    python-runtime/  the Python build pipeline (Makefile, scripts, recipes)
+
+`src/runtime/` is gone. Moves were done with `git mv` and every relative import
+recomputed programmatically. Four references were strings rather than import
+specifiers -- two `dist/` paths whose depth changed, a `/src/runtime/python/`
+check in config.ts, and a test allowlist -- and those caused 79 failures until
+found. There was no dead code to remove: 2 of 130 source files are unreferenced
+and both are ambient `.d.ts` files tsconfig loads implicitly.
+
+## Packages: nothing to pre-build any more
+
+`pip install <anything>` now builds a wheel when the index has none.
+
+- `scripts/auto_recipe.py` writes a recipe from what PyPI and the source
+  already state: identity, verified sdist, and the declared PEP 517 backend.
+  Backends with no adapter are refused by name. Build requirements the lock has
+  never seen are pinned at that moment rather than dropped.
+- `src/python/local-builder.ts` runs the pipeline; `bin/sandboxedjs-build-wheels.mjs`
+  serves the index and builds on request, for browsers that have no compiler.
+- Opt-in, defaulting on only in Node from a checkout. Submit-and-poll, because
+  a connection held open for a minutes-long build reads as an unreachable
+  service.
+- Verified: `pip install ujson` with no recipe -> generated, built, indexed,
+  installed, imported, both locally and through the service.
+
+## Two real defects found and fixed
+
+- The browser's default wheel index was filtered to the wheels whose bytes are
+  inlined in the bundle, so every other built wheel was invisible -- `pip
+  install numpy` reported no usable distribution while numpy sat unreferenced
+  beside the interpreter. The index now lists all built wheels, served from
+  next to the interpreter, with the inlined bytes as an overlay keyed by
+  filename.
+- The post-build index read went through pip's memoizing cache and returned the
+  pre-build copy, so a package was built twice.
+
+## Pre-existing failures, verified not caused by this work
+
+11 tests, reproduced identically in a clean worktree at HEAD: `python-syscalls`
+(5), `cpython` (2), `python-abi/baseline` (3), `python-runtime/asyncio` (1).
+Also: pytest's default output capture fails in the container
+(`OSError: [Errno 8] Bad file descriptor`), so upstream suites need
+`--capture=no`.
+
+## Unverified
+
+`import numpy` in a browser. The embedded browser used for testing blocks
+nested module workers loaded over HTTP, which the runtime needs to start Python
+at all -- `python3 --version` times out there too, and so does a trivial nested
+worker. `pip install numpy` was verified in that browser and returns 0.
+
+## Last evidence
+
+`npx vitest run`: 610 passed, 24 skipped, 12 failed (the 11 above plus one
+PyPI-network flake that passes in isolation). `npm run typecheck`: pass.
+`npm run build`: pass. All 16 wheels byte-identical across rebuilds.
+
+## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template## Compact checkpoint template
+
+Replace the sections above after each meaningful loop:
+
+```text
+Phase: <name>
+Current task: <path>
+Last completed task: <path or none>
+Blocker: <one sentence or none>
+User decision required: <yes/no and exact decision>
+Last evidence:
+- <command>: <pass/fail and decisive result>
+Next action: <one concrete action>
+Files changed this loop: <paths>
+```
+

package/docs/agent/tasks/00-verify-inherited-work.md

@@ -0,0 +1,36 @@
+# Task 00: verify inherited generic cross-build work
+
+## Purpose
+
+Establish that the staged setuptools/Cython work is real and reproducible
+before building new layers on it. Do not expand scope in this task.
+
+## Procedure
+
+1. Inspect `git status --short`, `git diff --cached --check`, and the staged
+   diff limited to the files listed in `STATE.md`.
+2. Confirm recipes cannot provide ABI compiler or linker flags.
+3. Confirm generated artifacts are checked for WebAssembly, `dylink`, and the
+   derived `PyInit_*` symbol.
+4. Run the setuptools and Cython fixture builds. Rebuild the wheel index after
+   any wheel output changes.
+5. Run `npm run build` only if runtime bundles required by the acceptance test
+   are absent or older than relevant inputs.
+6. Run `npx vitest run test/python-runtime/extensions.test.ts`.
+7. Run `npm run typecheck`.
+
+## Exit gate
+
+- Staged diff check passes.
+- Setuptools C, Cython, and PyO3 wheels install and execute native behavior in
+  the owned runtime.
+- Pydantic acceptance remains green.
+- No test passed by weakening or skipping an ABI assertion.
+- `STATE.md` contains exact passing commands and points to task 01.
+
+## If it fails
+
+Use `DECISION-TREE.md`. Fix only regressions within the inherited work. After
+three failed evidence-driven attempts on the same class, prepare an escalation
+packet instead of redesigning the ABI.
+