@wenathlan/saddle 2.0.150 → 2.0.151

package/Dockerfile

@@ -13,7 +13,7 @@
 #      compute service published as ghcr.io/wenathlan/saddle:<version>
 #      across the four-arch family standard (amd64, arm64, ppc64le, s390x
 #      — the trixie slim base line; the stage also builds the web SPA so
-#      the image serves the self-hosted console via `node /app/web/server.ts`).
+#      the image serves the self-hosted console via `node /app/webserver.ts`).
 #
 # saddle v2 (grand merge) - virtual hardware engine, multi-stage, multi-arch image.
 #
@@ -641,17 +641,20 @@ ENTRYPOINT ["/usr/bin/tini", "--", "qemu-system-x86_64"]
 # ---------------------------------------------------------------------------
 # saddle-build: the node-engine build stage (defined here, before the
 # vhe runtime, so BOTH container surfaces can consume its output: the
-# vhe runtime copies the built web SPA for its /engine/web console and
-# the saddle-runtime stage copies the engine dist plus the same web
-# tree - one build, two consumers). The stage runs native (never under
-# QEMU): its outputs are platform-independent static/js payloads.
+# vhe runtime copies the built web SPA beside the console server at
+# /engine and the saddle-runtime stage copies the engine dist plus the
+# same staged SPA - one build, two consumers). The stage runs native
+# (never under QEMU): its outputs are platform-independent static/js
+# payloads.
 
 # the build stage pins to the native build platform ($BUILDPLATFORM): its
 # outputs (the engine dist, pure js, and the web SPA, static assets) are
 # architecture-independent, while the tailwind/lightningcss pipeline only
 # ships native bindings for the builder platforms - the per-arch legs never
-# run it under QEMU.
-FROM --platform=$BUILDPLATFORM node:26.8.1-slim@sha256:c0753125a3789977aefe869cbebccf70e3cfd7ea84ca48547458f02e4f1d7146 AS saddle-build
+# run it under QEMU. The base rides the family tag contract (tags only,
+# never a @sha256: digest - a single digest cannot serve the
+# four-architecture matrix the registry resolves per platform).
+FROM --platform=$BUILDPLATFORM node:26.8.1-slim AS saddle-build
 
 ARG SADDLE_VERSION
 WORKDIR /app
@@ -663,7 +666,16 @@ RUN npm ci --ignore-scripts --legacy-peer-deps
 COPY . .
 RUN npm run build:engine \
     && node --check dist/cli.js \
-    && npm run web:build:pages
+    && npm run web:build:pages \
+    # the theme build emits the hashed SPA bundles straight at the app
+    # root (the family static-first vite contract): stage them into a
+    # clean folder so the runtime stages copy exactly the console
+    # surface - the shell, the hashed js/css bundles and the icon and
+    # manifest assets the shell references. the extension popup
+    # stylesheet is the one root css that never belongs to the spa.
+    && mkdir -p /out/spa \
+    && cp index.html *.js *.css *.svg *.webmanifest /out/spa/ \
+    && rm -f /out/spa/popup.css
 
 FROM ${UBUNTU} AS runtime
 ARG TARGETARCH
@@ -895,19 +907,24 @@ COPY --from=python-bridge /bridge/qemubridge.py /engine/qemubridge.py
 # the engine sources and the specification files consumed at runtime
 # (docker.config "final" stage copies the whole tree; the flat layout
 # keeps that a single COPY layer).
-COPY *.ts package.json tsconfig.json biome.json jsdom.d.ts /engine/
+COPY *.ts package.json tsconfig.json biome.jsonc jsdom.d.ts /engine/
 COPY processors.json gpus.json cores.json boards.json vm.config.json virtualhardware.json /engine/
-COPY qemu.config mttg.config passage.config docker.config /engine/
+COPY qemu.config mttg.config passage.config docker.config mime.types /engine/
 
 # the web node ships inside the main container: the mesh edition (auth,
 # sqlite database, dashboard and the browser sandbox pages) runs from the
 # same image, so one container serves the engine AND the web surface.
