@wenathlan/saddle 1.8.17 → 2.0.2

package/docs/planning.1.8.19.md

@@ -0,0 +1,49 @@
+# Saddle 1.8.19 planning base
+
+## Product direction
+
+Saddle 1.8.19 prioritizes a **virtual control plane**. The library can represent, validate, compare, deny and hand off requests for virtual storage, binary processing, containers, micro-VMs and browser sessions. It does not silently access a user's device, installed browser, browser profile, local files, local storage, credentials, process table or network configuration.
+
+“Virtual” is an operational property of a caller-owned remote adapter and its host. A browser-only demonstration, an in-memory object or an in-process cache cannot be represented as a virtual machine, remote browser or remote storage service. Every operational effect requires an explicit policy, approval, named adapter and receipt.
+
+## Browser direction
+
+| Surface | 1.8.19 interpretation | Operational boundary |
+| --- | --- | --- |
+| Saddle Browser | A custom visual shell, session manifest and adapter-selection surface. | It becomes a remote isolated browser only when a caller supplies a verified browser-runtime adapter. |
+| Chromium family | Capability adapters for Chromium, Chrome, Edge, Brave, Vivaldi, Opera and compatible distributions. | One selected remote image or executable has one declared engine and distribution; the root does not install or control it. |
+| Gecko family | Capability adapters for Firefox, Tor Browser and compatible Gecko distributions. | A Gecko adapter is distinct from a Chromium adapter and must have its own capability receipt. |
+| WebKit family | A future capability adapter family, included in planning for broad engine coverage. | No WebKit runtime is claimed or activated by 1.8.19 planning. |
+| Remote browser service | An adapter contract compatible with an operator-hosted browser container or remote-display service. | It requires a host, runtime/image, network and authentication policy owned by the operator. |
+
+The product must not claim that a single “master browser” merges the Chromium and Gecko engines. The realistic path is one custom Saddle Browser experience that selects among independently built and independently evidenced engine adapters.
+
+## Virtual execution direction
+
+| Request | Root-library result | Required operational adapter |
+| --- | --- | --- |
+| Remote artifact transfer | A bounded storage plan, policy decision and handoff reference. | A caller-owned remote storage adapter. |
+| Binary processing | An inspection, transform or execution plan with no local effect. | A caller-owned WASM, container, process, micro-VM or remote-runner adapter. |
+| Container job | An image, platform, limits and receipt requirement. | An operator-owned OCI runtime and host. |
+| Micro-VM job | Kernel/image/limit/network requirements and a lifecycle receipt schema. | An operator-owned micro-VM host with real virtualization support. |
+| Browser session | Engine preference, profile policy, network policy and capability request. | An operator-owned remote-browser adapter. |
+
+## Neko-derived architecture evidence
+
+Neko describes itself as a self-hosted virtual browser that runs in Docker and streams a desktop using WebRTC. Its public GitHub workflow builds a base image and separate application images through a matrix of browser and desktop choices, with platform declarations rather than a merged browser engine.[1] Its documentation makes file uploads/downloads and persistent browser profiles explicit policy changes, and its remote transport requires WebRTC networking or a TURN configuration.[2]
+
+Saddle can adopt these **architectural lessons** without copying Neko or assuming its infrastructure exists: use a base runtime plus distinct engine images, record platform/image capability receipts, treat remote display as a transport adapter, keep browser profile persistence opt-in, and separate build workflows from service operation. A Neko-compatible adapter remains a future integration point; it is not an embedded service in the package.
+
+## 1.8.19 first implementation selection
+
+The first implementable block is an additive **remote-browser capability contract** that extends the 1.8.18 denied-by-default isolation API. It must represent engine family, distribution, session policy, display transport, image reference, storage policy, capability receipt and adapter handoff. Deterministic tests will verify selection and denial states without starting a browser, container, micro-VM or network service.
+
+## Artifact recovery boundary
+
+The public `v1.8.18` tag and the packages already released from it remain immutable. Failed desktop and mobile release jobs used the tagged source that predated the web alias correction. Rerunning such a job would repeat the old source failure; a complete corrected desktop/mobile asset matrix therefore requires a later version after the 1.8.19 source is approved. The 1.8.18 package registries, Pages deployment and successful workflow evidence remain separate from missing release attachments.
+
+## References
+
+[1] [Neko repository and GHCR image build workflow](https://github.com/m1k1o/neko)
+
+[2] [Neko documentation: browser images, WebRTC, storage and profile policies](https://neko.m1k1o.net/docs/v2)

package/docs/releasenotes-1.8.17.md

@@ -30,6 +30,12 @@ The release workflows derive all names from `v1.8.17`. The expected artifact mat
 
 These notes describe the release candidate and expected outputs. Registry availability, image index contents, scan results, signatures, SBOM validity, Android signing, iOS artifacts, and any platform-specific execution claim are recorded only after the relevant workflow output independently confirms them.
 
+## Verified publication results
+
+The published [v1.8.17 release](https://github.com/wenathlan/saddle/releases/tag/v1.8.17) is neither a draft nor a prerelease and contains **38 attached assets**: 20 primary artifacts, nine manifests, and nine checksum files. The desktop, mobile, extension, and target workflows completed successfully. The Android manifest records `ci-test-key` and the container manifest records `caller-owned`; neither state is presented as production signing or registry trust.
+
+The six tag-driven registry workflows completed successfully in container-first order: GHCR, GitHub Packages npm, public npmjs, Maven, NuGet GitHub Packages, and RubyGems. GHCR run `31847952976` passed its QEMU-enabled build, scan, publication, manifest-index assertion for `linux/amd64`, `linux/arm64`, and `linux/ppc64le`, amd64 pull, OCI version-label comparison, and `saddle help` smoke test.
+
 ## References
 
 [1]: https://docs.docker.com/build/building/multi-platform/ "Docker multi-platform builds"

package/docs/releasenotes-1.8.18.md

@@ -0,0 +1,32 @@
+# Saddle 1.8.18
+
+Saddle 1.8.18 adds a data-only isolation planning surface and a single-site playground. It does not turn the package into a VPS, a micro-VM, a database host, a remote browser, or an executor. A binary, browser, container, provider, storage, database, network, or host operation remains unavailable until an operator supplies a compatible adapter, an explicit policy and a matching approval. The initial web projection uses a fixed safe fixture and produces only plans, denials or caller-owned handoffs.
+
+## Changes
+
+| Area | Change |
+| --- | --- |
+| Isolation contracts | Adds `executionrequest`, `executiondecision` and `executionhandoff` to normalize intent, make the default denial explicit and render an adapter handoff without invoking it. |
+| Internal API | Adds `internalenvelope` and `internalapi` for typed gateway, planning, policy, materialization, execution, persistence and evidence projections. |
+| Package surface | Adds `@wenathlan/saddle/isolation` as a narrow browser-safe subpath instead of requiring the complete root export graph. |
+| Default posture | Rejects effects without matching effect policy, target policy, approval, adapter capability and named adapter owner. The decision contains no effect invocation. |
+| Playground | Adds the unified `/playground` route under `web/`, showing a fixed descriptor, six internal boundaries and the difference between denial and a still-non-executing handoff. |
+| Versioning | Aligns active package, registry, native, extension, crawler, Capacitor and iOS metadata to `1.8.18`, with iOS build number `1008018`. |
+
+## Operational boundary
+
+An in-memory object, an in-memory database or a JavaScript data structure runs on the resources of its process host. It is not a VPS or a micro-VM. A remote browser, OCI sandbox, WebAssembly runtime and KVM micro-VM likewise require a real operator host and resource budget. The library does not select, pay for, create or use any such infrastructure. The new contracts make those future integration points explicit without activating them.
+
+## Expected artifact matrix
+
+The tag-driven release workflow derives names from `v1.8.18`. If the platform workflows complete, the candidate matrix contains the following 38 release assets. This is an expected matrix, not a claim that assets, registry entries, signatures, scans or platform execution have already been independently verified.
+
+| Class | Expected assets |
+| --- | --- |
+| Primary artifacts | `saddle.aab.1.8.18.aab`, `saddle.apk.1.8.18.apk`, `saddle.browser.1.8.18.arm64.app.zip`, `saddle.browser.1.8.18.arm64.appimage`, `saddle.browser.1.8.18.arm64.deb`, `saddle.browser.1.8.18.arm64.dmg`, `saddle.browser.1.8.18.arm64.exe`, `saddle.browser.1.8.18.arm64.msi`, `saddle.browser.1.8.18.arm64.rpm`, `saddle.browser.1.8.18.x64.app.zip`, `saddle.browser.1.8.18.x64.appimage`, `saddle.browser.1.8.18.x64.deb`, `saddle.browser.1.8.18.x64.dmg`, `saddle.browser.1.8.18.x64.exe`, `saddle.browser.1.8.18.x64.msi`, `saddle.browser.1.8.18.x64.rpm`, `saddle.browser.1.8.18.x86.exe`, `saddle.browser.1.8.18.x86.msi`, `saddle.container.1.8.18.tar.gz`, `saddle.extension.1.8.18.zip` |
+| Manifests | `manifest.android.1.8.18.json`, `manifest.container.1.8.18.json`, `manifest.desktop.linux.arm64.1.8.18.json`, `manifest.desktop.linux.x64.1.8.18.json`, `manifest.desktop.macos.arm64.1.8.18.json`, `manifest.desktop.macos.x64.1.8.18.json`, `manifest.desktop.windows.arm64.1.8.18.json`, `manifest.desktop.windows.x64.1.8.18.json`, `manifest.desktop.windows.x86.1.8.18.json` |
+| Checksums | `sha256.android.1.8.18`, `sha256.container.1.8.18`, `sha256.desktop.linux.arm64.1.8.18`, `sha256.desktop.linux.x64.1.8.18`, `sha256.desktop.macos.arm64.1.8.18`, `sha256.desktop.macos.x64.1.8.18`, `sha256.desktop.windows.arm64.1.8.18`, `sha256.desktop.windows.x64.1.8.18`, `sha256.desktop.windows.x86.1.8.18` |
+
+## Verification boundary
+
+The deterministic engine suite has passed 139 active tests for this candidate. The web TypeScript check and static build have passed, and the `/playground` route was manually verified in its denial and handoff-projection states. Registry availability, image manifest inspection, scan results, signing status, SBOM validation, Android signing, iOS artifacts and attached release assets must be recorded only after their relevant workflow outputs independently complete.

package/docs/releasenotes-1.8.19.md

@@ -0,0 +1,35 @@
+# Saddle 1.8.19 release notes
+
+## Release intent
+
+Version **1.8.19** reorganizes the existing Saddle implementation into **twenty correlated logic domains**. It is an architecture and maintainability release: it does not remove public features, introduce an implicit infrastructure provider, or relax the existing default-denial boundaries for browser, filesystem, storage, network, runner and remote-provider effects.
+
+## Architecture changes
+
+| Domain change | Result | Compatibility boundary |
+| --- | --- | --- |
+| Public root router | The package root re-exports coherent domain façades rather than a long undifferentiated module list. | The root remains transport-neutral. |
+| Foundation and execution | Domain nouns moved into `core/`; queues, workflow dispatch and session behavior moved into `runtime/`. | Published session and queue subpaths resolve to their new compiled files. |
+| Communication and adapters | JSON-family protocol, webhook and MCP logic moved into API and adapter contexts. | API names and MCP command behavior remain unchanged. |
+| Automation and modes | Workflow, bot and automation surfaces share an automation context; target profiles belong to modes. | Bot and surface-requirement subpaths remain available. |
+| Distribution and acquisition | Delivery and proxy-pool logic now live beside their related package and scrape contracts. | Delivery and deploy subpaths remain available. |
+
+The complete ownership map and dependency-flow diagram are included with the package documentation. The only allowed effects remain caller-owned adapters that are explicitly supplied and approved at invocation time.
+
+## Package and native metadata
+
+| Surface | Active version |
+| --- | --- |
+| npm, Maven, NuGet and RubyGems | `1.8.19` |
+| Desktop and extension | `1.8.19` |
+| Capacitor mobile metadata | `1.8.19` |
+| iOS marketing version / build number | `1.8.19` / `1008019` |
+| Robots user agent | `Saddle/1.8.19` |
+
+## Validation evidence
+
+The source tree passed the engine build, **140 active Node tests**, **69 legacy Vitest tests**, web type checking and production build, flat-native ownership validation, format checking, npm pack dry-run, diff integrity checking, and a production dependency audit with no reported vulnerabilities. A web build produced a bundle-size advisory for a JavaScript chunk over 500 kB; this is a non-blocking bundler warning, not a failing gate.
+
+## Release boundary
+
+This document records publication readiness only. It does **not** claim that registries, remote runners, signing services, hosted browsers or native packages have been activated. A tag and release remain separate operator actions and must be created only after the validated commit is available on the main branch.

package/docs/research-1.8.18-isolation.md

@@ -0,0 +1,43 @@
+# 1.8.18 isolation research record
+
+## Purpose
+
+This record classifies operational prerequisites for the execution adapters proposed for Saddle 1.8.18. It is evidence for planning only; it does not add a provider dependency, provision infrastructure, or assert that Saddle already operates any of the listed systems.
+
+## Findings
+
+| Technology | Verified finding | Saddle disposition |
+| --- | --- | --- |
+| Neko | Neko is a self-hosted remote browser or desktop built around container images and WebRTC. Operation requires image selection, networking, authentication, and usually a TURN or port-routing strategy. Browser persistence and file access require explicit policy or volume configuration. | Treat as a caller-owned remote-browser adapter candidate. The root library can describe requirements and validate a receipt; it cannot claim remote browser isolation without a configured operator deployment. |
+| gVisor | gVisor supplies the OCI `runsc` runtime for sandboxed containers. It has its own compatibility and performance boundaries and is not a conventional virtual machine. | Treat as a caller-owned OCI isolation adapter candidate. A plan must declare the image, mount, network, resource and receipt policy before dispatch. |
+| Firecracker | Firecracker runs KVM micro-VMs and requires host KVM access, a compatible Linux architecture, kernel image, root filesystem image, and production jailer configuration. | Treat as a caller-owned micro-VM adapter candidate requiring dedicated host infrastructure. It cannot run in the transport-neutral root or be promised by the static website. |
+
+## Planning implication
+
+The feasible 1.8.18 foundation is a serializable, denied-by-default execution plan plus adapter interfaces and capability receipts. The initial `web/` playground can let an operator create and inspect plans, binary metadata and policy outcomes with safe local fixtures. It must not execute uploaded binaries, create sandboxes, attach to Docker, start browser sessions, manage credentials, or expose a network target without a separately configured backend.
+
+## Submitted-material synthesis
+
+The submitted conversation records request that the former multi-site design be consolidated into one `web/` site. The useful architectural intent is a single user-facing surface that has internal API boundaries corresponding to a gateway, a plan coordinator, a working-set/materialization layer, an executor boundary, a persistence boundary, and a receipt/audit projection. That intent is compatible with Saddle's contract model when each boundary is represented by a deterministic in-memory demonstration adapter by default.
+
+The same records contain several claims that must not become product statements. A static site cannot be a server, a VPS, or a micro-VM by itself. An in-memory filesystem, SQLite `:memory:`, PouchDB memory adapter, or JavaScript object graph still consumes the memory and CPU of whichever process hosts it; it provides data isolation or a logical model, not no-hardware computation. An actual remote browser, binary processor, container, gVisor sandbox, or Firecracker micro-VM necessarily runs on some host and consumes its resources. A persistent embedded database necessarily consumes the host's storage. Those capabilities therefore remain disabled unless the caller explicitly provides an adapter and an approval; the default playground will demonstrate planning and denial paths only.
+
+The requested product default is consequently recorded as: no user-machine access, no implicit network call, no provider account, no paid product, no free-tier product, no local disk use, no binary execution, no browser launch, and no remote dispatch. A caller may add a local, remote, storage, database, browser, container, or micro-VM adapter later, but the receipt must identify that it was enabled and what resources it is permitted to use.
+
+## Submitted material provenance
+
+1. User-provided `CONVERSA25.txt`
+2. User-provided `CONVERSA26.txt`
+3. User-provided `CONVERSA27.txt`
+4. User-provided `conversa.txt`
+5. User-provided `pasted_content.txt`
+
+## Playground verification
+
+The unified `/playground` route was built and inspected through a temporary preview. The rendered page presents the six internal boundaries, the fixed binary descriptor, a default `EXECUTION_POLICY_DENIED` projection with an empty effects list, and an optional handoff projection that remains explicitly non-executing. The navigation includes the new Playground route and the page copy distinguishes internal typed envelopes from hidden endpoints, second sites, remote machines, or active infrastructure. The responsive layout presents the boundary map as an editorial six-stage band and places the policy-state projection beside its two state controls without visually implying that either button starts an executor. Selecting the optional state changed the projection to `CALLER_ADAPTER_REQUIRED` with `caller-delegates` and an empty effects array; it did not add a real adapter or initiate an operation.
+
+## Sources
+
+1. [Neko documentation](https://neko.m1k1o.net/docs/v2)
+2. [Firecracker getting started guide](https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md)
+3. [gVisor documentation](https://gvisor.dev/docs/)

package/docs/research-1.8.19-virtual-browser.md

@@ -0,0 +1,27 @@
+# 1.8.19 virtual browser research record
+
+## Scope
+
+This record evaluates Neko as a public reference for remote browser architecture. It is not an instruction to deploy Neko, a Docker runtime, a TURN server, a browser image or a micro-VM.
+
+## Findings
+
+| Finding | Planning consequence |
+| --- | --- |
+| Neko is self-hosted, uses Docker and streams a desktop through WebRTC. | A browser service requires an operator-managed runtime, network and remote-display transport; it cannot live inside a static package or GitHub Pages site. |
+| Neko's GHCR workflow builds a base image then runs a matrix for separate Firefox, Chromium, Chrome, Edge, Brave, Vivaldi, Opera, Tor Browser and desktop images. | Saddle should model engine and distribution selection as separate capabilities rather than claim source-level fusion of browser engines. |
+| Neko treats file access and browser profile persistence as explicit configuration changes. | Saddle must keep transfers, downloads, uploads and persistence denied by default and adapter-owned. |
+| Neko's remote interaction relies on WebRTC networking, with additional TURN or port configuration in some deployments. | A Saddle remote-browser adapter needs display transport, signaling, authentication and network-policy declarations before a real session can be claimed. |
+| Neko supports other Linux desktop applications in addition to browsers. | Saddle can generalize its remote-runner contract beyond browsers while keeping every effect outside the root library. |
+
+## Disposition
+
+1.8.19 will introduce a data-only remote-browser capability model and test fixtures first. It will not bundle Neko, browser binaries, Docker, container images, TURN credentials, browser profiles or a persistent remote browser service. Those are future caller-selected adapters and operator deployments.
+
+## Sources
+
+- https://github.com/m1k1o/neko
+- https://raw.githubusercontent.com/m1k1o/neko/master/.github/workflows/ghcr.yml
+- https://raw.githubusercontent.com/m1k1o/neko/master/.github/workflows/image_base.yml
+- https://raw.githubusercontent.com/m1k1o/neko/master/.github/workflows/image_app.yml
+- https://neko.m1k1o.net/docs/v2