dshm-compat 0.1.3 → 0.1.5

package/AGENTS.md

@@ -0,0 +1,17 @@
+# dshm-compat development rules
+
+## No per-plugin adaptation
+
+- **Never** add a production branch, recipe, rule, or hand-built artifact for one
+  package name. `dshm-compat` must adapt plugins through its generic engines.
+- S2/native plugins go through `lib/s2-native.js`: detect the worker and the
+  standard runtime/spawn patterns, stage the worker, normalize the manifest, and
+  validate the result. Package names may appear only in tests and documentation
+  examples, never in `if (name === ...)` logic.
+- If a plugin has a genuinely unique protocol, expose a **generic extension
+  point** in the plugin engine (patterns, hooks, or sidecar descriptor), not a
+  one-off patch.
+- `dsh-ops` is a regression fixture. It proves the generic S2 adapter; it is not
+  a special case.
+- Deliverables are the plugin and its generic tooling, not a converted tarball
+  for a single plugin.

package/CHANGELOG.md

@@ -1,16 +1,82 @@
 # Changelog
 
+## 0.1.5
+
+- Spawn rewriting now uses `['bash', file]` plus a staged shell wrapper instead
+  of `bash -c 'exec "$0" "$@"'`. `dshm-vm-bash` drops positional parameters for
+  `-c`, so the old form produced `Permission denied` and lost worker arguments.
+- `runGuestFile` and sidecars use the same non-`-c` path (`bash <wrapper> <args>`).
+- Release acquisition tries the package-version tag first, then the latest
+  release, falls back to the API asset endpoint, verifies `sha256` when
+  available, and returns attempts instead of a silent failure.
+- Source-only packages return `needs-build` with an external build contract;
+  when the same package has a published npm build, `convert` automatically
+  retries that build instead. Verified with `dsh-ops` 0.4.0 GitHub source:
+  it falls back to `dsh-ops@0.3.0` and produces a validated package.
+- Added `compat_build`: a source build planner for `Cargo.toml`/Node
+  `build`/`prepack` packages, plus an opt-in `backend:"guest"` attempt that
+  provisions Rust or Node in the Alpine guest and runs the build there. The
+  guest path depends on guest network/disk and is explicitly experimental.
+- Added `compat_uninstall` and `engines.dsh` normalization.
+- Offline regression suite: 30/30.
+
+## 0.1.4
+
+- The generic S2 adapter now accepts **x86_64** workers: it bundles
+  `qemu-x86_64` and a minimal x86_64 glibc rootfs, stages a shell wrapper, and
+  runs the worker under QEMU in the guest. No AArch64 rebuild is required for
+  plugins that publish a `linux-x64` runtime.
+- If the package contains no worker, the adapter looks at the GitHub repository
+  release assets, prefers `linux-arm64` then `linux-x64`, extracts the archive
+  (ZIP or tar.gz), and uses the first AArch64/x86_64 ELF. No package name is
+  special-cased.
+- Source-only native packages (for example a Rust `native/` tree with no
+  prebuilt runtime) now classify as S2 instead of S0, so the native adapter gets
+  a chance to build or acquire a worker.
+- Verified end-to-end: `compat_convert("https://github.com/T-Auto/dsh-ops")`
+  with **no workerPath** acquires the upstream `linux-x64` release asset, wraps
+  it in QEMU, patches the runtime/spawn/peer/os-cpu gates, and validates.
+- Spawn rewrite now uses `['bash', file]` and stages a shell wrapper around the
+  real worker instead of `bash -c 'exec "$0" "$@"'`. `dshm-vm-bash` drops
+  `$0`/`$@` for `-c` commands, which caused `Permission denied` and lost
+  arguments; the non-`-c` path preserves them.
+- Release selection first tries the tag matching the package version (`vX.Y.Z`),
+  then the latest release with assets; missing tags fall through instead of
+  returning an empty asset list.
+- Release download falls back from `browser_download_url` to the GitHub API
+  asset endpoint (`Accept: application/octet-stream`), records every attempt,
+  and verifies the asset `sha256` digest when GitHub provides one. Failures are
+  returned in `acquisition.attempts`, not swallowed.
+- The adapter also rewrites resolved-shell spawns (`[file, '-c', command]` and
+  `[file, scriptPath]`) to `['bash', '-c', command]` / `['bash', scriptPath]`,
+  so the shell component does not exec an ELF from the app sandbox.
+- `runGuestFile` now invokes `bash <script> <args>` instead of
+  `bash -c 'exec "$0" "$@"'`; sidecars stage a wrapper script so positional
+  arguments survive `dshm-vm-bash`.
+- Source packages with no built `main` and a `build`/`prepack` script return
+  `needs-build` with an external `npm ci && npm run build && npm pack` contract
+  instead of `recipe-mismatch`.
+- Added `compat_uninstall` for profile-local removal (node_modules + dependency
+  + bundle entry), and `engines.dsh` is stripped alongside `os`/`cpu`.
+- Offline regression suite: 28/28.
+
 ## 0.1.3
 
