@wenathlan/saddle 1.8.17 → 2.0.2

package/README.md

@@ -6,7 +6,7 @@
   <strong>Storage-backed jobs, scraping contracts and portable runners for Node.js.</strong><br/>
   <strong>Binary computing engine, agent browser, scraper and packager.</strong><br/>
   <a href="https://github.com/wenathlan/saddle/actions/workflows/ci.yml"><img src="https://github.com/wenathlan/saddle/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
-  <a href="https://github.com/wenathlan/saddle/releases/tag/v1.8.14"><img src="https://img.shields.io/badge/release-v1.8.14-d35d3d" alt="Release 1.8.14" /></a>
+  <a href="https://github.com/wenathlan/saddle/releases/tag/v2.0.0"><img src="https://img.shields.io/badge/release-v2.0.0-d35d3d" alt="Release 2.0.0" /></a>
   <a href="https://github.com/wenathlan/saddle/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0--only-202a2f" alt="GPL 3.0 only license" /></a>
 </p>
 
@@ -16,6 +16,27 @@ Saddle is a **TypeScript-first ESM engine** compiled to JavaScript, declarations
 
 The canonical JavaScript package is `@wenathlan/saddle`. GitHub Packages npm, Maven and GHCR use the `wenathlan` owner namespace; NuGet and RubyGems retain their ecosystem package names. Older `@wenathlan`, `@iakadion` and `io.devthink` references in archived documents are historical records, not current package identities.
 
