sandboxedjs 0.2.10 → 0.2.12

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="/assets/logo.png" alt="SandboxedJS" width="140" />
+<img src="https://cdn.jsdelivr.net/npm/sandboxedjs@latest/assets/logo.png" alt="SandboxedJS" width="140" />
 
 # SandboxedJS
 
@@ -29,7 +29,7 @@ const box = await createContainer({
 });
 
 await box.exec("ls -la /app");
-await box.exec("node /app/hello.js");        // → hi from linux
+await box.exec("node /app/hello.js"); // → hi from linux
 await box.exec("python3 -c 'print(2**64)'"); // → 18446744073709551616
 
 box.dispose();
@@ -54,16 +54,16 @@ Node 18.17+. Pure JavaScript and WebAssembly — no build step, no native module
 
 ## What's inside
 
-| | |
-|---|---|
-| **Filesystem** | A full FHS tree in memory (`/etc`, `/usr`, `/var`, `/home`), permissions, ownership, symlinks, hard links, `umask` |
-| **Shell** | POSIX `sh` — pipes, redirection, here-docs, globbing, functions, loops, job control, traps, `[[ ]]`, `(( ))` |
-| **Commands** | 160 programs: `ls cat grep sed awk find sort tar gzip curl wget diff sha256sum ps top` … |
-| **Node.js** | Its own runtime reporting v22.12.0 — CommonJS *and* ESM, `http`, `fs`, streams, `child_process`, npm and npx |
-| **Python** | Source-built CPython 3.13 (WASM) on the same filesystem, with `pip` |
-| **WebAssembly** | A WASI preview1 host: any `wasm32-wasi` binary runs as an ordinary process |
-| **FFmpeg** | `ffmpeg` / `ffprobe` 5.1 over container files — [optional install](#video-and-audio) |
-| **Network** | In-container HTTP servers, loopback, live previews, and a proxy for real outbound calls |
+|                 |                                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **Filesystem**  | A full FHS tree in memory (`/etc`, `/usr`, `/var`, `/home`), permissions, ownership, symlinks, hard links, `umask` |
+| **Shell**       | POSIX `sh` — pipes, redirection, here-docs, globbing, functions, loops, job control, traps, `[[ ]]`, `(( ))`       |
+| **Commands**    | 160 programs: `ls cat grep sed awk find sort tar gzip curl wget diff sha256sum ps top` …                           |
+| **Node.js**     | Its own runtime reporting v22.12.0 — CommonJS _and_ ESM, `http`, `fs`, streams, `child_process`, npm and npx       |
+| **Python**      | Source-built CPython 3.13 (WASM) on the same filesystem, with `pip`                                                |
+| **WebAssembly** | A WASI preview1 host: any `wasm32-wasi` binary runs as an ordinary process                                         |
+| **FFmpeg**      | `ffmpeg` / `ffprobe` 5.1 over container files — [optional install](#video-and-audio)                               |
+| **Network**     | In-container HTTP servers, loopback, live previews, and a proxy for real outbound calls                            |
 
 One filesystem underneath all of it: a file written by `echo` is read by `require('fs')` and by
 Python's `open()`, in any direction.
@@ -71,13 +71,16 @@ Python's `open()`, in any direction.
 ## Quick tour
 
 ```ts
-const box = await createContainer({ cwd: "/app", network: { allowOutbound: true } });
+const box = await createContainer({
+  cwd: "/app",
+  network: { allowOutbound: true },
+});
 
 await box.exec("npm install express", { cwd: "/app", timeoutMs: 300_000 });
 box.spawn("node server.js", { cwd: "/app" });
 await box.waitForPort(3000);
 
-const res = await box.request(3000, { path: "/api" });   // talk to it from your code
+const res = await box.request(3000, { path: "/api" }); // talk to it from your code
 console.log(res.status, res.json());
 ```
 
@@ -87,17 +90,21 @@ A stateful shell, when `exec` alone is too forgetful:
 const session = box.session();
 await session.run("cd /app");
 await session.run("export TOKEN=abc");
-await session.run("echo $TOKEN in $(pwd)");   // → abc in /app
+await session.run("echo $TOKEN in $(pwd)"); // → abc in /app
 ```
 
 Files in and out, snapshots, and a terminal you can wire to xterm.js:
 
 ```ts
 await box.fs.writeFile("/app/config.json", JSON.stringify(config));
-const snapshot = box.snapshot();              // serialisable; restore() later
+const snapshot = box.snapshot(); // serialisable; restore() later
 
 import { Terminal } from "sandboxedjs";
-const terminal = new Terminal(box.session(), { write: (d) => xterm.write(d), columns: 80, rows: 24 });
+const terminal = new Terminal(box.session(), {
+  write: (d) => xterm.write(d),
+  columns: 80,
+  rows: 24,
+});
 xterm.onData((d) => terminal.input(d));
 terminal.start();
 ```
@@ -110,7 +117,9 @@ terminal.start();
 This is the case most people arrive for: a Vite frontend and a Python backend, in one container, in
 a tab — the frontend calling `http://localhost:8000`, the backend calling a real API.
 
-Two different problems hide in that sentence, and SandboxedJS solves them in two different ways.
+The frontend-to-backend hop and the backend-to-internet hop have different requirements.
+See the [full-stack deployment guide](docs/fullstack-deployment.md) for production asset staging,
+Cloudflare Pages, Vercel, Node/serverless lifetimes, and troubleshooting.
 
 ### 1. Frontend → backend: nothing to configure
 
@@ -118,7 +127,7 @@ Two different problems hide in that sentence, and SandboxedJS solves them in two
 frontend (:3000) ──▶ http://localhost:8000/agent/run ──▶ FastAPI (:8000)
 ```
 
-Both servers are inside the container, so `localhost:8000` is *true there* — it means the
+Both servers are inside the container, so `localhost:8000` is _true there_ — it means the
 container's own backend, never your machine's. Leave the URL exactly as the project writes it. In a
 live preview, an injected script rewrites loopback addresses to the preview's origin and the
 service worker routes them back in by port, so the same code works in the frame without a proxy
@@ -129,21 +138,31 @@ import { createContainer, createPreview } from "sandboxedjs";
 
 // `allowOutbound` is still what lets the project install and call out at all;
 // the proxy is how those calls leave a browser, not permission to make them.
-const box = await createContainer({ files: project, network: { allowOutbound: true } });
+const box = await createContainer({
+  files: project,
+  network: { allowOutbound: true },
+});
 
-await box.exec("pip install -r requirements.txt", { cwd: "/app/backend", timeoutMs: 600_000 });
+await box.exec("pip install -r requirements.txt", {
+  cwd: "/app/backend",
+  timeoutMs: 600_000,
+});
 await box.exec("npm install", { cwd: "/app/frontend", timeoutMs: 600_000 });
 
 box.spawn("fastapi run", { cwd: "/app/backend" });
 box.spawn("npm run dev", { cwd: "/app/frontend" });
-await box.waitForPort(3000, { timeoutMs: 60_000 });
-
-const preview = await createPreview(box);      // null where service workers are unavailable
-iframe.src = preview!.urlFor(3000);
+if (!(await box.waitForPort(8000, { timeoutMs: 60_000 })) ||
+    !(await box.waitForPort(3000, { timeoutMs: 60_000 }))) {
+  throw new Error("Check backend and frontend startup logs");
+}
+
+const preview = await createPreview(box);
+if (!preview) throw new Error("Preview requires a working service worker");
+iframe.src = preview.urlFor(3000);
 ```
 
 It works between preview pages and from another tab of the same browser while the owner page is
-open. It does not work from Postman, curl or another machine — the container *is* the tab; there is
+open. It does not work from Postman, curl or another machine — the container _is_ the tab; there is
 no server anywhere to reach.
 
 ### 2. Backend → the internet: one file, once
@@ -155,25 +174,26 @@ FastAPI ──▶ egress proxy on your own origin ──▶ https://ollama.com
 
 A page may only read a response from a host that sends CORS headers, and most APIs send none — an
 `Authorization` header alone forces a preflight plenty of them answer with 405. That is the
-browser's rule about *pages*, not a container limit, and the only way through it is a request made
+browser's rule about _pages_, not a container limit, and the only way through it is a request made
 somewhere a page is not. So add one to the project you already deploy:
 
 ```bash
-npx sandboxedjs-egress init --allow ollama.com,api.openai.com
+npx sandboxedjs-egress init --target cloudflare --allow ollama.com,api.openai.com
 ```
 
 That writes a single function file at the path your host serves — Cloudflare Pages, Vercel and
 Netlify are detected, `--target` names one. Nothing else changes: a container in a browser probes
-its own origin for that proxy before giving up, so **no project passes a `proxy` option and no
-project is configured twice.**
-
-| Where you are | What to do |
-|---|---|
-| Deployed (Pages, Vercel, Netlify) | `npx sandboxedjs-egress init --allow …`, then deploy |
-| Developing | `npx sandboxedjs-egress` — the probe checks its port |
-| You already have a server | `app.use(EGRESS_PATH, egressNodeHandler({ allow: [...] }))`, before any body parser |
-| Using `npx sandboxedjs-serve` | Nothing; it mounts the proxy itself |
-| Node, not a browser | Nothing; there is no CORS to work around |
+its own origin for that proxy before giving up. The guest project needs no proxy setting;
+the host must deploy the generated function. For a separate relay, set `network.proxy`.
+A host serving only static files cannot relay APIs that reject browser requests.
+
+| Where you are                     | What to do                                                                          |
+| --------------------------------- | ----------------------------------------------------------------------------------- |
+| Deployed (Pages, Vercel, Netlify) | `npx sandboxedjs-egress init --allow …`, then deploy                                |
+| Developing                        | `npx sandboxedjs-egress` — the probe checks its port                                |
+| You already have a server         | `app.use(EGRESS_PATH, egressNodeHandler({ allow: [...] }))`, before any body parser |
+| Using `npx sandboxedjs-serve`     | Nothing; it mounts the proxy itself                                                 |
+| Node, not a browser               | Nothing; there is no CORS to work around                                            |
 
 ```ts
 // Your own Express/Node server:
@@ -182,12 +202,13 @@ app.use(EGRESS_PATH, egressNodeHandler({ allow: ["ollama.com"] }));
 
 // A static host — this is what `init` writes for you:
 import { handleEgressRequest } from "sandboxedjs/egress";
-export const onRequest = ({ request }) => handleEgressRequest(request, { allow: ["ollama.com"] });
+export const onRequest = ({ request }) =>
+  handleEgressRequest(request, { allow: ["ollama.com"] });
 ```
 
 Every exit honours it — `curl`, `wget`, a guest's `fetch`, Python's sockets and `httpx` — so it
 means the same thing whatever the project is written in. Loopback still stays inside the container,
-and the container's own policy still applies first: the proxy widens what a *page* can reach, never
+and the container's own policy still applies first: the proxy widens what a _page_ can reach, never
 what the container is allowed to.
 
 > ⚠️ Anything that can reach the proxy can make requests through it carrying whatever credentials
@@ -202,11 +223,13 @@ no meta tag or polyfill can add them later:
 ```ts
 // vite.config.ts
 export default {
-  server: { headers: {
-    "Cross-Origin-Opener-Policy": "same-origin",
-    "Cross-Origin-Embedder-Policy": "require-corp",
-  } },
-  optimizeDeps: { exclude: ["@rolldown/binding-wasm32-wasi"] },  // see below
+  server: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "require-corp",
+    },
+  },
+  optimizeDeps: { exclude: ["@rolldown/binding-wasm32-wasi"] }, // see below
 };
 ```
 
@@ -238,13 +261,13 @@ filesystem and a real socket), and the CLI. They fail only if you call them.
 
 ### Showing what runs
 
-| Need | Use | Runs guest code on your origin? |
-|---|---|---|
-| One response as data | `box.request(port, init)` | No — nothing executes |
-| One response rendered safely | `renderInto(box, el, { port })` | No — opaque-origin iframe, no `allow-same-origin` |
-| A whole site with real URLs | `createPreview(box)` → `urlFor(port)` | **Yes** — trusted code only |
+| Need                         | Use                                   | Runs guest code on your origin?                   |
+| ---------------------------- | ------------------------------------- | ------------------------------------------------- |
+| One response as data         | `box.request(port, init)`             | No — nothing executes                             |
+| One response rendered safely | `renderInto(box, el, { port })`       | No — opaque-origin iframe, no `allow-same-origin` |
+| A whole site with real URLs  | `createPreview(box)` → `urlFor(port)` | **Yes** — trusted code only                       |
 
-`createPreview` is what makes a dev server work: requests route by *which client is asking*, so
+`createPreview` is what makes a dev server work: requests route by _which client is asking_, so
 `/src/main.js` and `/@vite/client` resolve without rewriting anything, and a tunnelled `WebSocket`
 carries HMR. Serve it from a separate origin for code you did not write. On Node, `box.expose(port)`
 gives a real loopback URL instead. Full lifecycle notes: [Server previews](docs/server-previews.md).
@@ -274,9 +297,15 @@ not a runtime dependency, so install it alongside your model provider.
 ```ts
 import { SandboxedJsBackend, installSandboxSkills } from "sandboxedjs/agent";
 
-const box = await createContainer({ cwd: "/app", network: { allowOutbound: true } });
+const box = await createContainer({
+  cwd: "/app",
+  network: { allowOutbound: true },
+});
 await installSandboxSkills(box);
-const agent = createDeepAgent({ model, backend: new SandboxedJsBackend(box, { cwd: "/app" }) });
+const agent = createDeepAgent({
+  model,
+  backend: new SandboxedJsBackend(box, { cwd: "/app" }),
+});
 ```
 
 ## Video and audio
@@ -287,7 +316,9 @@ filesystem — inputs and outputs are ordinary container files, so pipelines wor
 report themselves missing, as a real system does.
 
 ```js
-await box.exec("ffmpeg -f lavfi -i testsrc=size=640x480:rate=25:duration=5 -pix_fmt yuv420p clip.mp4");
+await box.exec(
+  "ffmpeg -f lavfi -i testsrc=size=640x480:rate=25:duration=5 -pix_fmt yuv420p clip.mp4",
+);
 await box.exec("ffmpeg -i clip.mp4 -vf scale=320:-2 -frames:v 1 thumb.png");
 ```
 
@@ -305,7 +336,7 @@ What it is **not**:
 - **Not a VM.** Everything runs in your JavaScript engine. A true escape is an engine escape. This
   is isolation from mistakes and ordinary untrusted programs, not from a determined attacker.
 - **The user model does not constrain Node.** `user: "agent"` is enforced for the shell, the
-  commands and Python — `cat /root/secret` is denied for real. It is *not* enforced for `node`,
+  commands and Python — `cat /root/secret` is denied for real. It is _not_ enforced for `node`,
   which reaches the volume directly. Model ordinary multi-user behaviour with it; do not treat it
   as a privilege boundary for JavaScript you do not trust.
 - **A preview shares your origin.** `createPreview` serves guest code from the page that registered
@@ -323,7 +354,7 @@ An honest list:
 
 - **No compiled native addons.** A `.node` file cannot load; a package needs a JS or WASM fallback.
   `rollup` and `esbuild` get redirected to `@rollup/wasm-node` and `esbuild-wasm` automatically.
-- **esbuild cannot run *inside* the sandbox**, so tools that call it directly fail. On Node it
+- **esbuild cannot run _inside_ the sandbox**, so tools that call it directly fail. On Node it
   borrows the host's `esbuild-wasm`.
 - **Vite 8 / Rolldown is browser-only.** The Node binding preopens the real filesystem root and
   cannot be handed another, so it looks for your project on the actual disk. Vite 7 works on both.
@@ -333,7 +364,7 @@ An honest list:
 - **Processes are cooperative.** `kill -9` cannot interrupt a tight synchronous loop; `SIGSTOP`
   marks state. `chroot` runs the command in the target rather than isolating it.
 - **`execSync` needs the worker runtime.** Where it is unavailable, it throws naming the command —
-  answer *No* to prompts like `npm create vite`'s "Install and start now?" and run the steps from
+  answer _No_ to prompts like `npm create vite`'s "Install and start now?" and run the steps from
   the shell.
 - **`node:test`** covers what test files use (`test`/`describe`/hooks/`mock.fn`, spec and tap
   reports); `run()`, coverage and mock timers are not implemented.
@@ -357,13 +388,15 @@ dispatch all find it:
 ```ts
 import { defineCommand } from "sandboxedjs";
 
-box.kernel.installCommand(defineCommand({
-  name: "greet",
-  summary: "say hello",
-  run: (ctx) => (ctx.line(`hello ${ctx.args[0] ?? "world"}`), 0),
-}));
+box.kernel.installCommand(
+  defineCommand({
+    name: "greet",
+    summary: "say hello",
+    run: (ctx) => (ctx.line(`hello ${ctx.args[0] ?? "world"}`), 0),
+  }),
+);
 
-await box.exec("greet there | tr a-z A-Z");   // → HELLO THERE
+await box.exec("greet there | tr a-z A-Z"); // → HELLO THERE
 ```
 
 `Kernel`, `Vfs`, `Shell`, `Terminal` and `NetworkStack` are exported too, if you want to embed a

package/bin/sandboxedjs-egress.mjs

@@ -45,7 +45,7 @@ const TARGETS = {
 ${allow}
 /* Cloudflare Pages serves this file at /__sandboxedjs__/egress, which is where
  * a container in this site's pages looks for its way out. */
-export const onRequest = ({ request }) => handleEgressRequest(request, options);
+export const onRequest = ({ request }: { request: Request }) => handleEgressRequest(request, options);
 `,
   },
   vercel: {
@@ -57,7 +57,7 @@ export const config = { runtime: "edge" };
 
 /* Vercel serves this file at /api/__sandboxedjs__/egress, which is one of the
  * paths a container in this site's pages probes for its way out. */
-export default (request) => handleEgressRequest(request, options);
+export default (request: Request) => handleEgressRequest(request, options);
 `,
   },
   netlify: {
@@ -67,7 +67,7 @@ export default (request) => handleEgressRequest(request, options);
 ${allow}
 export const config = { path: "/.netlify/functions/sandboxedjs-egress" };
 
-export default (request) => handleEgressRequest(request, options);
+export default (request: Request) => handleEgressRequest(request, options);
 `,
   },
 };
@@ -90,13 +90,28 @@ async function detectTarget(root) {
 }
 
 async function init(argv) {
-  const root = argv.find((a) => !a.startsWith("-")) ?? process.cwd();
-  const at = argv.indexOf("--target");
-  const allowAt = argv.indexOf("--allow");
-  const allowed = allowAt === -1
-    ? null
-    : (argv[allowAt + 1] ?? "").split(",").map((h) => h.trim()).filter(Boolean);
-  const name = at === -1 ? await detectTarget(root) : argv[at + 1];
+  let directory;
+  let targetName;
+  let allowed = null;
+  for (let index = 0; index < argv.length; index++) {
+    const argument = argv[index];
+    if (argument === "--target" || argument === "--allow") {
+      const value = argv[++index];
+      if (!value || value.startsWith("--")) {
+        console.error(`sandboxedjs-egress init: ${argument} requires a value`);
+        process.exitCode = 1;
+        return;
+      }
+      if (argument === "--target") targetName = value;
+      else allowed = value.split(",").map((host) => host.trim()).filter(Boolean);
+    } else if (argument.startsWith("-") || directory !== undefined) {
+      console.error(`sandboxedjs-egress init: unexpected argument ${argument}`);
+      process.exitCode = 1;
+      return;
+    } else directory = argument;
+  }
+  const root = directory ?? process.cwd();
+  const name = targetName ?? await detectTarget(root);
   if (!name || !TARGETS[name]) {
     console.error(
       name

package/dist/index.cjs

@@ -21103,7 +21103,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.10"};
+  version: "0.2.12"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {

package/dist/index.js

@@ -21086,7 +21086,7 @@ var wheels_default = {
 
 // package.json
 var package_default = {
-  version: "0.2.10"};
+  version: "0.2.12"};
 
 // src/python/extension-abi.ts
 var EXTENSION_ABI = {

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.
+