-- Fixed dsh-ops recipe dispatch for GitHub specs: the converter now keys on
-  `report.package.name`, not `report.resolved.name` (which is `owner/repo` for
-  GitHub). `compat_convert("https://github.com/T-Auto/dsh-ops", ...)` now
-  reaches the recipe and returns `needs-native-build` instead of `skipped`.
-- The dsh-ops recipe relaxes `peerDependencies["@deepseek-ai/dsh"]` to
-  `workspace:*` so installing it does not make the DSHM core fail its
-  prerelease compatibility check on the next boot.
-- Clearer S2 skipped message ("needs a recipe or an external native build").
-- Offline regression suite: 24/24.
+- Added a **generic S2 native adapter** (`lib/s2-native.js`). It discovers the
+  worker and the runtime matrix in the package, appends the DSHM target,
+  rewrites `${platform}-${arch}` templates, wraps standard `const/let argv =
+  [file]` spawn calls in `bash -c`, removes foreign `os`/`cpu` gates and
+  non-Linux optional payloads, and relaxes the DSH `peerDependencies` range.
+  There are no package-name branches and no built-in per-package rules.
+- Added a generic guest sidecar bridge (`compat_sidecar` / `lib/sidecar.js`):
+  stage a Linux/AArch64 worker from a converted tarball into
+  `$DSH_HOME/dshm-compat/sidecars/<id>`, list/probe it, and call it with one
+  JSON request/response through the Alpine guest.
+- `compat_plan` now infers `rust`, `c/c++`, or `node-gyp` from source files in
+  the report instead of relying on a package-specific rule.
+- S2 conversion dispatches on the strategy and the generic patterns, not on a
+  package name; GitHub specs work through the same path.
+- Offline regression suite: 25/25.
 
 ## 0.1.2
 

package/INSTALL.md

@@ -1,7 +1,7 @@
 # Installing dshm-compat
 
-The artifact is a normal DSH bundle package: `dshm-compat-0.1.3.tgz`.
-It is host-only, has no runtime dependencies, and adds eight agent tools.
+The artifact is a normal DSH bundle package: `dshm-compat-0.1.5.tgz`.
+It is host-only, has no runtime dependencies, and adds twelve agent tools.
 
 ## A. DSHM (the tablet)
 
@@ -15,7 +15,7 @@ input calls `pnpm view` before installing and fails with
 `Command failed with EACCES: pnpm view ... spawn pnpm EACCES`. Use one of these
 instead:
 
