@wenathlan/saddle 2.0.154 → 2.0.159

package/modes.ts

@@ -0,0 +1,170 @@
+/**
+ * modes.ts — target mode resolution and host-neutral deployment contracts.
+ *
+ * This file is the v2.0.0 grand-merge consolidation of the former nested
+ * folders of the repository (modes) into the single
+ * root-level domain file of the saddle family standard: one optimized
+ * TypeScript file per correlated domain, ordinal sections, JSDoc on every
+ * block, intra-domain imports dissolved, cross-domain imports rewritten to
+ * ./<domain>.js. Every capability of every source file is preserved here;
+ * the pure re-export barrels (none in this domain) folded their surface into this file directly.
+ */
+
+
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 1: modes/modes.ts — mode profiles describe paired operation surfaces without changing engine contracts. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * mode profiles describe paired operation surfaces without changing engine contracts.
+ */
+const names = ["computer", "library", "application", "browser", "desktop", "mobile", "extension", "cli", "binary", "internet", "physicalfile", "vectorfile", "visible", "headless"];
+
+export function modeprofile(options = {}) {
+  const enabled = new Set(options.enabled ?? ["library", "cli", "binary"]);
+  return Object.fromEntries(names.map((name) => [name, { name, enabled: enabled.has(name), paired: Boolean(options.paired?.includes(name)) }]));
+}
+
+export function librarymode(factory) { return { name: "library", start: factory, stop: async () => undefined }; }
+export function climode(run) { return { name: "cli", run }; }
+export function binarymode(run) { return { name: "binary", run }; }
+export function browsermode(adapter) { return { name: "browser", adapter }; }
+export function headlessmode(adapter) { return { name: "headless", adapter }; }
+export function computemode(adapter) { return { name: "computer", adapter }; }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 2: modes/matrix.ts — mode matrix keeps supported execution choices in one grouped contract. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * mode matrix keeps supported execution choices in one grouped contract.
+ */
+export const modeaxes = Object.freeze({
+  execution: ["library", "application", "browser", "desktopapp", "mobileapp", "extension", "cli", "binary", "computer", "internet"],
+  runtime: ["node", "browser", "deno", "bun", "worker", "unknown"],
+  memory: ["internal", "external", "physical", "vectorized", "library"],
+  file: ["internal", "external", "physical", "vector"],
+  dependency: ["internal", "external", "dev"],
+  visibility: ["visible", "headless"],
+  pair: ["without", "with"]
+});
+
+export const operationmodes = Object.freeze(modeaxes.execution.flatMap((execution) => modeaxes.pair.map((pair) => `${execution}${pair}`)));
+
+/** Returns true when the matrix contains the requested axis value. */
+export function validatemode(axis, value) { return Boolean(modeaxes[axis]?.includes(value)); }
+
+/** Returns a serializable snapshot for documentation and diagnostics. */
+export function modecatalog() { return { axes: Object.fromEntries(Object.entries(modeaxes).map(([key, values]) => [key, [...values]])), operationmodes: [...operationmodes] }; }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 3: modes/resolve.ts — mode resolver selects open defaults while preserving every caller choice. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * mode resolver selects open defaults while preserving every caller choice.
+ */
+
+/** Resolves an execution profile without starting a process or opening a socket. */
+export function resolvemode(options = {}) {
+  const profile = {
+    execution: options.execution ?? "library",
+    runtime: options.runtime ?? "unknown",
+    memory: options.memory ?? "internal",
+    file: options.file ?? "internal",
+    dependency: options.dependency ?? "internal",
+    visibility: options.visibility ?? "headless",
+    pair: options.pair ?? "without"
+  };
+  for (const [axis, value] of Object.entries(profile)) if (!validatemode(axis, value)) throw new TypeError(`unsupported mode ${axis}:${value}`);
+  return { ...profile, capabilities: modecapabilities(profile) };
+}
+
+/** Returns stable capabilities for adapters and diagnostics. */
+export function modecapabilities(profile) {
+  return {
+    library: profile.execution === "library" || profile.execution === "application",
+    browser: profile.execution === "browser" || profile.execution === "extension" || profile.runtime === "browser" || profile.runtime === "worker",
+    cli: profile.execution === "cli" || profile.execution === "binary",
+    physicalmemory: profile.memory === "physical",
+    vectorizedmemory: profile.memory === "vectorized",
+    externalmemory: profile.memory === "external",
+    externalfile: profile.file === "external",
+    externaldependency: profile.dependency === "external",
+    visible: profile.visibility === "visible"
+  };
+}
+
+/** Returns a stable cross-runtime capability report without starting infrastructure. */
+export function capabilityreport(options = {}) {
+  const overrides = { runtime: options.runtime ?? "unknown", memory: options.memory ?? "internal", file: options.file ?? "internal", dependency: options.dependency ?? "internal", visibility: options.visibility ?? "headless", pair: options.pair ?? "without" };
+  const profiles = modeaxes.execution.map((execution) => {
+    const profile = resolvemode({ ...overrides, execution });
+    return { mode: execution, capabilities: profile.capabilities, profile };
+  });
+  return { version: 1, axes: Object.fromEntries(Object.entries(modeaxes).map(([key, values]) => [key, [...values]])), overrides, profiles, infrastructure: { host: "caller-owned", port: "caller-owned", credentials: "caller-owned", provider: "caller-owned" } };
+}
+
+/** Applies one profile to a caller supplied operation. */
+export async function withmode(options, operation) { if (typeof operation !== "function") throw new TypeError("mode operation is required"); return operation(resolvemode(options)); }
+
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 4: modes/deploy.ts — deploy surface exposes artifact planning without performing provider mutations. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * deploy surface exposes artifact planning without performing provider mutations.
+ */
+export { publishplan, registrymanifest } from "./distribution.ts";
+/* the packaging surface pair (surfacemanifest, surfacebundle) moved to
+ * devthink with the automation domain (the saddle ownership law, wave a,
+ * actions 108-112 — the deploy surface keeps the artifact planning pair
+ * the engine owns). */
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 5: modes/targets.ts — target profiles keep platform packaging open and describe capability boundaries. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * target profiles keep platform packaging open and describe capability boundaries.
+ */
+export const targetprofiles = Object.freeze({
+  application: { runtime: "caller", entry: "distpackage/index.js", capabilities: ["memory", "storage", "network"], formats: ["zip", "tarball"] },
+  computer: { runtime: "node", entry: "distpackage/index.js", capabilities: ["memory", "storage", "runner"], formats: ["node", "bun", "deno", "singlefile"] },
+  desktopapp: { runtime: "tauri", entry: "desktop/src-tauri", capabilities: ["memory", "file", "visible"], formats: ["appimage", "deb", "rpm", "snap", "flatpak", "dmg", "pkg", "exe", "msi", "msix"] },
+  mobileapp: { runtime: "capacitor", entry: "index.html", capabilities: ["memory", "network", "visible"], formats: ["apk", "aab", "ipa"] },
+  android: { runtime: "capacitor", entry: "android", capabilities: ["memory", "network", "visible"], formats: ["apk", "aab"] },
+  ios: { runtime: "capacitor", entry: "ios", capabilities: ["memory", "network", "visible"], formats: ["ipa"] },
+  cli: { runtime: "node", entry: "distpackage/cli/main.js", capabilities: ["memory", "storage", "network"], formats: ["node", "bun", "deno", "singlefile", "exe", "deb", "rpm"] },
+  binary: { runtime: "caller", entry: "distpackage/cli/main.js", capabilities: ["memory", "storage", "runner"], formats: ["sea", "singlefile", "wasm"] },
+  browser: { runtime: "tauri", entry: "desktop/src-tauri", capabilities: ["memory", "network", "visible"], formats: ["html", "pwa", "wasm", "appimage", "deb", "rpm", "dmg", "exe", "msi"] },
+  extension: { runtime: "browser", entry: "distpackage/extension/index.js", capabilities: ["browser", "network", "visible"], formats: ["crx", "xpi", "safariextz"] },
+  internet: { runtime: "caller", entry: "distpackage/index.js", capabilities: ["network", "webhook", "api"], formats: ["http", "websocket", "grpc", "rest"] },
+  web: { runtime: "browser", entry: "index.html", capabilities: ["network", "visible"], formats: ["html", "pwa", "ssg", "ssr", "wasm"] },
+  libreoffice: { runtime: "caller", entry: "distpackage/index.js", capabilities: ["file", "network"], formats: ["oxt", "zip"] },
+  mcp: { runtime: "caller", entry: "distpackage/adapters/mcpserver.js", capabilities: ["network", "api"], formats: ["stdio", "jsonrpc"] },
+  vsix: { runtime: "caller", entry: "distpackage/index.js", capabilities: ["network", "visible"], formats: ["vsix"] },
+  container: { runtime: "node", entry: "distpackage/index.js", capabilities: ["memory", "storage", "network"], formats: ["oci", "docker"] }
+});
+
+/** Creates a surface target with caller supplied entry and capabilities. */
+export function targetmanifest(target, options = {}) { const profile = targetprofiles[target]; if (!profile) throw new TypeError(`unsupported target: ${target}`); return { target, runtime: options.runtime ?? profile.runtime, entry: options.entry ?? profile.entry, formats: options.formats ?? [...profile.formats], capabilities: options.capabilities ?? [...profile.capabilities], permissions: options.permissions ?? [], metadata: options.metadata ?? {} }; }
+
+/** Returns all supported target profiles for documentation and tooling. */
+export function targetcatalog() { return Object.fromEntries(Object.entries(targetprofiles).map(([key, value]) => [key, { ...value, capabilities: [...value.capabilities] }])); }
+
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 6: the runner-mode ladder — the runtime targets a run asks   */
+/* the engine for (wave 3, the engine ownership law: forge and foundry  */
+/* consumed the five targets as duplicated twin lists; the ladder       */
+/* answers from the saddle owner from this day on, and the apps import  */
+/* it through the published library specifier). Zero logic change to    */
+/* the lanes above — the section is additive and imports nothing.       */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * the runner modes of the engine: the runtime targets a run asks for on
+ * the saddle boundary — the full virtual machine, the runner host, the
+ * node packages lane, the docker lane and the ghcr immutable lane.
+ */
+export const runnermodes = ["full-virtual", "runner", "node-packages", "docker", "ghcr"] as const;
+
+/** one runner mode of the engine (the runtime target a run asks for). */
+export type RunnerMode = (typeof runnermodes)[number];

