dshm-compat 0.1.3 → 0.1.4

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,40 @@
 # Changelog
 
+## 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.
+- Offline regression suite: 27/27.
+
 ## 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.4.tgz`.
+It is host-only, has no runtime dependencies, and adds ten 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.4` 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.4.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.4.tgz /data/storage/el2/base/haps/entry/files/dshm-compat-0.1.4.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.4.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.4 adds a generic S2 native adapter (including an x86_64 worker + bundled
+QEMU fallback and GitHub Release worker acquisition), `compat_doctor`,
+rollback-safe local installs, and codeload fallbacks for GitHub. 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,19 @@ 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.
+  Only when none of these exist does it return `needs-native-build` with the
+  cross-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.
@@ -41,16 +49,24 @@ conversion.
 
 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,18 @@ 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/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,6 +76,7 @@ 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_status` | read-only |
@@ -79,11 +84,12 @@ spec ──► resolve (npm / GitHub / local .tgz)
 ## 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,73 @@
-# Conversion recipes
+# Generic conversion patterns
 
-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.
+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.
 
-## `dsh-ops` (Rust native worker)
+## S2: native worker
 
-Upstream: `T-Auto/dsh-ops`. The core is `native/` (Rust) and the published
-worker is `runtime/<target>/dsh-ops-worker`.
+The generic adapter in `lib/s2-native.js` recognizes the common shape of a
+native DSH plugin:
 
-### 1. Support matrix
+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.
 
-`lib/ptc/runtime.js` hard-codes:
+For each match it:
 
-```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:
+- 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)}`;
+- wraps every standard spawn call in
+  `['bash', '-c', 'exec "$0" "$@"', file]`, which `dshm-vm-bash` routes to the
+  Alpine guest;
+- removes `os`/`cpu`, drops win32/darwin optional payloads, and relaxes
+  `@deepseek-ai/dsh` to `workspace:*`;
+- adds `openharmony`/target/arch to `dsh-plugin.json` component targets;
+- stages the worker at `runtime/<target>/<worker>` with a matching
+  `provenance.json` (`version`, `target`, `executable`, `sha256`).
 
-- 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`.
+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.
 
-Also update:
+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.
 
-- `package.json` `os`/`cpu` (remove the gates or add `openharmony`/`arm64`);
-- `dsh-plugin.json` `platforms`, `architectures`, and `targets` for each
-  `x-components` entry.
+### Building the worker
 
-### 2. Build the worker
-
-From a Linux build host or CI:
+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`.
-
-Stage the result as `runtime/linux-arm64/dsh-ops-worker` with a matching
-`provenance.json` (`version`, `target`, `executable`, `sha256`).
+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.
 
-### 3. Spawn through the guest
+### Generic sidecar
 
-`lib/file/worker.js` and `lib/ptc/worker.js` call:
+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:
 
-```js
-subprocess.spawn({ argv: [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 }
 ```
 
-`dshm-vm-bash` only redirects `bash -c`, so patch both call sites to:
-
-```js
-argv: ['bash', '-c', 'exec "$0"', file]
-```
-
-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
 

package/index.js

@@ -15,6 +15,7 @@ import { probeGuest, provisionGuest } from './lib/guest.js'
 import { enqueueInstall } from './lib/install.js'
 import { installLocalTarball, isLocalSpec } from './lib/local-install.js'
 import { buildPlan } from './lib/plan.js'
+import { callSidecar, listSidecars, probeSidecar, stageSidecar } from './lib/sidecar.js'
 import { recordInstall, recordReport, status } from './lib/state.js'
 
 export const name = 'dshm-compat'
@@ -152,7 +153,7 @@ export function apply(ctx) {
         profileDir: { type: 'string', description: 'Absolute DSHM profile directory for install:true. Omit to let the host choose.' },
         confirm: { type: 'boolean', description: 'Required when install is true. Confirms that installing the converted package runs third-party code.' },
         vendor: { type: 'boolean', description: 'Vendor missing pure-JS runtime dependencies into the tarball. Default true.' },
-        workerPath: { type: 'string', description: 'Absolute path to a prebuilt AArch64 Linux worker for recipes that need one (currently dsh-ops). Omit to receive the build command instead.' },
+        workerPath: { type: 'string', description: 'Absolute path to a prebuilt AArch64 Linux worker for an S2 plugin. Omit to let the generic adapter return the build command.' },
         allowLocal: { type: 'boolean', description: 'When install is true, unpack the converted tarball into the profile instead of the host queue. Default true; set false to force the queue.' },
       },
       required: ['spec'],
@@ -232,6 +233,50 @@ export function apply(ctx) {
     },
   ), 'compat_guest_provision')
 