+## The e2ugh virtual-hardware engine (the grand merge)
+
+Version 2.0.0 merges the e2ugh repository into saddle. The engine core
+(`createVirtualEngine`, `validateSpec`, `randomPort`, `InternalMemory`,
+`MetricsStore`, the `enginebus`) is re-exported from the package root; the
+domain modules land beside the saddle domains:
+
+| module | surface |
+| --- | --- |
+| `virtualcpu.ts`, `virtualmemory.ts`, `virtualgpu.ts` | the virtual hardware catalog contracts |
+| `virtualization.ts`, `orchestrator.ts` | grid orchestration and the sandbox/vm runtime strategies |
+| `scheduler.ts`, `compute.ts`, `performance.ts` | job queues, batch compute and benchmark planning |
+| `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 |
+| `web/` | the static console and the zero-dependency self-hosted API (`node web/server.js`) |
+| `specs/*` package exports | processors, gpus, cores, boards and the qemu/mttg/passage/docker envelopes |
+
+The full pre-merge documentation of the engine lives in
+[docs/e2ugh-engine.md](docs/e2ugh-engine.md) and its release history in
+[CHANGELOG.md (the e2ugh lineage sections)](CHANGELOG.md (the e2ugh lineage sections)).
+
 ## Start here
 
 Saddle requires **Node.js 26.7.0 or newer**.
@@ -40,17 +61,19 @@ node --import tsx examples/publicapi.ts
 npm test
 ```
 
-## Progressive architecture
+## Foundation
 
-The project documentation follows a progressive arc. The foundation describes the storage and runner model; the engine describes the contracts that make the model executable; productization describes the package, extension, workflow and web surfaces.
+Saddle is organized as a progressive architecture. **Foundation** defines the storage, runner and working-set model. **Engine** defines the contracts that make that model executable. **Productization** exposes the same contracts through package, extension, workflow, native and web surfaces without creating a second source of truth.
 
-### Foundation: storage, runners and working sets
+### Storage, runners and working sets
 
 Saddle treats a repository, bucket or object store as durable state and a third-party runner as a replaceable processor. GitHub Actions is one adapter, not the core. Forgejo, Gitea, GitLab, Codeberg, Docker and caller-owned runners can implement the same runner contracts.
 
 The physical limit remains explicit: remote storage is not VRAM. A storage-to-RAM bridge can stage a bounded working set through a local filesystem, tmpfs, mmap, cache or caller-owned storage adapter, but it cannot remove network latency or create the bandwidth of a GPU bus. The engine exposes that distinction instead of hiding it behind marketing language.
 
-The execution model is:
+### The execution model
+
+The execution model is intentionally small and explicit:
 
 ```text
 repository or bucket -> runner working set -> process -> durable artifact
@@ -74,7 +97,11 @@ The historical design treats the repository and its runner as a **virtual proces
 
 The engine keeps these boundaries explicit. It does not silently install a browser, mount a bucket as VRAM, create a database, choose a proxy, or transfer credentials to a provider.
 
-### Engine: contracts instead of vendor lock-in
+## Engine
+
+The engine coordinates serializable contracts rather than hiding providers. The caller composes storage, working-set, runner, protocol and delivery adapters around a durable artifact boundary. Remote effects remain adapter-owned; the transport-neutral root does not require a cloud account, database, browser binary or secret.
+
+### What is included
 
 | Area | Contracts shipped | Result |
 | --- | --- | --- |
@@ -101,7 +128,9 @@ The protocol layer accepts JSON request/response envelopes, NDJSON append-only e
 
 The root entry point is transport-neutral. Node filesystem, HTTP server, persistent sessions and Playwright are explicit subpaths or optional adapters. The library accepts caller-provided fetchers, browser transports, storage adapters, persistence, proxy pools, captcha evidence handlers, webhook secrets and remote credentials.
 
-### Productization: one engine, many shells
+## Productization
+
+### One engine, many shells
 
 The same contracts can be surfaced as an npm library, application archive, computer runtime, desktop installer, Android APK/AAB, iOS IPA, CLI, binary, browser package, Manifest V3 extension, web/PWA artifact, LibreOffice OXT, VSIX, webhook server, MCP transport, workflow action, container image, Maven package, NuGet package or RubyGem. These surfaces are declarative target plans and caller-owned adapters around the engine; they are not separate sources of truth.
 
@@ -135,8 +164,12 @@ Saddle can be connected to GitHub, GitLab, Forgejo, Gitea, Codeberg, Docker or a
 | `nodeserver` | Web Request/Response handler |
 | `engine` / `scheduler` | job lifecycle and runner dispatch |
 | `release-assets` | SHA256SUMS, SBOM and provenance metadata for caller-selected artifacts |
+| `releaseevidence` / `evaluateevidence` | serializable release-evidence creation and evaluation |
+| `releasereadiness` / `evidencefromverification` | readiness assessment from caller-supplied verification evidence |
+| `executionrequest` / `executiondecision` / `executionhandoff` | denied-by-default privileged-effect planning and caller-owned handoff projection |
+| `internalenvelope` / `internalapi` | pure typed envelopes for a unified web gateway, plan, policy, materialization, execution, persistence and evidence boundary |
 
-The complete export map is documented in [`docs/libraryapi.md`](docs/libraryapi.md). The product index is in [`docs/productindex.md`](docs/productindex.md), and runnable examples are in [`docs/usage.md`](docs/usage.md).
+The package export map is defined by the root manifest. Runnable public examples, API reference material and technical records ship with the package, while the root entry point remains the recommended starting surface for applications that do not need a platform-specific adapter.
 
 ## Browser extension
 
@@ -165,7 +198,7 @@ The base permission set is `activeTab`, `scripting` and `storage`. It does not r
 | Failure | retry, circuit breaker, idempotency and resume are configurable |
 | Releases | version comes from the `vX.Y.Z` tag and must match `package.json` |
 
-Version 1.8.14 carries the TypeScript-first source into the current release and keeps public JavaScript package paths stable. It includes release-derived package metadata, queue leases, bounded structured extraction with provenance, browser context budgets, explicit workflow cancellation with caller-owned compensation, deterministic artifact retention decisions and a post-push container pull/smoke validation. The dynamic debug collector is intentionally an unchecked browser boundary because it monkey-patches browser APIs; the rest of the web surface remains strictly typechecked. See [`docs/reorganization-1.8.9.md`](docs/reorganization-1.8.9.md), [`docs/toolchainresearch-1.8.9.md`](docs/toolchainresearch-1.8.9.md), [`docs/releasenotes-1.8.12.md`](docs/releasenotes-1.8.12.md), [`docs/releasenotes-1.8.13.md`](docs/releasenotes-1.8.13.md) and [`docs/releasenotes-1.8.14.md`](docs/releasenotes-1.8.14.md).
+Version 2.0.0 (the grand merge) absorbs the e2ugh virtual-hardware engine into the saddle engine: fifteen engine modules land at the repository root (virtualcpu, virtualmemory, virtualgpu, virtualization, orchestrator, scheduler, compute, media, render, security, performance, alternatives, tiers, quantum and the engine index core), the e2ugh static console and self-hosted API live at web, the hardware catalogs (processors, gpus, cores, boards) and the four virtual-hardware config envelopes (qemu, mttg, passage, docker) ship as package exports under specs/*, and the legacy WebScrape toolkit generation consolidates into webscrape.ts. The engine surface stays dependency-free at the root (node built-ins only). Version 1.8.19 previously while reorganizing implementation ownership into twenty correlated domains behind a transport-neutral root router. The migration groups foundation nouns, execution state, API protocols, MCP adapters, automation contracts, package delivery and mode profiles without adding a privileged effect. Existing package subpaths remain available through their updated compiled targets. The denied-by-default execution, policy, handoff and internal-API contracts remain plans or receipts until a separately approved caller adapter is supplied. The current container targets `linux/amd64`, `linux/arm64` and `linux/ppc64le`; release evidence, readiness and verification remain serializable and caller-owned.
 
 ## Package surfaces and release automation
 
@@ -188,11 +221,11 @@ Saddle is applying to the SignPath Foundation for open-source code signing. Unti
 
 The requested policy is: **Free code signing provided by SignPath.io, certificate by SignPath Foundation**. Committers and reviewers are maintainers with write access to the public repository. Approvers are repository owners or release approvers recorded in `governance.md`. Every signed release must be built from repository source, pass the security and packaging gates, and receive manual signing approval.
 
-The core program will not transfer information to other networked systems unless specifically requested by the user or the person installing or operating it. Browser sessions, storage adapters, runners and external services remain caller-configured and subject to their own policies. See [`privacy-policy.md`](privacy-policy.md) and [`security.md`](security.md).
+The core program will not transfer information to other networked systems unless specifically requested by the user or the person installing or operating it. Browser sessions, storage adapters, runners and external services remain caller-configured and subject to their own policies. See [`privacy-policy.md`](privacy-policy.md) and [`SECURITY.md`](SECURITY.md).
 
 ## GitHub Pages web surface
 
-The marketing site lives under [`web/`](web/) with a root-based TypeScript/React layout. It has no `client/` or `src/` subdirectory. Vite normalizes the base path and all visual assets resolve through a shared helper, so the same build works at `/` and `/saddle/`.
+The marketing site lives under [`web/`](web/) with a root-based TypeScript/React layout. It has no `client/` or `src/` subdirectory. Vite normalizes the base path and all visual assets resolve through a shared helper, so the same build works at `/` and `/saddle/`. Its `/playground` route projects the unified internal API boundaries with a fixed safe fixture; it is not a binary executor, service host, persistent store, remote browser or hidden backend.
 
 ```bash
 npm run web:check
@@ -201,7 +234,7 @@ 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/lib/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.
 
-## Development and release gates
+## Development
 
 ```bash
 npm ci
@@ -214,28 +247,41 @@ npm run web:check
 VITE_BASE_PATH=/saddle npm run web:build:pages
 ```
 
-The engine test suite is deterministic and does not require real credentials or network access. The release path is: update `package.json` and the manifest files, update `changelog.md` and release notes, run all gates, create `v<package-version>`, push the tag and create the GitHub release. Registry workflows then derive the same version from that release tag. A package metadata change alone does not publish anything; the release tag is the intentional publication boundary.
+The engine test suite is deterministic and does not require real credentials or network access. The release path is: update `package.json` and the manifest files, update `CHANGELOG.md` and release notes, run all gates, create `v<package-version>`, push the tag and create the GitHub release. Registry workflows then derive the same version from that release tag. A package metadata change alone does not publish anything; the release tag is the intentional publication boundary.
+
+## CLI
+
+The published `saddle` executable is a local, adapter-oriented inspection surface. It intentionally lists only stable commands and does not turn a local invocation into remote dispatch.
+
+| Command | Purpose | External effect |
+| --- | --- | --- |
+| `saddle help` | list the stable command surface | none |
+| `saddle modes` | print the mode catalog as JSON | none |
+| `saddle runexample` | execute a temporary local engine example | temporary local storage only |
+| `saddle mcp` | print the available MCP tool declarations | none |
+
+Remote execution, provider credentials, browser transport, persistence, proxy selection, captcha evidence handling and webhook dispatch remain caller-provided adapters. The CLI is therefore a way to inspect or exercise local contracts, not a substitute for an operator-owned deployment policy.
 
 ## Repository map
 
 ```text
-core/          engine errors, scrape error taxonomy, events, identifiers and hashing
-domain/        jobs, artifacts, sessions and providers
+core/          errors, events, identifiers, hashing, jobs, artifacts, sessions and providers
 memory/        working-set bridge, modes, objects and transforms
 storage/       local, chunked, remote and file-hosting adapters
 scrape/        robots, cache, extraction, schema, normalization and grouped crawl contracts
-queue/         queue, idempotency, saga and recovery
+runtime/       engine orchestration, queues, idempotency, saga, resumable and session contexts
 browser/       fingerprint, session, agent and Playwright adapter contracts
 extension/     Manifest V3 reference surface and packager
 desktop/       Tauri browser application for Windows, Linux and macOS
 android/       Capacitor Android conversion target and optimized Gradle release
 ios/           Capacitor iOS conversion target and caller-owned Xcode signing
 capacitor.config.ts shared web-to-native configuration for Android and iOS
-protocol/      JSON, NDJSON, SSE and block serializers
-workflow/      manifests, templates and registry contracts
+api/           envelopes, authentication, controls, JSON/NDJSON/SSE and webhooks
+adapters/      forge, app, socket and MCP integration adapters
+automation/    workflow, bot, permission and surface automation contracts
 release/       checksums, SBOM and provenance metadata
-runtime/       engine orchestration, capability detection, worker and grouped retry context
-packager/      dist, binary, container and multi-target artifact plans
+packager/      distribution, delivery, binary, container and multi-target artifact plans
+modes/         target mode selection, deployment plans and surface profiles
 web/           root-based static marketing site with TypeScript React source
 tests/         deterministic engine and extension coverage
 docs/          architecture, API, security, release and registry notes
@@ -245,11 +291,11 @@ The engine is TypeScript-first ESM with English JSDoc comments and a generated J
 
 ## Historical documentation
 
-Earlier root README snapshots and platform READMEs remain in `docs/plans/README.md`, `docs/talks9/README.md`, `docs/talks9/README (2).md`, `android/README.md`, `browser/README.md`, `desktop/README.md`, `extension/README.md` and `ios/README.md` as archival or surface-specific evidence. Their useful architecture ideas were consolidated here, while stale `@wenathlan`, `@iakadion`, `io.devthink`, Node 20/22, `client/src`, speculative provider quotas and unimplemented hosted services were not copied into the canonical contract.
+The repository history contains 41 root README revisions and several surface-specific records. Their durable ideas are consolidated here: storage-backed execution, bounded working sets, replaceable runners, content extraction, browser actions, workflow delivery, multi-registry packaging, explicit recovery contracts and caller-owned integrations. Historical references that describe superseded identities, obsolete Node baselines, speculative provider quotas, unavailable hosted services or removed layouts remain historical evidence rather than current promises.
 
 ## Current scope
 
-Version 1.8.14 extends the TypeScript-first engine with flat project-owned desktop, Android and iOS build surfaces, explicit Capacitor staging boundaries, dotted release asset naming, helper-binary rejection, structured extraction provenance, browser context budgets, resumable workflow compensation, retention metadata and a container image that is pulled and smoke-tested after publication. Browser binaries, provider credentials, n8n host registration, persistent databases, captcha solvers and production deployment remain caller-selected adapters. Future work should extend contracts without coupling the core to one forge, registry, browser or storage vendor.
+Version 1.8.19 organizes the existing engine into twenty documented, dependency-directed domains and keeps the root package as a universal, transport-neutral router. The web playground continues to demonstrate request, policy and handoff states using a fixed fixture with no operational adapter. Browser binaries, provider credentials, hosted automation registration, persistent databases, captcha solvers, remote execution and production deployment remain caller-selected adapters. Future work should extend contracts without coupling the core to one forge, registry, browser or storage vendor.
 
 ## License