package/mttg.config

@@ -2,7 +2,7 @@
   "meta": {
     "name": "mttg.config",
     "title": "saddle - MTTG Multi-Tenant Task Groups (cgroups v2 + tenants + transcode) with MTTCG (QEMU TCG) section",
-    "version": "2.0.127",
+    "version": "2.0.154",
     "date": "2026-08-22",
     "language": "en",
     "conceptSeparation": "MTTG = Multi-Tenant Task Groups (cgroup v2 cpu.weight/cpuset/memory/io/pids/hugetlb/rdma + tenants + transcode pipelines). MTTCG = QEMU Multi-Threaded TCG (one host thread per vCPU under TCG). Both live here as DISTINCT sections; MTTCG accel flags also in qemu.config#mttcg.",

package/orchestrator.ts

@@ -68,8 +68,8 @@ import { cpus, freemem, networkInterfaces, tmpdir, totalmem } from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { setTimeout as sleep } from 'node:timers/promises';
-import type { enginetopicname, enginetopics } from './index.js';
-import { enginebus, MetricsStore } from './index.js';
+import type { enginetopicname, enginetopics } from './index.ts';
+import { enginebus, MetricsStore } from './index.ts';
 
 /* ------------------------------------------------------------------ */
 /* context: runtime catalog (verified 2026-08-22)                       */
@@ -1279,8 +1279,12 @@ class firecrackerruntime extends runtimestrategy {
  * the class also absorbs spawnqemu from the Meta source: the vm plane
  * launches qemu with monitor and qmp unix sockets, a numa pin line,
  * vfio devices for every gpu assignment, extra args from qemu.config
- * and, when the binary is absent (CI), a "sleep 3600" stand-in process
- * so scheduling and lifecycle still exercise end to end.
+ * and — the honest-boot law of the engine-real rung — when the qemu
+ * binary is absent the spawn refuses with ERR_QEMU_ABSENT (the error
+ * names the binary the host must carry) so a vm record never claims
+ * running over a stand-in process: scheduling and lifecycle still
+ * exercise end to end in CI through the argv builders and the create /
+ * destroy planes, never through a faked boot.
  */
 class qemuruntime extends runtimestrategy {
   override readonly name: sandboxruntime = 'qemu';
@@ -1346,13 +1350,24 @@ class qemuruntime extends runtimestrategy {
 
   /**
    * builds the vm plane argv: strategy flags plus the name/uuid, dual
-   * unix sockets, virtio balloon, the per-numa bridge netdev, the numa
-   * pin line and one vfio-pci device per assigned gpu.
+   * unix sockets, virtio balloon, the numa pin line and one vfio-pci
+   * device per assigned gpu. the netdev answers the honest network law:
+   * the per-numa bridge (br-vhe-N) rides when the interface exists on
+   * the host (the privileged deployments the bridge plane owns), and a
+   * host without the interface rides user-mode networking (slirp) — a
+   * real qemu network mode that needs no privilege — so the argv a host
+   * without the bridge answers is a bootable argv, never a bridge the
+   * kernel would refuse.
    */
   buildvmcommand(vm: vmrecord, assignments: readonly gpuassignment[]): readonly string[] {
     const kvm = kvmavailable();
     const accel = vm.accel === 'kvm' && kvm ? 'kvm' : 'tcg,thread=multi,tb-size=1024';
     const sockets = this.socketsfor(vm.id);
+    const bridgename = `br-vhe-${vm.numanode}`;
+    const bridgeonhost = existsSync(`/sys/class/net/${bridgename}`);
+    const netdev = bridgeonhost
+      ? `bridge,br=${bridgename},id=net0`
+      : 'user,id=net0';
     const args: string[] = [
       vm.qemubinary,
       '-machine',
@@ -1372,7 +1387,7 @@ class qemuruntime extends runtimestrategy {
       '-device',
       'virtio-balloon-pci,id=balloon0',
       '-netdev',
-      `bridge,br=br-vhe-${vm.numanode},id=net0`,
+      netdev,
       '-device',
       'virtio-net-pci,netdev=net0',
       '-display',
@@ -1394,8 +1409,12 @@ class qemuruntime extends runtimestrategy {
 
   /**
    * spawns qemu for a vm record; when the binary does not exist the
-   * method spawns "sleep 3600" instead so CI environments without qemu
-   * still run the scheduling and lifecycle paths (spawnqemu merge).
+   * method refuses with ERR_QEMU_ABSENT — the honest-boot law of the
+   * engine-real rung: a host without the qemu binary never answers a
+   * stand-in process, the vm record never claims running over a sleep
+   * (startvm catches the refusal, marks the vm failed and publishes the
+   * error, so CI exercises the argv builders and the create / destroy
+   * planes instead of a faked boot).
    */
   async spawn(
     vm: vmrecord,
@@ -1404,14 +1423,23 @@ class qemuruntime extends runtimestrategy {
   ): Promise<qemuprocess> {
     try {
       const sockets = this.socketsfor(vm.id);
-      const argv = [...this.buildvmcommand(vm, assignments), '-daemonize'];
+      // the socket seats must exist before the guest opens its servers —
+      // qemu creates the socket files itself, never the parent directory
+      mkdirSync(path.dirname(sockets.qmp), { recursive: true });
+      // the foreground law of the honest-boot rung: the tracked child is
+      // the process that lives as long as the vm — the daemonize flag
+      // would fork the daemon and exit the parent at once (the vm would
+      // read stopped over a live machine), so the spawn rides the
+      // foreground argv the exit callback can own
+      const argv = this.buildvmcommand(vm, assignments);
       const [bin, ...rest] = argv;
-      let child: ChildProcess;
-      if (existsSync(bin)) {
-        child = spawn(bin, rest, { stdio: 'ignore', detached: false });
-      } else {
-        child = spawn('sleep', ['3600'], { stdio: 'ignore', detached: false });
+      if (!existsSync(bin)) {
+        throw new orchestratorerror(
+          `qemu spawn refused for ${vm.id}: the binary ${bin} is absent from the engine host (the honest-boot law — a vm never runs over a stand-in process)`,
+          'ERR_QEMU_ABSENT',
+        );
       }
+      const child: ChildProcess = spawn(bin, rest, { stdio: 'ignore', detached: false });
       const pid = child.pid ?? randomInt(1000, 11000);
       const processinfo: qemuprocess = {
         vmid: vm.id,
@@ -1426,6 +1454,12 @@ class qemuruntime extends runtimestrategy {
       });
       return processinfo;
     } catch (error) {
+      // the honest-boot refusal rides through untouched — the code the
+      // law answers (ERR_QEMU_ABSENT) is the code startvm and the vm
+      // record read, never the generic spawn wrap
+      if (error instanceof orchestratorerror) {
+        throw error;
+      }
       throw new orchestratorerror(
         `qemu spawn failed for ${vm.id}: ${errormessage(error)}`,
         'ERR_QEMU_SPAWN',