-- ask the DSHM Agent to run `pnpm add dshm-compat@0.1.3` in its bash tool (the
+- ask the DSHM Agent to run `pnpm add dshm-compat@0.1.5` in its bash tool (the
   bundled pnpm shim routes that command to the host install queue); or
 - install from a GitHub repository URL; or
 - after any working install, use the plugin's own `compat_install` tool for
@@ -28,7 +28,7 @@ not accept local paths, `file:` or `http://` specs.
 
 ### A2. HTTPS tarball
 
-Put `dshm-compat-0.1.3.tgz` on any HTTPS host (GitHub Release, Gitee Release,
+Put `dshm-compat-0.1.5.tgz` on any HTTPS host (GitHub Release, Gitee Release,
 object storage) and paste the `.tgz` URL into the same Add plugin input. DSHM's
 installer accepts tarball specs; if the current market UI refuses a plain URL,
 use A1.
@@ -38,7 +38,7 @@ use A1.
 If `hdc` is available and the app can read the path:
 
 ```sh
-hdc file send dshm-compat-0.1.3.tgz /data/storage/el2/base/haps/entry/files/dshm-compat-0.1.3.tgz
+hdc file send dshm-compat-0.1.5.tgz /data/storage/el2/base/haps/entry/files/dshm-compat-0.1.5.tgz
 ```
 
 Then enter the absolute path (or `file:/...`) in the Add plugin input. This
@@ -47,7 +47,7 @@ depends on the DSHM build's local-file support; A1 is safer.
 ## B. Desktop DSH (for testing only)
 
 ```powershell
-& 'D:\安装\dsh-desktop\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add 'D:\dsh\dsh-26-09-30\dshm-compat\dshm-compat-0.1.3.tgz'
+& 'D:\安装\dsh-desktop\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add 'D:\dsh\dsh-26-09-30\dshm-compat\dshm-compat-0.1.5.tgz'
 ```
 
 If the profile reports `ERR_PNPM_UNEXPECTED_VIRTUAL_STORE`, its `node_modules`

package/README.md

@@ -5,11 +5,12 @@ them through the least invasive strategy that can work.
 
 ## Current phase
 
-0.1.3 fixes dsh-ops recipe dispatch for GitHub specs and relaxes its DSH peer
-range; it also adds `compat_doctor`, rollback-safe local installs, and codeload
-fallbacks for GitHub. Phase 1 ships the analyzer, the S0/S1 converter, the
-dsh-ops recipe, guest probing/provisioning, the DSHM install-queue transport,
-and a profile-local fallback for artifacts the host queue rejects:
+0.1.5 adds runtime-bridge fixes (non-`-c` spawn wrappers), release asset
+fallbacks, and `compat_uninstall`; 0.1.4 added the generic S2 adapter with
+x86_64 QEMU and GitHub Release acquisition. Phase 1 ships the analyzer, the
+S0/S1 converter, the generic S2 engine, guest probing/provisioning, the DSHM
+install-queue transport, and a profile-local fallback for artifacts the host
+queue rejects:
 
 - `compat_analyze` downloads an npm/GitHub/local package and classifies it.
 - `compat_plan` returns the concrete conversion plan without changing anything.
@@ -18,12 +19,21 @@ and a profile-local fallback for artifacts the host queue rejects:
   install lifecycle scripts, client platform), vendors missing pure-JS runtime
   dependencies into a flat `node_modules`, validates the resulting tarball, and
   repacks it as a DSHM tarball; for S1 it removes a native dependency that the
-  DSHM core already provides. For `dsh-ops` it applies the 0.3.x recipe once an
-  AArch64 Linux worker is supplied via `workerPath`; without one it returns
-  `needs-native-build` with the exact cross-build command.
+  DSHM core already provides. For S2 it uses the generic native adapter: it
+  detects the worker, `PLATFORMS` matrix, `${platform}-${arch}` templates,
+  standard spawn calls, and foreign `os`/`cpu`/peer gates. A worker can come from
+  `workerPath`, the package's `runtime/linux-*`, or the GitHub Release assets
+  (linux-arm64 first, then linux-x64). An x86_64 worker is executed through the
+  bundled `qemu-x86_64` and glibc rootfs, so no AArch64 rebuild is required.
+  A source-only checkout is retried against the package's published npm build
+  (with a `fallback` field in the result); only when neither a worker nor a
+  published build exists does it return `needs-build`/`needs-native-build` with
+  the external build command. Package names are not special-cased.
 - `compat_guest_probe` reports the Alpine guest kernel/packages/tools.
 - `compat_guest_provision` installs a reviewed allowlist of Alpine packages in
   the guest (`confirm:true` required).
+- `compat_sidecar` stages a native Linux/AArch64 worker from a converted
+  tarball and lists/probes/calls it in the guest with JSON stdin/stdout.
 - `compat_status` lists stored reports and install attempts.
 - `compat_doctor` checks DSHM mode, core, profile/bundle, queue, state, and the
   guest in one read-only call.
@@ -31,26 +41,40 @@ and a profile-local fallback for artifacts the host queue rejects:
   `.tgz` paths (and `file:`/`link:`) are unpacked directly into the owning DSH
   profile and its bundle list, then need a DSHM restart; this is required
   because the DSHM host queue rejects local specs.
+- `compat_build` plans a source build (PC/CI commands) or, with
+  `backend:"guest"` and `confirm:true`, provisions Node/Rust in the Alpine
+  guest and attempts the build there. The guest path is experimental and
+  depends on guest network/disk.
+- `compat_uninstall` removes a profile-local package, its dependency entry, and
+  its bundle entry; it also needs a restart.
 - `compat_convert` with `install:true` uses the same local fallback for its
   converted tarball.
 
-The converter deliberately stops at the manifest/repack/vendor boundary:
-source transpilation and native builds are later phases. A report saying
-`S2`/`S3`/`S4` is returned as-is rather than being reported as a successful
-conversion.
+The converter stops at the manifest/repack/vendor boundary for S0/S1. S2 also
+returns `needs-build` for a source-only package or `needs-native-build` when no
+Linux worker can be obtained. It does not silently claim that an unsupported
+native build succeeded.
 
 See [architecture](docs/ARCHITECTURE.md) and [conversion recipes](docs/RECIPES.md).
 
+## Development policy
+
+There are **no per-plugin production branches**. S2 native plugins go through
+the generic `lib/s2-native.js` engine; package names appear only in tests and
+documentation examples. If a plugin has a unique protocol, add a generic
+extension point (pattern, hook, or sidecar descriptor) instead of a one-off
+patch. See [AGENTS.md](AGENTS.md).
+
 ## CLI
 
 The same converter runs on a PC without installing the DSH plugin:
 
 ```sh
 node bin/dshm-compat.mjs analyze dsh-m
-node bin/dshm-compat.mjs plan dsh-ops
+node bin/dshm-compat.mjs plan some-native-plugin
 node bin/dshm-compat.mjs convert dsh-cache-billing --no-vendor
-node bin/dshm-compat.mjs convert dsh-ops --worker ./dsh-ops-worker
-node bin/dshm-compat.mjs scan dsh-m dsh-ops some-plugin
+node bin/dshm-compat.mjs convert some-native-plugin --worker ./some-native-worker
+node bin/dshm-compat.mjs scan dsh-m some-native-plugin some-plugin
 ```
 
 `convert` writes the tarball under `$DSH_HOME/dshm-compat/builds` (override with

package/assets/qemu-x86_64/NOTICE.md

@@ -0,0 +1,17 @@
+# Bundled QEMU x86_64 user-mode runtime
+
+This directory is a generic fallback for S2 plugins that ship a `linux-x64`
+native worker but no AArch64 build. `qemu-x86_64` executes the x86_64 worker in
+the DSHM Alpine guest; the `rootfs/` directory supplies the glibc loader and
+libraries the worker links against.
+
+- `qemu-x86_64`: Alpine 3.22 `qemu-x86_64` 10.0.0-r1 (aarch64 build), GPL-2.0.
+  Source: https://pkgs.alpinelinux.org/package/v3.22/community/aarch64/qemu-x86_64
+- `rootfs/lib64/ld-linux-x86-64.so.2`,
+  `rootfs/lib/x86_64-linux-gnu/libc.so.6`,
+  `rootfs/lib/x86_64-linux-gnu/libgcc_s.so.1`: Ubuntu 24.04 x86_64 base rootfs,
+  LGPL-2.1/GPL-2.0 with GCC runtime exception.
+  Source: https://cdimage.ubuntu.com/ubuntu-base/releases/24.04/release/
+
+The fallback is optional: when a plugin has a native AArch64 worker, the generic
+S2 adapter stages that directly and these files are not used.

package/docs/ARCHITECTURE.md

@@ -37,7 +37,7 @@ spec ──► resolve (npm / GitHub / local .tgz)
       ──► extract (ustar/pax, no dependency)
       ──► analyze (manifest, native files, scripts, platform/Electron scan, core inventory)
       ──► plan (S0..S4 + concrete steps)
-      ──► convert (S0/S1 now; S2+ is a plan)
+      ──► convert (S0/S1 manifest, S2 generic native adapter)
       ──► pack (ustar writer)
       ──► install queue (DSHM only)
 ```
@@ -50,14 +50,20 @@ spec ──► resolve (npm / GitHub / local .tgz)
 | `lib/tar.js` | ustar/pax extraction with traversal and size guards |
 | `lib/analyze.js` | classification evidence, strategy, confidence, next action |
 | `lib/core.js` | locate `$DSH_HOME/cores/<version>/node_modules` and compare runtime dependencies |
-| `lib/rules.js` | exact recipes for known packages (`dsh-ops`) |
-| `lib/convert.js` | S0 manifest rewrite/repack and vendoring; S1 native-dependency removal |
+| `lib/rules.js` | operator-supplied custom rules only; no built-in per-package rules |
+| `lib/convert.js` | S0 manifest rewrite/repack and vendoring; S1 native-dependency removal; dispatch to the S2 adapter |
+| `lib/s2-native.js` | generic S2 worker/runtime/spawn/peer adapter |
+| `lib/release.js` | GitHub Release Linux worker discovery and extraction |
+| `lib/zip.js` | dependency-free ZIP reader for release assets |
 | `lib/vendor.js` | flat `node_modules` vendoring for missing pure-JS dependencies |
 | `lib/validate.js` | post-conversion manifest/entry/dependency validation |
 | `lib/plan.js` | user-visible conversion plan for every strategy |
 | `lib/guest.js` | read-only Alpine guest probe through `subprocess` |
 | `lib/install.js` | DSHM install-queue producer with polling and cancellation |
 | `lib/local-install.js` | profile-local tarball install with staging, backup, and rollback |
+| `lib/uninstall.js` | profile-local removal of files, dependency, and bundle entry |
+| `lib/source-build.js` | source-build planner and experimental guest build |
+| `lib/sidecar.js` | generic guest worker staging and JSON-stdio calls |
 | `lib/doctor.js` | one-shot DSHM/core/profile/queue/guest diagnosis |
 | `lib/state.js` | bounded report/install index and atomic writes |
 | `lib/pack.js` | dependency-free ustar/gzip writer |
@@ -72,18 +78,22 @@ spec ──► resolve (npm / GitHub / local .tgz)
 | `compat_convert` | writes a converted tarball; optionally submits it to the install queue |
 | `compat_guest_probe` | read-only guest command |
 | `compat_guest_provision` | installs allowlisted Alpine packages in the guest |
+| `compat_sidecar` | stages/lists/probes/calls a JSON-stdio native worker in the guest |
 | `compat_doctor` | read-only DSHM/core/profile/queue/guest diagnosis |
 | `compat_install` | writes one install-queue request; runs third-party code |
+| `compat_build` | plans a source build, or provisions a guest toolchain and runs it with confirm:true |
+| `compat_uninstall` | removes a profile-local package, dependency, and bundle entry |
 | `compat_status` | read-only |
 
 ## Phase status
 
 - **Phase 1 (done):** analyzer, batch triage, S0 manifest converter + flat
-  dependency vendoring + output validation, S1 manifest substitution,
-  dependency preflight, guest probe/provisioning, worker execution primitive,
-  dsh-ops 0.3.x recipe (external AArch64 worker), install queue, offline tests.
-- **Phase 2 (next):** on-device guest verification, dsh-ops worker build, nested
-  version-conflict vendoring, sidecar RPC.
+  dependency vendoring + output validation, S1 manifest substitution, generic S2
+  native adapter (AArch64 worker, x86_64 worker through bundled QEMU, GitHub
+  Release acquisition), dependency preflight, guest probe/provisioning, worker
+  execution primitive, install queue, offline tests.
+- **Phase 2 (next):** on-device guest verification, automatic worker build
+  (desktop/CI), nested version-conflict vendoring, sidecar RPC.
 - **Phase 3:** WASM/remote fallback, market UI entry, compatibility registry
   updates.
 

package/docs/RECIPES.md

@@ -1,104 +1,92 @@
-# Conversion recipes
-
-These are the concrete recipes behind `S1`/`S2` plans. They are intentionally
-written as patches to the upstream package, not as claims that the current
-converter executes them.
-
-## `dsh-ops` (Rust native worker)
-
-Upstream: `T-Auto/dsh-ops`. The core is `native/` (Rust) and the published
-worker is `runtime/<target>/dsh-ops-worker`.
-
-### 1. Support matrix
-
-`lib/ptc/runtime.js` hard-codes:
-
-```js
-const PLATFORMS = ['win32-x64', 'linux-x64', 'darwin-arm64']
-```
-
-`resolveWorker()` checks this matrix **before** considering
-`DSH_OPS_WORKER_BIN`, so a binary path override alone cannot unblock DSHM.
-
-Patch:
-
-- add `linux-arm64` to `PLATFORMS`;
-- map an OHOS `process.platform` to `linux-arm64` before the matrix check;
-- keep `workerName()` returning `dsh-ops-worker` on non-win32;
-- look for `runtime/linux-arm64/dsh-ops-worker`.
-
-Also update:
-
-- `package.json` `os`/`cpu` (remove the gates or add `openharmony`/`arm64`);
-- `dsh-plugin.json` `platforms`, `architectures`, and `targets` for each
-  `x-components` entry.
-
-### 2. Build the worker
-
-From a Linux build host or CI:
+# Generic conversion patterns
+
+These are the patterns behind `S1`/`S2` plans. They are **generic**: no
+production branch is keyed on a package name. A package name may appear only in
+tests or as a documentation example.
+
+## S2: native worker
+
+The generic adapter in `lib/s2-native.js` recognizes the common shape of a
+native DSH plugin:
+
+1. A worker binary under `runtime/<platform>-<arch>/<name>`, a worker passed
+   explicitly with `workerPath`, or a Linux asset on the repository's GitHub
+   Release (arm64 preferred, then x64).
+2. A JS module exporting a `PLATFORMS` array and interpolating
+   `${platform}-${arch}` into runtime paths.
+3. Spawn calls of the form `const argv = [file]` or `let argv = [file]`.
+4. Optional `package.json` `os`/`cpu` gates and a DSH `peerDependencies` range.
+
+For each match it:
+
+- appends `linux-arm64` (AArch64 worker) or `linux-x64` (x86_64 worker) to
+  `PLATFORMS` and injects a `resolveTarget()` helper so `openharmony`/arm64
+  resolves to that target in both `resolveWorker` and `tryResolveWorker`;
+- replaces `${platform}-${arch}` **inside template literals** with
+  `${resolveTarget(platform, arch)}`;
+- rewrites every standard spawn call to `['bash', file]` and stages a shell
+  wrapper at `file` that `exec`s the real worker with `"$@"`. The
+  non-`-c` path is required because `dshm-vm-bash` drops positional parameters
+  for `bash -c`; the wrapper preserves the worker's argv;
+- removes `os`/`cpu`/`engines.dsh`, drops win32/darwin optional payloads, and
+  relaxes `@deepseek-ai/dsh` to `workspace:*`;
+- adds `openharmony`/target/arch to `dsh-plugin.json` component targets;
+- stages the wrapper at `runtime/<target>/<worker>` and the real binary at
+  `<worker>-bin` (AArch64) or `<worker>-x64` (x86_64), with a matching
+  `provenance.json` (`version`, `target`, `executable`, `sha256`).
+
+A source package whose `main` is absent but which has a `build`/`prepack` script
+returns `needs-build` with `npm ci && npm run build && npm pack`; the produced
+tarball is then passed back to `compat_convert`. Before returning that, the
+converter retries the package's latest published npm build and records a
+`fallback` field when it succeeds. This keeps a source checkout from being
+misreported as a broken recipe while still preferring a runnable published build.
+
+### Guest source build
+
+`compat_build { spec, backend: "plan" }` returns the exact PC/CI commands. With
+`backend: "guest"` and `confirm: true`, the plugin provisions Node or Rust in
+the Alpine guest and runs the detected command (`cargo build --release`, or
+`npm ci && npm run build && npm pack`). This is experimental: it needs guest
+network, enough guest disk for the toolchain, and a guest-visible source
+directory. A failure returns the exact `apk`/build stderr; fall back to an
+external build and pass the produced artifact to `compat_convert`.
+
+An x86_64 worker is staged as a shell wrapper plus `qemu-x86_64`, a minimal
+x86_64 glibc rootfs, and the original `<worker>-x64`; the wrapper runs QEMU in
+the guest. This makes a `linux-x64` runtime usable without an AArch64 rebuild.
+
+If no worker is supplied, none is found in the package, and the GitHub Release
+has no Linux asset, the result is `needs-native-build` with the cross-build
+command. The adapter never builds the worker itself.
+
+### Building the worker
+
+For a Rust crate under `native/`:
 
 ```sh
-rustup target add aarch64-unknown-linux-musl
-# either
-cross build --release --locked --manifest-path native/Cargo.toml --target aarch64-unknown-linux-musl
-# or
+cargo build --release --locked --manifest-path native/Cargo.toml --target aarch64-unknown-linux-musl
+# or, with a Zig-based cross linker:
 cargo zigbuild --release --locked --manifest-path native/Cargo.toml --target aarch64-unknown-linux-musl
 ```
 
-The Windows/macOS metadata crates are target-gated in `native/Cargo.toml`; the
-portable dependencies are `cap-std`, `cap-fs-ext`, `fs2`, `rustix`, `sha2`,
-`serde`, `serde_json`, `uuid`, `regex`.
+The result must be a static AArch64 musl ELF: `e_machine == 183`, no
+`PT_INTERP`. Dynamic glibc binaries will not start in the Alpine guest.
 
-Stage the result as `runtime/linux-arm64/dsh-ops-worker` with a matching
-`provenance.json` (`version`, `target`, `executable`, `sha256`).
+### Generic sidecar
 
-### 3. Spawn through the guest
+A native worker that follows one-JSON-request / one-JSON-response can also be
+staged and called without patching the plugin's own tool layer:
 
-`lib/file/worker.js` and `lib/ptc/worker.js` call:
-
-```js
-subprocess.spawn({ argv: [file], ... })
-```
-
-`dshm-vm-bash` only redirects `bash -c`, so patch both call sites to:
-
-```js
-argv: ['bash', '-c', 'exec "$0"', file]
+```json
+compat_sidecar { "action": "stage", "tarball": "<converted.tgz>", "workerPath": "runtime/linux-arm64/worker", "id": "my-worker" }
+compat_sidecar { "action": "probe", "id": "my-worker" }
+compat_sidecar { "action": "call", "id": "my-worker", "input": { "ping": true }, "confirm": true }
 ```
 
-The worker path is under the profile's 9p share, so the guest sees the same
-absolute path. If exec from 9p fails on a device, copy the worker to
-`/tmp/dsh-ops-worker` once (hash-keyed) and execute that copy.
-
-### 4. Shell component
-
-`lib/shells/resolve.js` treats every non-win32 host as POSIX and probes the
-**host** for `/bin/bash`. DSHM's host has no bash. Patch the DSHM branch to
-report the guest's `/bin/bash` as available; `ops_bash` then spawns
-`bash -c`, which `dshm-vm-bash` routes into the guest.
-
-Disable the PowerShell rung: the pwsh payload is win32-only.
-
-### 5. PTC vs file
-
-`lib/ptc/worker.js` calls `sandbox.confine()` for non-`danger-full-access`
-policies. If DSHM's sandbox provider cannot confine the worker, PTC tools fail
-closed. The `file` component uses policy checks but no `sandbox.confine`, so
-port `ops_*` file tools first and treat PTC as a later optimization.
-
-### 6. Verification
-
-Run on the device:
-
-- `ops_stat` on a workspace file;
-- `ops_grep` over a small tree;
-- `ops_write_file` then `ops_stat` (check the new revision);
-- `ops_copy` / `ops_move` (9p rename/atomicity);
-- a failure case with a read-only policy.
-
-Watch for `cap-std`/`rustix` failures on 9p (`openat2`, `statx`, `renameat2`,
-`flock`). If those fail, the fallback is a JS reimplementation of the worker
-protocol rather than a guest port.
+Staging checks the worker is an AArch64 ELF and puts it under
+`$DSH_HOME/dshm-compat/sidecars/<id>/`. Calls run through
+`bash -c 'exec "$0" "$@"'`, which `dshm-vm-bash` routes into Alpine.
 
 ## Common native dependencies