@wenathlan/saddle 2.1.6 → 2.1.7

package/docs/logs/examplesession.json

@@ -0,0 +1,54 @@
+{
+  "version": 1,
+  "session": {
+    "id": "examplesession-0001",
+    "browser": "brave",
+    "seed": "examplesession-seed-0001"
+  },
+  "events": [
+    {
+      "t": 140,
+      "type": "move",
+      "x": 120,
+      "y": 90
+    },
+    {
+      "t": 300,
+      "type": "move",
+      "x": 180,
+      "y": 140
+    },
+    {
+      "t": 480,
+      "type": "click",
+      "x": 180,
+      "y": 140
+    },
+    {
+      "t": 680,
+      "type": "type",
+      "key": "k"
+    },
+    {
+      "t": 900,
+      "type": "move",
+      "x": 240,
+      "y": 200
+    },
+    {
+      "t": 1140,
+      "type": "click",
+      "x": 240,
+      "y": 200
+    },
+    {
+      "t": 1400,
+      "type": "scroll",
+      "dy": 320
+    }
+  ],
+  "captcha": {
+    "kind": "hcaptcha",
+    "passed": true
+  }
+}

package/docs/ninetymodalities.md

@@ -0,0 +1,191 @@
+# ninety.modalities — the wave record
+
+the ninety modalities wave (branch waved/ninety.modalities): the saddle
+plane answers the ninety modality plan the owner charged — every planned
+lane of the registry wires an honest executor, every app of the family
+declares the modality its workloads ride, and the report never lies.
+
+## the state the wave found
+
+the registry carried the ninety records with 30 live, 3 host and 57
+planned — the catalog promised more than the lanes wired. the edge plane
+drove 16 lanes (10 live, 6 host) and every app of the family named its
+sandbox seat only through the debonair precedent (4 ids).
+
+## the wiring the wave answered
+
+- **edgelandeshost.ts** (group a, 25 lanes): the sandbox jails
+  (bubblewrap, nsjail, chroot with the fakechroot fallback and the
+  privilege gate), the container extensions (podman, containerd, runc,
+  crun, the docker max/lite/ghcr profiles), the runtimes (clr, workerd),
+  the screens (xvfb-run, the wayland compositor seat), the mobile
+  termux host, the builds (bazel, buck2, turborepo), the ci runners
+  (actions-runner, gitlab-runner with the exec-removed refusal), the
+  network tunnels (tor with the socks circuit, i2p, wireguard with the
+  keygen law) and the storage daemons (minio mc, garage). every lane
+  probes its binary, runs under the hard deadline in a private temp dir
+  and answers the coded absence when the host carries no runtime.
+- **edgelandesinproc.ts** (group b, 19 lanes): the ram recipes (tmpfs,
+  mmap, overlayfs, loopram, gitram, zram with the real stored-block
+  zlib stream, zswap with the lru pool, swapfile) behind the oom-guard
+  quota, the delivery protocols (the cdn mirror manifest, the rfc6455
+  wss frame, the quic datagram, the grpc length prefix, the capnp
+  segment), the storage wire speakers (libsql envelope, the mysql
+  handshake packet, the postgres startup message, the s3 canonical
+  signer), the webcontainer seat (the frozen module vm) and the
+  local-optin consent gate — pure ts, deterministic, in-process.
+- **edgelandesvirtual.ts** (group c, 7 lanes): the virtual hardware
+  compositions riding the engine's own catalogs — the full machine, the
+  vgpu mig slice, the screen with the session otp, the driver surface,
+  the kvm plan (the qemu argv through the lazy virtualization domain —
+  the .js specifier graph loads inside the executor, never the boot),
+  the gpuless mesa render and the virgl context. every report says
+  composed, never booted.
+- **edgelandesninety.ts** (the merge seat): the six heavyweight probes
+  (browser-server, mobile-capacitor, mobile-postmarketos, pod-session,
+  confidential-sevsnp, confidential-tdx) and the merged lane tables the
+  dispatch plane reads — 73 lanes in the plane, every one carrying its
+  executor, the wiring self-check refusing a gap at boot.
+- **edgeplane.ts**: the lane table rides the merged specs, the dispatch
+  reads the merged executors, the visitor law guard holds on every run.
+- **modalityregistry.ts**: the honest flips — 51 planned lanes walk to
+  live (the lanes the wave wired), 6 walk to host (the heavyweight
+  probes), zero stay planned. the census: **81 live, 9 host, 0 planned,
+  90 records.**
+- **the app declarations** (group e): every app of the family names the
+  modality its workloads ride — argan (17), cadria (16), cobaia (8),
+  devthink (78, the full vocabulary), forge (40), foundry (20), getry
+  (13), stealthhead (12), vault (25) and the debonair seat widened 4 →
+  23 — every one through the env opt-in (APP_WORKER_MODALITY), the ids
+  mirrored as the string contract, zero imports, the visitor law stated
+  in every header.
+- **the vendor mirror**: devthink/modalities.ts re-synced byte-identical
+  to the engine registry (the single-source law), the census pins of the
+  sandboxlane and e2e suites updated to the new truth.
+
+## the verification the wave recorded
+
+- saddle: 28 files / **414 tests green** (379 base + 35 lane tests)
+- argan 69 · cadria 548 · cobaia 30 · debonair 730 · devthink 194 files /
+  3512 · forge 90 · foundry 78 · getry 86 · stealthhead 152 · vault 98
+- family total: **5807 tests green** (5680 base + 127 of the wave)
+- biome zero findings on every file the wave authored
+- the live proof: the webserver answers /api/v1/modalities with
+  {plancount: 90, live: 81, host: 9, planned: 0} and /api/v1/edge/lanes
+  with the 73 probed lanes (61 live, 12 host)
+
+## the reconciliation with the parallel waves
+
+the rebase onto main met two waves that landed while this one worked:
+#239 (the tests home — the tests folders pure inside every app) and
+#240 (the workload law — every app declares its lanes through
+sandboxmodality.ts, the family seat with the join resolver and the
+api routes). the reconciliation honored the no-duplication law: this
+wave dropped its own app declaration seats (the modality.ts files of
+group e) in favor of the #240 family seat the main branch pinned, and
+kept everything the parallel waves did not touch — the fifty-seven
+lane wirings, the registry flips, the vendor mirror sync and the
+census pins. the two census rows #240 charged against the planned-only
+gpu wait (the workload battery and the web workloads lane) now answer
+the post-wave truth: the gpu records this wave wired live make the
+stealthhead world-bake dispatchable, the family census carries zero
+planned-only lanes, and the batteries say so.
+
+## the honest notes
+
+- the host binary lanes of group a name runtimes this host does not
+  carry — the lanes answer HOST_RUNTIME_ABSENT naming the runtime (the
+  language-ruby precedent: live means the engine drives it when the
+  host provides the seat).
+- the kvm lane loads the virtualization domain lazily inside the
+  executor: the webserver's plain node host resolves only .ts
+  specifiers and the domain re-exports virtualgpu through a .js
+  specifier — the family law (a domain the host cannot resolve degrades
+  that one lane, never the engine boot) now pins the pattern for every
+  future lane that reaches the .js graph.
+- the six heavyweight lanes stay host (probe only): the execution
+  wiring of a confidential compute seat or a pod session is the next
+  rung, and the registry says so.
+
+## the wiring wave (wave four, pr15 — branch wave/ninety.wiring)
+
+the wiring wave closed the last gap of the ninety plan: the registry
+carried the ninety records with 81 live and 9 host while the plane
+drove only 73 lanes — seventeen registry-live modalities waited without
+a lane. the wave wired all seventeen, honestly, and the plane table
+now answers the full plan: **90 lanes, 66 live, 24 host.**
+
+### the state the wave found
+
+- the plane: 73 lanes (61 live, 12 host); the registry live set ahead
+  of the lane table by seventeen ids — runner-deno, runner-serverless,
+  language-rust, language-cargo, language-v, language-dotnet,
+  language-php, language-lua, language-zig, language-nim, runner-wasi,
+  fs-gitobjects, storage-sqlite, network-dns, network-doh, build-make
+  and build-ninja, every one already live in the registry.
+
+### the wiring the wave answered
+
+- **edgelandeshost.ts** (group a, +12 lanes): the language toolchains
+  (rustc with the compile-then-run seat, cargo with CARGO_HOME and the
+  target tree inside the private dir, v with HOME at the temp dir,
+  dotnet with the csproj seat and DOTNET_CLI_HOME inside, php, lua, zig
+  with the global cache inside, nim with the nimcache inside), the
+  runner seats (deno with the scoped read permission and DENO_DIR
+  inside, wasi through wasmtime with the base64 module bytes) and the
+  build tail (make with the Makefile as the code field, ninja with the
+  build.ninja as the code field). every lane probes its binary, runs
+  under the hard deadline in the private temp dir and answers the coded
+  absence when the host carries no runtime — the twelve ride kind host
+  (the runtime probe rung), the twenty-five of the first wave stay kind
+  live.
+- **edgelandesinproc.ts** (group b, +5 lanes): the serverless runner
+  (the v8 isolate manifest — one fresh node:vm context per run, the
+  module fingerprint fnv-1a, the frozen inputs surface), the git
+  objects vfs (the loose-object header law and the two-hex-char
+  fan-out), the sqlite vault (the hundred-byte page-one header with the
+  fnv-1a statement id as the change counter) and the network resolvers
+  (the rfc1035 question bytes of dns, the rfc8484 base64url ride of
+  doh under the https-only resolver law) — pure ts, deterministic,
+  seeded, in-process.
+- **edgelandesninety.ts / edgeplane.ts**: the stale sixty-three
+  comments now state the post-wiring truth — ninety lanes, sixty-six
+  live, twenty-four host.
+- **the pinned tests**: the host battery 25 → 37 (the twelve wave ids
+  in alphabetical order, kind host), the inproc battery 19 → 24 with
+  the five samples and the wave four seat laws (the isolate, the
+  fan-out, the page and the resolvers), the plane table 61/12 → 66/24,
+  and the runner-deno refusal test rewired to the wired truth (a real
+  run or the coded absence — the gap it proved is closed).
+
+### the verification the wave recorded
+
+- saddle: 30 files / **437 tests green** (436 base + 1 seat law test)
+- the build green, dist carrying both lane files
+- biome zero findings on every file the wave touched
+- the live proof: the plane table answers 66 live and 24 host of 90 —
+  /api/v1/edge/lanes now reports the ninety probed lanes
+
+### the honest notes
+
+- the twelve host seats ride kind host with real executors: the plane
+  probes the runtime and the executor drives it when the host carries
+  it — an absent runtime answers HOST_RUNTIME_ABSENT naming the runtime,
+  exactly like the live seats of the first wave (the kind answers the
+  rung the table reports, the executor answers the run).
+- the inproc seats stay deterministic: fixed fnv-1a addresses, rfc1035
+  big-endian fields and stored hex — no clock, no randomness, the same
+  payload answers the same bytes every run.
+- this engine host carries make only: the eleven other runtimes answer
+  the coded absence here while the make lane proves a real run — the
+  batteries stay green on both kinds of host.
+
+## the os nicknames of the owner (reference)
+
+sandboxprofile.ts answers five guest os ids — android, grapheneos, linux,
+omarchy, windows — and the owner's spoken names are nicknames of those
+builds, not new ids: marsh (marshmallow) → android, grapenios and grafene
+os → grapheneos, omashi → omarchy, linux normal → linux. the owner's "v"
+names no guest os: it answers the language-v lane of the modality
+registry (the v compiler seat). nothing to add — the vocabulary already
+covers every name the owner used.