-# run it with: docker run ghcr.io/wenathlan/saddle node /engine/web/server.ts
-COPY web /engine/web
-# the built web SPA (vite, from the saddle-build stage): the console
-# server (node /engine/web/server.ts) serves web/dist/public - the
-# unified React interface that absorbed the former static pages.
-COPY --from=saddle-build /app/web/dist /engine/web/dist
+# run it with: docker run ghcr.io/wenathlan/saddle node /engine/webserver.ts
+# (the console server is a root engine source - the COPY *.ts line above
+# already lands it at /engine together with its console stack, and the
+# extension denylist of its static resolver keeps every .ts/.json/.sql
+# source unreachable).
+# the built web SPA (vite, staged by saddle-build): the theme build emits
+# the hashed bundles straight at the app root, so the staged spa lands
+# beside the console server at /engine and webserver.ts serves it from
+# its own module directory - the unified React interface that absorbed
+# the former static pages.
+COPY --from=saddle-build /out/spa /engine/
 
 RUN set -eux; \
     chmod 0755 /usr/local/bin/nvidia-smi /usr/local/bin/aetherforge; \
@@ -1310,7 +1327,7 @@ ENTRYPOINT ["/entrypoint.sh"]
 #   docker build --target saddle-runtime -t saddle:<version> .
 # ══════════════════════════════════════════════════════════════════════
 
-FROM node:26.8.1-slim@sha256:c0753125a3789977aefe869cbebccf70e3cfd7ea84ca48547458f02e4f1d7146 AS saddle-runtime
+FROM node:26.8.1-slim AS saddle-runtime
 
 ARG SADDLE_VERSION
 LABEL org.opencontainers.image.title="Saddle" \
@@ -1357,12 +1374,15 @@ RUN apt-get update \
     && rm -rf node_modules/cpu-features/deps \
     && find node_modules -type f -name Dockerfile -delete
 COPY --from=saddle-build /app/dist ./dist
-# the web service surface (self-hosted console): the built SPA
-# (web/dist/public from the saddle-build vite run) plus the pure-node
-# server stack (server.ts, db.ts, auth.ts, mesh.ts, sandbox.ts,
-# mime.types, init.sql, schema.prisma) - zero npm dependencies, the
-# node 26 runtime carries everything (node:sqlite, node:crypto).
-COPY --from=saddle-build /app/web ./web
+# the web service surface (self-hosted console): the staged spa plus the
+# pure-node server stack (webserver.ts, db.ts, labels.ts, auth.ts,
+# mesh.ts, sandbox.ts, sandboxprofile.ts, sandboxenvprofile.ts,
+# sandboxquota.ts, mime.types, init.sql, schema.prisma) - zero npm
+# dependencies, the node 26 runtime carries everything (node:sqlite,
+# node:crypto, native type stripping for the .ts sources).
+# run the console with: docker run saddle:<version> node webserver.ts
+COPY --from=saddle-build /app/webserver.ts /app/db.ts /app/labels.ts /app/auth.ts /app/mesh.ts /app/sandbox.ts /app/sandboxprofile.ts /app/sandboxenvprofile.ts /app/sandboxquota.ts /app/mime.types /app/init.sql /app/schema.prisma ./
+COPY --from=saddle-build /out/spa ./
 
 USER node
 

package/README.md

@@ -31,7 +31,7 @@ domain modules land beside the saddle domains:
 | `media.ts`, `render.ts`, `quantum.ts`, `tiers.ts` | media pipeline, GPU registry, quantum simulation, tier policy |
 | `security.ts`, `alternatives.ts` | hardening gates and the alternative-stack catalog |
 | `index.html`, `App.tsx`, `Sol/` | the single SPA shell and the Sol theme (one tsx app with one stylesheet per theme) |