+  register(definition(
+    'compat_sidecar',
+    'Stage and call a native Linux/AArch64 worker in the DSHM Alpine guest. Actions: stage (extract a worker from a converted tarball into $DSH_HOME/dshm-compat/sidecars/<id>), list, probe (run --version), call (one JSON request on stdin, one JSON value on stdout; requires confirm:true). '
+      + 'This is the generic S2 bridge; the worker runs through bash -c and is routed to the guest by dshm-vm-bash.',
+    {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['stage', 'list', 'probe', 'call'] },
+        id: { type: 'string', description: 'Sidecar id (letters, digits, dot, underscore, dash).' },
+        tarball: { type: 'string', description: 'Converted package tarball containing the worker.' },
+        workerPath: { type: 'string', description: 'Worker path inside the tarball, e.g. runtime/linux-arm64/<worker>.' },
+        input: { type: 'object', additionalProperties: true, description: 'JSON request for action=call. Default {}.' },
+        timeoutMs: { type: 'integer', description: 'Per-call timeout. Default 120000.' },
+        confirm: { type: 'boolean', description: 'Required for action=call: confirms that the worker runs native code in the guest.' },
+      },
+      required: ['action'],
+      additionalProperties: false,
+    },
+    async (args, exec) => {
+      try {
+        if (args?.action === 'stage') {
+          if (typeof args.tarball !== 'string' || typeof args.workerPath !== 'string') {
+            return { status: 'error', error: { code: 'INVALID_ARGUMENT', message: 'stage requires tarball and workerPath' } }
+          }
+          const result = stageSidecar(args.tarball, args.workerPath, { id: args.id })
+          return result.ok ? { status: 'ok', ...result } : { status: 'error', ...result }
+        }
+        if (args?.action === 'list') return { status: 'ok', sidecars: listSidecars() }
+        if (args?.action === 'probe') {
+          if (typeof args.id !== 'string') return { status: 'error', error: { code: 'INVALID_ARGUMENT', message: 'probe requires id' } }
+          return { status: 'ok', ...(await probeSidecar(ctx, args.id, { timeoutMs: args.timeoutMs, signal: exec?.signal })) }
+        }
+        if (args?.action === 'call') {
+          if (typeof args.id !== 'string') return { status: 'error', error: { code: 'INVALID_ARGUMENT', message: 'call requires id' } }
+          if (args.confirm !== true) return { status: 'confirmation-required', message: 'Re-run with confirm:true to execute the worker in the guest.' }
+          return { status: 'ok', ...(await callSidecar(ctx, args.id, args.input ?? {}, { timeoutMs: args.timeoutMs, signal: exec?.signal })) }
+        }
+        return { status: 'error', error: { code: 'INVALID_ACTION', message: `unknown sidecar action: ${String(args?.action)}` } }
+      } catch (error) {
+        return errorResult(error)
+      }
+    },
+  ), 'compat_sidecar')
+
   register(definition(
     'compat_install',
     'Install an already-built plugin artifact. Local .tgz paths (or file:/link: paths) are unpacked into the owning DSH profile and its bundle list, because DSHM\'s host queue rejects local specs; npm names and GitHub repositories still go through the host install queue. '

package/lib/analyze.js

@@ -245,10 +245,11 @@ export async function analyze(spec, options = {}) {
     confidence = 'high'
     reasons.push('the archive carries only win32 payloads and no C/C++/Rust source to rebuild')
     next.push('ask the plugin author for source or a linux-arm64 build')
-  } else if (nativeFiles.length > 0 || unknownNativeDeps.length > 0 || electronSurface) {
+  } else if (nativeFiles.length > 0 || unknownNativeDeps.length > 0 || electronSurface || hasNativeSource) {
     strategy = 'S2'
     confidence = 'medium'
     if (nativeFiles.length > 0) reasons.push(`${nativeFiles.length} native file(s) need a linux-arm64 runtime outside the DSHM host process`)
+    if (hasNativeSource && nativeFiles.length === 0) reasons.push('native source needs a Linux/guest build; no prebuilt runtime is present')
     if (unknownNativeDeps.length > 0) reasons.push(`unrecognized native dependencies: ${unknownNativeDeps.map(dep => dep.name).join(', ')}`)
     if (Object.keys(installScripts).length > 0) reasons.push(`install scripts: ${Object.keys(installScripts).join(', ')}`)
     if (electronSurface) reasons.push(`Electron API surface detected (${scan.electron} reference(s)); needs a shim or a sidecar UI`)
@@ -360,6 +361,10 @@ export async function analyze(spec, options = {}) {
       },
       nativeDeps,
       unknownNativeDeps: unknownNativeDeps.map(dep => dep.name),
+      nativeSource: hasNativeSource,
+      rustSource: files.some(file => /(?:^|\/)Cargo\.toml$/.test(file.path) || /\.rs$/.test(file.path)),
+      cSource: files.some(file => /\.(?:c|cc|cpp)$/.test(file.path)),
+      nodeGyp: files.some(file => /(?:^|\/)binding\.gyp$/.test(file.path)),
       dependencies: {
         core: dependencyCheck.core,
         present: dependencyCheck.present.slice(0, 100),

package/lib/convert.js

@@ -47,12 +47,13 @@ function safeName(name) {
  */
 export async function convert(spec, options = {}) {
   const report = options.report ?? await analyze(spec, { textScan: false, signal: options.signal, registry: options.registry })
-  if (report.package?.name === 'dsh-ops' && report.rule?.nativeBuild?.language === 'rust') {
-    const { convertDshOps } = await import('./recipes/dsh-ops.js')
-    return await convertDshOps(spec, {
+  if (report.strategy === 'S2') {
+    const { convertS2Native } = await import('./s2-native.js')
+    return await convertS2Native(spec, {
       report,
       workerPath: options.workerPath,
       workerBinary: options.workerBinary,
+      workerName: options.workerName,
       signal: options.signal,
     })
   }

package/lib/elf.js

@@ -0,0 +1,41 @@
+/**
+ * Minimal AArch64 ELF checks shared by the generic S2 adapter and the generic
+ * sidecar staging path.
+ *
+ * @module dshm-compat/elf
+ */
+
+/** @param {Buffer} buffer */
+export function isAarch64Elf(buffer) {
+  return buffer.length >= 64
+    && buffer[0] === 0x7f && buffer[1] === 0x45 && buffer[2] === 0x4c && buffer[3] === 0x46
+    && buffer[4] === 2 && buffer[5] === 1
+    && buffer.readUInt16LE(18) === 183
+}
+
+/** @param {Buffer} buffer */
+export function isX64Elf(buffer) {
+  return buffer.length >= 64
+    && buffer[0] === 0x7f && buffer[1] === 0x45 && buffer[2] === 0x4c && buffer[3] === 0x46
+    && buffer[4] === 2 && buffer[5] === 1
+    && buffer.readUInt16LE(18) === 62
+}
+
+/** @param {Buffer} buffer @returns {'arm64'|'x64'|undefined} */
+export function elfArch(buffer) {
+  if (isAarch64Elf(buffer)) return 'arm64'
+  if (isX64Elf(buffer)) return 'x64'
+  return undefined
+}
+
+/** @param {Buffer} buffer */
+export function elfSummary(buffer) {
+  if (!isAarch64Elf(buffer)) return undefined
+  return {
+    class: 64,
+    endian: 'little',
+    machine: 'AArch64',
+    type: buffer.readUInt16LE(16) === 3 ? 'DYN' : buffer.readUInt16LE(16) === 2 ? 'EXEC' : String(buffer.readUInt16LE(16)),
+    bytes: buffer.length,
+  }
+}

package/lib/guest.js

@@ -8,6 +8,8 @@
  *
  * @module dshm-compat/guest
  */
+import { isAbsolute } from 'node:path'
+
 const PROBE_SCRIPT = [
   'echo DSHM_COMPAT_PROBE_BEGIN',
   'uname -srm 2>/dev/null || true',
@@ -19,7 +21,6 @@ const PROBE_SCRIPT = [
   'command -v python3 || true',
   'echo DSHM_COMPAT_PROBE_END',
 ].join('\n')
-
 /** Packages the provisioning tool may install. */
 export const PROVISION_PACKAGES = Object.freeze([
   'bash',
@@ -98,7 +99,7 @@ export async function runGuest(ctx, script, options = {}) {
  * @param {{ timeoutMs?: number, signal?: AbortSignal, cwd?: string }} [options]
  */
 export async function runGuestFile(ctx, file, args = [], input = '', options = {}) {
-  if (typeof file !== 'string' || !file.startsWith('/')) {
+  if (typeof file !== 'string' || !isAbsolute(file)) {
     return { status: 'invalid', reason: 'worker path must be absolute and visible inside the guest' }
   }
   const subprocess = ctx.get('subprocess')

package/lib/plan.js

@@ -18,6 +18,16 @@ function record(value) {
 function nativeBuildOf(report) {
   const rule = record(report.rule)
   if (record(rule?.nativeBuild) !== undefined) return rule.nativeBuild
+  const signals = record(report.signals) ?? {}
+  if (signals.nodeGyp === true) {
+    return { language: 'node-gyp', target: 'aarch64-unknown-linux-musl', notes: 'build in the Alpine guest with build-base and python3' }
+  }
+  if (signals.rustSource === true) {
+    return { language: 'rust', target: 'aarch64-unknown-linux-musl' }
+  }
+  if (signals.cSource === true) {
+    return { language: 'c/c++', target: 'aarch64-unknown-linux-musl', notes: 'build in the Alpine guest' }
+  }
   const native = Array.isArray(report.files?.native) ? report.files.native : []
   if (native.some(file => typeof file.path === 'string' && file.path.endsWith('binding.gyp'))) {
     return { language: 'node-gyp', target: 'aarch64-unknown-linux-musl', notes: 'build in the Alpine guest with build-base and python3' }