package/docs/planningengine.md

@@ -0,0 +1,186 @@
+# planning.engine — the saddle engine ladder (the sandbox that actually runs)
+
+> the owner order: the interface exists, the engine must WORK — the saddle
+> engine planned for real and wired into the whole system, 100% customizable
+> (storage, ram, aliases, drivers, every knob editable through the api), the
+> git storage and the github tree system living in the db, the sandbox
+> modalities opening with their drivers (vgpu, vcpu, memory) running real on
+> the hosts and NEVER touching the person's machine. the flows of the
+> competitors (the telas files: z.ai, grok, manus, bolt, ai studio, vercel,
+> netlify, cloudflare) are the recipe the engine follows; the framework, the
+> library and the package choice stay open as long as node and the engines
+> orchestrate behind. everything rides mime types + https.
+>
+> ## the competitor recipe the engine copies (from telas-sandbox-fluxo)
+>
+> - one sandbox per session, created implicitly at the first send, discovered
+>   never hand-built: workspaces/up (z.ai), /api/preview/{id} (grok),
+>   preview/resolve (manus).
+> - the sandbox state streams: checking → quota ok → initializing → ready
+>   (sse of states with explicit quotas per user), the pod id in the ready
+>   payload.
+> - the preview lives in its own subdomain with the port in it:
+>   preview-chat-<id>.devthink.pro, <port>-<hash>.<region>.devthink.run.
+> - versioned storage OUTSIDE the sandbox: versions/<uuid> per write
+>   (z.ai), codestorage + commitSha (bolt), git repo in s3 (manus) — the
+>   saddle form: git objects inside the db (vault, libgit2) with the
+>   commitSha pointer the sandbox rootfs commits against.
+> - ephemeral credentials only: jwt 300s per preview session (grok), otp per
+>   vnc (manus) — the saddle form: session-scoped tokens minted per sandbox
+>   bind, never a long-lived secret at the edge.
+> - capabilities announced as an event (computer.capabilities.updated): the
+>   image inventory (node 26, git, ffmpeg, playwright-headless) reaches the
+>   front so features toggle by real capacity.
+> - quotas explicit and queryable (x/min, y/4h, z/global) and the 429 typed
+>   before the bind.
+> - the runtime daemon inside the sandbox: supervisord + runtime service
+>   (manus :8330/:8340 form) → devthink-runtime on its own port with the
+>   watcher loop and the upgrade lock, env in two layers (platform + user).
+> - zero captcha anywhere, zero traffic from the person's browser: the code
+>   never transits the visitor, the agent's own headless browser runs inside
+>   the sandbox.
+
+## wave SV0 — what already stands (verified, 411 tests green)
+
+- [x] SV0.001 the virtual hardware engine: cpu/gpu banks, topology solver,
+      the host inventory probes (meminfo, nvidia-smi, glxinfo, vulkan)
+- [x] SV0.002 the vgpu drivers lane: pci ids, nvml shim env, vfio
+      bind/unbind, rom dump, looking glass b7, nvidia vgpu profiles, mig
+      layouts (blackwell) with density validation, intel sriov dkms, nvenc
+      dual engine
+- [x] SV0.003 the vcpu and memory lanes: topology composition, the mttg and
+      passage envelopes, the qemu and docker envelopes, the tier policy
+- [x] SV0.004 the orchestrator with the gitops flux planning, the scheduler,
+      the queue and the quota lanes, the isolation and security gates
+- [x] SV0.005 the webserver (health, specs, sandbox lifecycle, exec, spa
+      shell) and the browser-pure engine port with the transport-neutral
+      bundle set
+- [x] SV0.006 the build engine riding node directly (the windows spawnSync
+      EINVAL wall gone), the lockstep version stamp across the envelope
+- [x] SV0.007 the competitor flows captured (the telas files live beside the
+      md corpus) and the recipe distilled into this plan
+
+## wave SV1 — the modality registry (the fifty, one catalog, the join)
+
+- [ ] SV1.001 modalityregistry.ts: every sandbox modality as a record (id,
+      family, isolation level, driver requirements, boot cost class, the
+      mime contract, the driver modules it mounts) — the catalog grows
+      toward the fifty the owner counts, seeded from the rules list
+- [ ] SV1.002 the families: complete virtual (drivers, cpu, gpu, memory, the
+      three profiles), universal runner, node packages, docker hardened,
+      ghcr immutable, microvm per workflow, browser/webcontainer server side,
+      mobile (capacitor, termux, postmarketos), confidential (sev-snp, tdx),
+      qemu and firecracker, pod per session, local opt-in, vm+vnc,
+      wasm/wasi, vfs, cdn
+- [ ] SV1.003 the join resolver: the workload asks, the engine answers the
+      modality set (the nuclear modality — the person chooses none, the
+      platform resolves the join of all)
+- [ ] SV1.004 the capability contract per modality: what the workload may
+      ask (net off, dropped caps, read-only root, pid limits for the docker
+      hardened; the clean rootfs, injected vcpu count, mesa llvmpipe,
+      lavapipe, rusticl, xvfb for the microvm)
+- [ ] SV1.005 the boot ladder per modality: cold, warm, hot classes with
+      the measured budgets (gvisor without kvm about 200 ms, firecracker
+      125 ms boot the sandbox.ts banner already answers, v8 isolates for
+      serverless)
+- [ ] SV1.006 tests: the registry determinism, the join resolution on the
+      three base profiles (max, balanced, lite), every record complete
+
+## wave SV2 — the vfs and the cdn lane (the packages never touch the visitor)
+
+- [ ] SV2.001 vfs.ts: the virtual file system born from prisma/git/db —
+      read(path) → chunk pointers from the db, write(path, bytes) → chunk
+      catalog with sha-256 and compression, automatic reuse of equal chunks
+- [ ] SV2.002 the cdn lane: the ~45 cdns (esm.sh among them) fetched INSIDE
+      the sandbox over https through the vfs mirror — the person's browser
+      never loads a cdn byte of a sandbox workload
+- [ ] SV2.003 the granular materialization: packages install ten by ten,
+      forty by forty inside the sandbox from the catalog (package.10 law) —
+      never on the build host
+- [ ] SV2.004 the mime contract: every vfs object answers its mimetype, the
+      api serves content-type on every read (the mimetypes file feeds the
+      mapping)
+- [ ] SV2.005 tests: chunk dedupe round trip, sha-256 stability, the cdn
+      mirror mock, the mime headers on every route
+
+## wave SV3 — the git storage and the github tree (the code survives the sandbox)
+
+- [ ] SV3.001 gitobjects.ts: git objects and blobs inside the db through
+      libgit2 semantics — the tree system the github tree law names: read
+      tree(path) → entries, write tree, commit with the parent chain
+- [ ] SV3.002 the versioned write: every sandbox write stamps versions/<uuid>
+      with the commitSha — the bolt/z.ai pattern with the vault storage
+- [ ] SV3.003 the github tree lane: read the live tree of a repository over
+      the api (authenticated), mirror into the git objects table, the
+      sandbox mounts the tree as its rootfs through the vfs
+- [ ] SV3.004 the rollback: checkout any commitSha back into a running
+      sandbox (the history the vitrine clicks through)
+- [ ] SV3.005 tests: tree round trip, commit chain integrity, the github
+      mirror with a recorded fixture, rollback determinism
+
+## wave SV4 — the session sandbox law (pod per session, the states stream)
+
+- [ ] SV4.001 sandboxup: one sandbox per session created implicitly at the
+      first send, discovered by session id — never a hand-built url
+- [ ] SV4.002 the states stream over sse: checking → quota ok →
+      initializing → ready with the sandbox id, quotas per user explicit in
+      the handshake
+- [ ] SV4.003 the capabilities event: the image inventory (node 26, git,
+      ffmpeg, playwright-headless, ffmpeg) announced when the sandbox turns
+      ready
+- [ ] SV4.004 the preview subdomain: preview-<session>.devthink.pro with the
+      port binding, the ephemeral jwt 300s per bind (claims sub, session,
+      port)
+- [ ] SV4.005 the runtime daemon: devthink-runtime inside the sandbox (the
+      supervisord + watcher loop + upgrade lock the manus form proves), env
+      in two layers (platform + session)
+- [ ] SV4.006 the sweep: ttl 15 minutes, the sweep period the webserver
+      already carries, the workspace quota answering with the sandbox id
+- [ ] SV4.007 tests: the state ladder order, the quota refusal typed 429,
+      the jwt expiry, the capabilities payload
+
+## wave SV5 — config and aliases (100% customizable through the api)
+
+- [ ] SV5.001 sandboxconfig.ts: every knob editable — base (max, balanced,
+      lite), os image (android, grapheneos, linux, omarchy, windows,
+      distros), arch (arm64, amd64), vcpu count, vram mib, storage quota,
+      the modality join, the driver set
+- [ ] SV5.002 the aliases table: user-defined aliases per sandbox (the
+      short names the shell and the api resolve), add/rename/remove through
+      the api, unique per owner
+- [ ] SV5.003 the config store: rows in sqlite through parameter binding,
+      the api serves and accepts the whole surface (the ui edits the same
+      rows), defaults from the seed catalog never hardcoded in components
+- [ ] SV5.004 the presets: named profiles (the three bases plus user
+      presets) shareable and versioned
+- [ ] SV5.005 tests: config round trip, alias uniqueness, preset apply,
+      the api contract with a fake request
+
+## wave SV6 — the runners (forge at the frontier, foundry the face)
+
+- [ ] SV6.001 the docker hardened runner: no network, dropped caps,
+      read-only root, pid limits, runsc option
+- [ ] SV6.002 the microvm runner: clean rootfs, injected vcpu count, the
+      cpu id via ld_preload, mesa llvmpipe + lavapipe + rusticl + xvfb for
+      the gpu-less render, iso-style and ghcr sources
+- [ ] SV6.003 the wasm/wasi runner: wasmer and wasmedge behind the same
+      dispatch contract
+- [ ] SV6.004 the universal runner: any binary of the market through the
+      binfmt form, the platform processes included
+- [ ] SV6.005 the dispatch result: the same SandboxState/DispatchResult
+      shape every runner answers (the contract the tests already pin)
+- [ ] SV6.006 tests: per-runner dispatch on the recorded fixtures, the
+      hardening gates refusing the forbidden flags
+
+## wave SV7 — the verification (the owner reads the live proof)
+
+- [ ] SV7.001 the full battery green on every wave's modules
+- [ ] SV7.002 the live proof: sandbox up through the api, the states stream
+      answering, exec inside, the vfs fetch of a cdn package, the git
+      commit with the commitSha, the preview subdomain bound with the
+      ephemeral jwt
+- [ ] SV7.003 the live proof: the config edited through the api (ram,
+      storage, alias), the next boot honoring it
+- [ ] SV7.004 the debonair bridge: the render jobs of the audio engine run
+      inside a saddle sandbox (the no-client-dsp law of the music pipeline)
+- [ ] SV7.005 the worklog and the ladder ticked, the wave committed