-| `server.ts`, `sandbox.ts` | the zero-dependency self-hosted API of the 2.0.150 grand-merge envelope (`node server.ts`; the api answers its version at `/api/v1/health`) and the browser-pure engine port |
+| `server.ts`, `sandbox.ts` | the zero-dependency self-hosted API of the 2.0.151 grand-merge envelope (`node server.ts`; the api answers its version at `/api/v1/health`) and the browser-pure engine port |
 | `vercel.json`, `netlify.toml` | the platform deploy adapters beside the surface they publish (the caddy ghost stays out of the tree) |
 | `specs/*` package exports | processors, gpus, cores, boards and the qemu/mttg/passage/docker envelopes |
 
@@ -234,7 +234,7 @@ npm run web:check
 VITE_BASE_PATH=/saddle npm run web:build:pages
 ```
 
-Small public configuration and visual assets live under `web/public/`. The development collector is TypeScript source at `web/debugcollector.ts`, injected only in development, and uses `/debuglogs`; it is not part of the production build. The obsolete `web/public/__manus__` directory is intentionally absent.
+Small public configuration and visual assets live under `web/public/`. The obsolete `web/public/__manus__` directory is intentionally absent; the development debug collector (the visitor-browser telemetry hook at the former `web/debugcollector.ts`) left the saddle together with the scrape lanes — the engine keeps no surface that watches the user's browser.
 
 ## Development
 

package/biome.jsonc

@@ -0,0 +1,127 @@
+// the family biome baseline: identical across the apps, the identity only names the app.
+{
+  "$schema": "https://biomejs.dev/schemas/2.6.3/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "includes": [
+      "**/*.ts",
+      "**/*.tsx",
+      "**/*.js",
+      "**/*.mjs",
+      "**/*.cjs",
+      "**/*.css",
+      "**/*.json",
+      "!**/dist",
+      "!**/distpackage",
+      "!**/target",
+      "!**/node_modules",
+      "!**/bun.lock",
+      "!**/*.min.js",
+      "!**/docs",
+      "!**/tests/tmp",
+      "!**/tests/code",
+      "!**/Sol/dist"
+    ]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120,
+    "lineEnding": "lf"
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "correctness": {
+        "noUnusedVariables": "warn",
+        "noUnsafeOptionalChaining": "warn",
+        "useExhaustiveDependencies": "warn",
+        "noUnusedImports": "warn",
+        "noUnusedPrivateClassMembers": "warn",
+        "noUnusedFunctionParameters": "warn",
+        "noConstantCondition": "warn",
+        "noVoidTypeReturn": "warn"
+      },
+      "a11y": {
+        "useButtonType": "warn",
+        "noStaticElementInteractions": "warn",
+        "useSemanticElements": "warn",
+        "useAriaPropsSupportedByRole": "warn"
+      },
+      "suspicious": {
+        "noExplicitAny": "warn",
+        "noArrayIndexKey": "warn",
+        "noControlCharactersInRegex": "warn",
+        "noRedeclare": "warn",
+        "noAssignInExpressions": "warn",
+        "noShadowRestrictedNames": "warn",
+        "noDuplicateElseIf": "warn",
+        "noImplicitAnyLet": "warn",
+        "noTsIgnore": "warn",
+        "noGlobalIsNan": "warn"
+      },
+      "style": {
+        "noNonNullAssertion": "warn",
+        "useTemplate": "warn",
+        "useExponentiationOperator": "warn",
+        "useConst": "warn"
+      },
+      "complexity": {
+        "useLiteralKeys": "warn",
+        "useOptionalChain": "warn",
+        "noUselessContinue": "warn",
+        "noUselessUndefinedInitialization": "warn",
+        "noUselessEscapeInRegex": "warn"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all",
+      "arrowParentheses": "always"
+    }
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  },
+  "overrides": [
+    {
+      "includes": ["**/*"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noDebugger": "off"
+          }
+        }
+      }
+    },
+    {
+      "includes": ["tests/workflowcheck.ts"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noTemplateCurlyInString": "off"
+          }
+        }
+      }
+    }
+  ],
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "useSortedKeys": "off"
+      }
+    }
+  }
+}

package/docker.config

@@ -106,11 +106,14 @@
   "platforms": {
     "architectures": [
       "linux/amd64",
-      "linux/arm64"
+      "linux/arm64",
+      "linux/ppc64le",
+      "linux/s390x"
     ],
     "primary": "linux/amd64",
-    "qemuEmulation": false,
-    "nativeBuild": true
+    "qemuEmulation": true,
+    "nativeBuild": true,
+    "note": "the four-arch family standard (amd64, arm64, ppc64le, s390x) the one container file and the publish lanes carry; amd64 builds native, the other legs ride QEMU emulation; unknown/* stays rejected as not runnable"
   },
   "runtimeBase": {
     "nodeImage": "node:26.7.0-alpine",
@@ -468,9 +471,11 @@
     "multiArch": {
       "platforms": [
         "linux/amd64",
-        "linux/arm64"
+        "linux/arm64",
+        "linux/ppc64le",
+        "linux/s390x"
       ],
-      "command": "docker buildx build --platform linux/amd64,linux/arm64 --cache-from type=gha --cache-to type=gha,mode=max --push -t ghcr.io/vhe/sandbox:29.7.2 ."
+      "command": "docker buildx build --platform linux/amd64,linux/arm64,linux/ppc64le,linux/s390x --cache-from type=gha --cache-to type=gha,mode=max --push -t ghcr.io/vhe/sandbox:29.7.2 ."
     },
     "actionsWorkflowUses": [
       "docker/setup-buildx-action@v4.3.0",
@@ -655,7 +660,9 @@
     "target": "runtime-base",
     "platforms": [
       "linux/amd64",
-      "linux/arm64"
+      "linux/arm64",
+      "linux/ppc64le",
+      "linux/s390x"
     ],
     "cacheFrom": [
       "type=gha",

package/index.ts

@@ -1462,7 +1462,6 @@ export * from './virtualmemory.js';
 
 /* ── Section 2: the saddle domain routing barrel ── */
 
-export * from './acquisition.js';
 export * from './automation.js';
 export * from './browser.js';
 export * from './communication.js';
@@ -1472,6 +1471,8 @@ export * from './foundation.js';
 export * from './integration.js';
 export * from './intelligence.js';
 export * from './isolation.js';
+/** Re-exports the sandbox modality registry — the catalog the join
+ * resolver reads (the spine of the sandbox modalities the engine opens). */
+export * from './modalityregistry.js';
 export * from './modes.js';
-export * from './operations.js';
 export * from './virtual.js';

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Saddle browser bridge",
-  "version": "2.0.150",
+  "version": "2.0.151",
   "description": "User initiated page snapshots through the Saddle browser contract.",
   "minimum_chrome_version": "110",
   "permissions": [

package/modalityregistry.ts

@@ -0,0 +1,156 @@
+// # modalityregistry — the catalog of the sandbox modalities the saddle
+// engine opens (root layer, wave SV1). One record per modality: the
+// isolation family, the driver requirements it mounts, the boot cost class,
+// the hardening gates it carries and the mime contract it answers. The
+// registry is the spine of the "fifty modalities" promise: the workload
+// never chooses by name — the join resolver reads the request (isolation,
+// gpu, network, boot budget) and answers the modality set that satisfies
+// it, so the person chooses none and the platform resolves the join of all
+// (the nuclear modality law). Pure data and pure functions: zero storage,
+// zero node-only imports, the browser-pure bundle keeps carrying it.
+
+/** The boot cost classes the ladder measures. */
+export type BootClass = "hot" | "warm" | "cold";
+
+/** The isolation families the modalities group under. */
+export type ModalityFamily =
+  | "virtual"
+  | "runner"
+  | "packages"
+  | "container"
+  | "microvm"
+  | "browser"
+  | "mobile"
+  | "confidential"
+  | "emulator"
+  | "pod"
+  | "local"
+  | "screen"
+  | "wasm"
+  | "fs"
+  | "delivery";
+
+/** One sandbox modality of the registry. */
+export interface ModalityRecord {
+  /** The stable id the api and the config rows reference. */
+  id: string;
+  /** The display label (short, lowercase). */
+  label: string;
+  /** The isolation family the modality belongs to. */
+  family: ModalityFamily;
+  /** The isolation depth the family reaches (the capability contract). */
+  isolation: "process" | "namespace" | "vm" | "hardware";
+  /** The driver modules the modality mounts when it boots. */
+  drivers: readonly string[];
+  /** The hardening gates the modality enforces by default. */
+  hardening: readonly string[];
+  /** The boot cost class (the measured budget lives in the boot ladder). */
+  boot: BootClass;
+  /** The measured boot budget in milliseconds (the ladder answers). */
+  bootms: number;
+  /** Whether the modality presents a gpu through the virtual drivers. */
+  gpu: boolean;
+  /** Whether the modality opens a network path (the hardened default is off). */
+  network: boolean;
+  /** The mime type the modality's api surface answers. */
+  mime: string;
+}
+
+/** The boot budgets of the ladder, per class: the ceilings the records walk
+ * under (firecracker 125 ms and gvisor about 200 ms ride warm, the full
+ * machine images ride cold). */
+export const BOOTLADDER: Readonly<Record<BootClass, number>> = Object.freeze({
+  hot: 25,
+  warm: 800,
+  cold: 1500,
+});
+
+/** The modality records: the catalog the join resolver reads. */
+export const MODALITIES: readonly ModalityRecord[] = Object.freeze([
+  // the virtual family: the full machine with the virtual drivers
+  { id: "virtual-full", label: "complete virtual", family: "virtual", isolation: "hardware", drivers: ["virtualcpu", "virtualgpu", "virtualmemory"], hardening: ["profile-lock"], boot: "cold", bootms: BOOTLADDER.cold, gpu: true, network: true, mime: "application/vnd.devthink.sandbox+json" },
+  { id: "virtual-vgpu", label: "vgpu slice", family: "virtual", isolation: "hardware", drivers: ["virtualgpu", "nvml-shim", "vfio"], hardening: ["mig-profile"], boot: "warm", bootms: 600, gpu: true, network: true, mime: "application/vnd.devthink.sandbox+json" },
+  { id: "virtual-screen", label: "vm plus vnc", family: "screen", isolation: "vm", drivers: ["virtualcpu", "virtualgpu", "xvfb", "looking-glass"], hardening: ["session-otp"], boot: "warm", bootms: 700, gpu: true, network: true, mime: "application/vnd.devthink.screen+json" },
+  // the runner family: the universal binary runner
+  { id: "runner-universal", label: "universal runner", family: "runner", isolation: "namespace", drivers: ["binfmt"], hardening: ["read-only-root", "dropped-caps"], boot: "warm", bootms: BOOTLADDER.warm, gpu: false, network: true, mime: "application/vnd.devthink.run+json" },
+  { id: "runner-node", label: "node packages", family: "packages", isolation: "process", drivers: ["node", "babel", "swc"], hardening: ["package-allowlist"], boot: "hot", bootms: BOOTLADDER.hot, gpu: false, network: true, mime: "application/vnd.devthink.run+json" },
+  { id: "runner-wasm", label: "wasm and wasi", family: "wasm", isolation: "process", drivers: ["wasmer", "wasmedge"], hardening: ["capability-imports"], boot: "hot", bootms: 15, gpu: false, network: false, mime: "application/wasm" },
+  { id: "runner-serverless", label: "v8 isolates", family: "runner", isolation: "process", drivers: ["v8"], hardening: ["no-fs", "cpu-quota"], boot: "hot", bootms: 8, gpu: false, network: true, mime: "application/vnd.devthink.run+json" },
+  // the container family: docker hardened and ghcr immutable
+  { id: "container-docker", label: "docker hardened", family: "container", isolation: "namespace", drivers: ["docker"], hardening: ["no-network", "dropped-caps", "read-only-root", "pid-limit"], boot: "warm", bootms: 400, gpu: false, network: false, mime: "application/vnd.devthink.container+json" },
+  { id: "container-ghcr", label: "ghcr immutable", family: "container", isolation: "namespace", drivers: ["docker", "ghcr"], hardening: ["immutable-root", "uuid-instance"], boot: "warm", bootms: 450, gpu: false, network: true, mime: "application/vnd.devthink.container+json" },
+  { id: "container-runsc", label: "gvisor sandboxed", family: "container", isolation: "namespace", drivers: ["runsc"], hardening: ["user-kernel"], boot: "warm", bootms: BOOTLADDER.warm, gpu: false, network: true, mime: "application/vnd.devthink.container+json" },
+  // the microvm family: per workflow, the e2b form
+  { id: "microvm-firecracker", label: "firecracker microvm", family: "microvm", isolation: "vm", drivers: ["firecracker", "virtualcpu"], hardening: ["clean-rootfs", "injected-vcpu"], boot: "warm", bootms: 125, gpu: false, network: true, mime: "application/vnd.devthink.microvm+json" },
+  { id: "microvm-gpuless", label: "gpuless render", family: "microvm", isolation: "vm", drivers: ["mesa-llvmpipe", "lavapipe", "rusticl", "xvfb"], hardening: ["clean-rootfs"], boot: "warm", bootms: 500, gpu: true, network: true, mime: "application/vnd.devthink.microvm+json" },
+  // the pod family: one pod per session (the competitor recipe)
+  { id: "pod-session", label: "pod per session", family: "pod", isolation: "namespace", drivers: ["k8s"], hardening: ["quota-check"], boot: "warm", bootms: 800, gpu: false, network: true, mime: "application/vnd.devthink.pod+json" },
+  // the confidential family: attested compute
+  { id: "confidential-sevsnp", label: "sev snp", family: "confidential", isolation: "hardware", drivers: ["sev-snp", "tpm"], hardening: ["attestation"], boot: "cold", bootms: 1200, gpu: false, network: true, mime: "application/vnd.devthink.confidential+json" },
+  { id: "confidential-tdx", label: "tdx", family: "confidential", isolation: "hardware", drivers: ["tdx", "tpm"], hardening: ["attestation"], boot: "cold", bootms: 1200, gpu: false, network: true, mime: "application/vnd.devthink.confidential+json" },
+  // the emulator family: qemu full emulation
+  { id: "emulator-qemu", label: "qemu", family: "emulator", isolation: "vm", drivers: ["qemu"], hardening: ["tcg"], boot: "cold", bootms: 900, gpu: false, network: true, mime: "application/vnd.devthink.emulator+json" },
+  // the browser family: the sandbox-side browser (never the person's)
+  { id: "browser-server", label: "virtual browser", family: "browser", isolation: "namespace", drivers: ["chromium-headless", "playwright"], hardening: ["sandboxed-tabs"], boot: "warm", bootms: 300, gpu: false, network: true, mime: "application/vnd.devthink.browser+json" },
+  { id: "browser-webcontainer", label: "webcontainer server side", family: "browser", isolation: "namespace", drivers: ["node", "wasm"], hardening: ["opt-in"], boot: "warm", bootms: 350, gpu: false, network: true, mime: "application/vnd.devthink.browser+json" },
+  // the mobile family: the os images of the mobile lane
+  { id: "mobile-capacitor", label: "capacitor", family: "mobile", isolation: "namespace", drivers: ["capacitor"], hardening: ["emulated-device"], boot: "warm", bootms: 600, gpu: false, network: true, mime: "application/vnd.devthink.mobile+json" },
+  { id: "mobile-termux", label: "termux", family: "mobile", isolation: "namespace", drivers: ["termux"], hardening: ["emulated-device"], boot: "warm", bootms: 550, gpu: false, network: true, mime: "application/vnd.devthink.mobile+json" },
+  { id: "mobile-postmarketos", label: "postmarketos", family: "mobile", isolation: "vm", drivers: ["qemu"], hardening: ["emulated-device"], boot: "cold", bootms: 1000, gpu: false, network: true, mime: "application/vnd.devthink.mobile+json" },
+  // the fs and delivery families: the vfs and the cdn lane
+  { id: "fs-vfs", label: "vfs", family: "fs", isolation: "process", drivers: ["vfs"], hardening: ["chunk-catalog"], boot: "hot", bootms: 5, gpu: false, network: false, mime: "application/vnd.devthink.vfs+json" },
+  { id: "delivery-cdn", label: "cdn mirror", family: "delivery", isolation: "process", drivers: ["vfs", "cdn"], hardening: ["inside-sandbox-fetch"], boot: "hot", bootms: 5, gpu: false, network: true, mime: "application/vnd.devthink.cdn+json" },
+  { id: "local-optin", label: "local opt in", family: "local", isolation: "process", drivers: [], hardening: ["explicit-consent"], boot: "hot", bootms: 10, gpu: false, network: false, mime: "application/vnd.devthink.local+json" },
+]);
+
+/** The base profiles the owner names (the config wave makes them editable). */
+export type BaseProfile = "max" | "balanced" | "lite";
+
+/** The join request: what the workload asks, never a modality name. */
+export interface JoinRequest {
+  /** The base profile the sandbox boots under. */
+  base: BaseProfile;
+  /** Whether the workload needs a gpu path through the virtual drivers. */
+  gpu: boolean;
+  /** Whether the workload needs a network path. */
+  network: boolean;
+  /** The isolation depth the workload demands at minimum. */
+  isolation?: ModalityRecord["isolation"];
+  /** The boot budget the workload tolerates, in milliseconds. */
+  bootbudget?: number;
+  /** The family the workload prefers (the first filter when given). */
+  family?: ModalityFamily;
+}
+
+/**
+ * Resolves the modality join for a request: the records that satisfy every
+ * demand, ordered by boot cost then isolation depth — the platform answers
+ * the join, the person never names a modality (the nuclear law).
+ *
+ * @param request the workload demands.
+ * @returns the modality records that satisfy the join, best candidate first.
+ */
+export function resolvejoin(request: JoinRequest): readonly ModalityRecord[] {
+  const budget = request.bootbudget ?? BOOTLADDER.cold;
+  const order: Record<ModalityRecord["isolation"], number> = { process: 0, namespace: 1, vm: 2, hardware: 3 };
+  return MODALITIES.filter((modality) => {
+    if (request.family && modality.family !== request.family) return false;
+    if (request.gpu && !modality.gpu) return false;
+    if (request.network && !modality.network) return false;
+    if (request.isolation && order[modality.isolation] < order[request.isolation]) return false;
+    if (modality.bootms > budget) return false;
+    // the lite base keeps the heavy machine images out of the answer
+    if (request.base === "lite" && modality.isolation === "hardware") return false;
+    return true;
+  }).sort((a, b) => a.bootms - b.bootms || order[a.isolation] - order[b.isolation]);
+}
+
+/**
+ * Answers one modality by id (the config rows and the api carry ids).
+ *
+ * @param id the modality id.
+ * @returns the record, or undefined when the id is unknown.
+ */
+export function getmodality(id: string): ModalityRecord | undefined {
+  return MODALITIES.find((modality) => modality.id === id);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/saddle",
-  "version": "2.0.150",
+  "version": "2.0.151",
   "description": "binary computing engine that turns distributed storage into a publishable working set carrying the merged virtual-hardware engine (the saddle + e2ugh grand merge)",
   "type": "module",
   "private": false,
@@ -102,17 +102,16 @@
     "./modes": "./dist/modes.js",
     "./mode": "./dist/modes.js",
     "./sandbox": "./dist/sandbox.js",
+    "./modalities": "./dist/modalityregistry.js",
     "./browser": "./dist/browser.js",
     "./browser-playwright": "./dist/browser.js",
     "./bot": "./dist/automation.js",
-    "./captcha": "./dist/acquisition.js",
     "./deploy": "./dist/modes.js",
     "./extension": "./dist/browser.js",
     "./server-node": "./dist/server.js",
     "./sessions-file": "./dist/execution.js",
     "./sessions-store": "./dist/execution.js",
     "./queue-persistent": "./dist/execution.js",
-    "./captcha-evidence": "./dist/acquisition.js",
     "./hash": "./dist/foundation.js",
     "./release-assets": "./dist/distribution.js",
     "./release-verify": "./dist/distribution.js",
@@ -184,16 +183,16 @@
     "docker.config",
     "Dockerfile",
     "tsconfig.json",
-    "biome.json",
+    "biome.jsonc",
+    "modalityregistry.ts",
     "tiers.ts",
     "quantum.ts"
   ],
   "scripts": {
-    "build:engine": "node tests/scripts/buildengine.mjs",
+    "build:engine": "node tests/scripts/buildengine.ts",
     "check": "npm run build:engine && node --check dist/index.js && node --check dist/execution.js && node --check dist/cli.js && node --check dist/browser.js && node --check dist/distribution.js",
     "formatcheck": "node --import tsx format.ts",
     "test": "vitest run",
-    "test:legacy": "vitest run tests/agent-utils.test.ts tests/cache.test.ts tests/chunking.test.ts tests/core.test.ts tests/errors.test.ts tests/llms-txt.test.ts tests/middleware.test.ts tests/proxy.test.ts tests/tokens.test.ts",
     "run": "npm run build:engine && node dist/cli.js",
     "extension:build": "npm run build:engine && node dist/browser.js",
     "release:assets": "npm run build:engine && node dist/distribution.js",
@@ -204,7 +203,7 @@
     "tauri": "npx --yes @tauri-apps/cli@2.11.4",
     "capacitor:sync:android": "npm run web:build:pages && cap sync android",
     "capacitor:sync:ios": "npm run web:build:pages && cap sync ios",
-    "native:check:flat": "node tests/scripts/validateflatnative.mjs",
+    "native:check:flat": "node tests/scripts/validateflatnative.ts",
     "web:dev": "vite --host",
     "web:check": "npm run build:engine && tsc --project tsconfig.json --noEmit",
     "web:build": "vite build",
@@ -234,9 +233,9 @@
     "vm:create": "node --import tsx ./cli.ts vm",
     "vm:validate": "node --import tsx ./cli.ts vmlint",
     "gpu:list": "node --import tsx ./cli.ts gpus",
-    "docker:build": "docker build -f Dockerfile -t saddle:2.0.150 .",
-    "docker:run": "docker run --rm --memory-swap=-1 --shm-size=2g saddle:2.0.150",
-    "docker:health": "docker run --rm saddle:2.0.150 qemu-system-x86_64 --version && curl -fsS http://localhost:8080/health || true",
+    "docker:build": "docker build -f Dockerfile -t saddle:2.0.151 .",
+    "docker:run": "docker run --rm --memory-swap=-1 --shm-size=2g saddle:2.0.151",
+    "docker:health": "docker run --rm saddle:2.0.151 qemu-system-x86_64 --version && curl -fsS http://localhost:8080/health || true",
     "firecracker:boot": "firecracker --api-sock /tmp/fc-saddle.sock --config-file vmconfig.json 2>/dev/null || echo 'firecracker 1.16.1 warm-pool boot 125ms target'",
     "py:bridge": "python3 qemubridge.py",
     "py:test": "python3 -m pytest -q || python3 qemubridge.py",

package/docs/example-publicapi.ts

@@ -1,7 +0,0 @@
-/**
- * public api example with an injected fetcher; no network is required to run it.
- */
-import { scrapeurl, formatforagent } from "../operations.js";
-
-const result = await scrapeurl("https://example.com", { fetcher: async () => ({ ok: true, status: 200, text: async () => "<title>Example</title><p>Injected content.</p>" }) });
-console.log(JSON.stringify(formatforagent(result), null, 2));