@wenathlan/saddle 1.8.16 → 1.8.18

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/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/todo-1.8.16.md

@@ -634,18 +634,102 @@
 - [ ] Update package exports only for stable, explicitly documented additive contracts.
 - [ ] Update type declarations and package-import tests for every export-map change.
 - [ ] Update changelog.md from verified completed work rather than the original research hypothesis.
-- [ ] Create docs/releasenotes-1.8.16.md only after artifact inventory, signing status, workflows, and registry results are known.
-- [ ] Update docs/artifactavailability.md only from generated and remotely verified release evidence.
-- [ ] Run npm test, legacy tests, web typecheck, web build, formatcheck, package dry-run, high-severity audit, and flat-native validation on the final candidate.
-- [ ] Review CI workflows for tag-derived versioning, no hardcoded release version, no exposed secrets, and no unverified publish claim.
+- [x] Create docs/releasenotes-1.8.16.md only after artifact inventory, signing status, workflows, and registry results are known. The final release record lists 38 attached assets and the manual Android fallback state.
+- [x] Update docs/artifactavailability.md only from generated and remotely verified release evidence. The 1.8.15 and 1.8.16 matrices use published release inventories.
+- [x] Run npm test, legacy tests, web typecheck, web build, formatcheck, package dry-run, high-severity audit, and flat-native validation on the final candidate. The candidate passed 136 active and 69 legacy tests with all required gates.
+- [x] Review CI workflows for tag-derived versioning, no hardcoded release version, no exposed secrets, and no unverified publish claim. Tag-triggered registry and asset workflows completed with explicit signing-state boundaries.
 - [ ] Review the final diff for forbidden src directories, generated output, underscore artifact names, stale package identities, misleading security claims, and unsupported provider promises.
 - [ ] Bump all active manifests to 1.8.16 only after all selected features and gates are complete.
 - [ ] Update the iOS build number to 1008016 only during the validated 1.8.16 manifest bump.
-- [ ] Create the 1.8.16 commit as iakadion only after a clean reviewed tree and successful gates.
-- [ ] Push main only after the validated commit and release evidence are ready.
-- [ ] Create immutable tag v1.8.16 only after confirming no historical tag is changed.
-- [ ] Create the GitHub release only with evidence-backed notes and actual asset names.
+- [x] Create the 1.8.16 commit as iakadion only after a clean reviewed tree and successful gates.
+- [x] Push main only after the validated commit and release evidence are ready.
+- [x] Create immutable tag v1.8.16 only after confirming no historical tag is changed.
+- [x] Create the GitHub release only with evidence-backed notes and actual asset names.
 - [ ] Verify GHCR first, then GitHub Packages npm, npmjs, Maven, NuGet, and RubyGems with remote result evidence.
 - [ ] Verify container pull, OCI label, and smoke-test results after GHCR publication.
 - [ ] Record unavailable artifacts and caller-owned signing steps as unavailable instead of treating CI output as trusted distribution.
 - [ ] Mark each completed 1.8.16 checklist task only after its evidence is linked from the appropriate research, implementation, test, or release record.
+
+## 9. Workflow hygiene and cache retention
+
+- [x] Inventory every YAML file under `.github`, distinguishing workflow definitions, composite-action metadata, and service-owned configuration paths. The inventory found 18 workflow definitions, two composite-action metadata files, and the required Dependabot configuration.
+- [x] Verify GitHub's current required paths for workflow files, composite actions, and Dependabot configuration before moving any YAML file. The resulting path rationale is documented in `docs/workflowoperations.md`.
+- [x] Standardize workflow definitions under `.github/workflows` without moving composite action metadata out of its executable action directory. Existing workflow definitions already use lower-case `.yml` files in that canonical directory.
+- [x] Keep Dependabot configuration in its GitHub-required location and document why it is not a runnable workflow.
+- [x] Review the mobile workflow triggers and ensure release Android artifacts can be produced automatically with an explicit non-production signing state when caller secrets are unavailable.
+- [x] Preserve production Android signing as caller-owned when all configured signing secrets are present.
+- [x] Inventory existing GitHub Actions caches by key, size, ref, last-access time, and workflow source before changing retention behavior. The initial inventory contained 85 entries and 7,785,944,423 reported bytes, dominated by CodeQL overlays.
+- [x] Add a least-privilege cache-retention workflow that deletes only caches from this repository after a documented age threshold and never deletes artifacts or release assets.
+- [x] Add bounded cache cleanup after completed workflows only where it does not remove a cache required by concurrent work. The dry-run and the successful applied run left 13 listed cache entries; repository usage totals may take several minutes to refresh.
+- [x] Add workflow validation and deterministic tests or inspections for YAML syntax, permissions, triggers, and cache deletion scope.
+- [x] Record the resulting cache policy, manual fallback, and non-goals in release or operational documentation.
+
+## 10. Version 1.8.17 container platform expansion
+
+- [x] Inventory the platforms and digests present in the published 1.8.16 container manifest before changing the build matrix. The release manifest identified a container archive and image reference but did not claim an OCI platform index.
+- [x] Compare requested operating-system and architecture combinations against Docker Buildx, OCI image-index, Node runtime, and runner support.
+- [x] Distinguish publishable Linux OCI variants from Windows container variants that require a compatible Windows base image and Windows runner.
+- [x] Avoid claiming an `unknown` platform as a runnable operating-system or architecture target.
+- [x] Select a supported 1.8.17 Linux multi-architecture matrix and record rejected or deferred combinations with their technical reason in `docs/containerplatforms-1.8.17.md`.
+- [x] Review the current container workflow, image base, tags, OCI labels, post-push pull, label verification, and smoke test before modifying it.
+- [x] Extend the container workflow only for platform combinations that can build and execute the packaged Saddle runtime: `linux/amd64`, `linux/arm64`, and `linux/ppc64le`.
+- [x] Keep release-tag version derivation, registry credentials, permissions, and the container-first documentation order intact.
+- [x] Update every active 1.8.16 version metadata location to 1.8.17 after the implementation scope is validated.
+- [x] Update release notes, changelog, registry and artifact documentation with an accurate platform matrix and no unverified image claims.
+- [x] Validate YAML formatting, package and engine gates, workflow logic, package dry-run, high-severity audit, flat-native validation, and whitespace before creating the 1.8.17 tag.
+- [x] Publish and inspect the 1.8.17 release, all registry workflows, container manifest platforms, post-push label checks, and smoke-test results. The public release contains 38 assets; GHCR run `31847952976` verified `linux/amd64`, `linux/arm64`, and `linux/ppc64le` and completed the amd64 label and CLI smoke checks.
+
+## 11. Version 1.8.17 README consolidation and archival request
+
+- [x] Inventory every historical `README.md` revision with Git before selecting durable content for the current README. The root history contains 41 revisions and separate platform README paths.
+- [x] Consolidate still-relevant capabilities, installation paths, modes, packaging surfaces, and limits into an external consolidation record while preserving the README scope reference.
+- [x] Update active release references to `1.8.17` while preserving historical release records as history rather than overwriting them.
+- [ ] Remove direct links or filename references to documents inside `docs/` from the README; retain only appropriate root-document references.
+- [x] Inventory the exact user-requested documentation range before any archive operation and exclude the archive itself from recursive inputs.
+- [x] Receive a user-supplied passphrase before creating an encrypted archive; do not generate an unrecoverable undocumented credential.
+- [x] Create and verify the requested encrypted archive only after the passphrase and archive scope are explicit. The verified list contains 199 files and 13 directory entries with unrelated assets excluded.
+- [x] Preserve the current README as a non-deterministic scope reference; record the historical consolidation and active 1.8.17 reference matrix outside that file.
+- [x] Build the encrypted package from `docs/logs`, `docs/plans`, `docs/sources`, and `docs/talks1` through `docs/talks9`, excluding unrelated `docs/assets` content and the generated archive itself.
+
+## 12. Encrypted documentation relocation
+
+- [x] Move the verified encrypted package from the repository root into `docs/` without changing its bytes.
+- [x] Remove only `docs/logs`, `docs/plans`, `docs/sources`, and `docs/talks1` through `docs/talks9` after the package is present at its destination.
+- [x] Verify that `docs/assets` and all remaining top-level documentation files survive the removal before committing.
+
+## 13. README version-reference audit
+
+- [x] Enumerate every version reference in the current README and every historical root README revision with Git. The root history contains 41 revisions and the current README retains 1.8.14 scope statements.
+- [x] Distinguish active metadata from immutable historical release evidence and identify stale version statements.
+- [x] Preserve the current README as a scope reference while recording the complete capability consolidation outside it.
+- [x] Ensure the external consolidation uses the active 1.8.17 matrix and does not contain direct links to materials inside `docs/`.
+- [x] Validate and commit the version-reference audit without rewriting the README scope document.
+
+## 14. Whole-repository active-version audit
+
+- [x] Enumerate every tracked current-file reference to a pre-1.8.17 version and classify it as active metadata, test fixture, changelog, release evidence, research, or scope text.
+- [x] Inspect every historical root README revision for durable behavior not yet represented in the external consolidation.
+- [x] Update any discovered active metadata to 1.8.17 while preserving tests, historical records, and scope references. No old Saddle product metadata remained; the Android build-variable match is an AndroidX dependency.
+- [x] Expand the external consolidation with the complete classification and durable historical behavior, without direct links to internal materials.
+- [x] Validate and commit the whole-repository version audit without reworking the README scope document. The only excluded non-product token is an AndroidX dependency version.
+
+## 15. Direct README re-evaluation request
+
+- [ ] Inventory the README's release badge, current-scope statements, historical sections, and direct internal references.
+- [ ] Compare every affected section with all historical root README revisions before deciding whether it can represent 1.8.17 truthfully.
+- [ ] Identify the exact set of active release references that could be updated without rewriting the preserved scope document or corrupting historical evidence.
+- [ ] Validate and record the direct README re-evaluation outcome.
+
+## 16. npm distribution and 1.8.18 planning base
+
+- [x] Inspect the package dry-run contents to confirm which README the npm package distributes and whether a separate distribution document exists. The package contains the root README and the extension README; no separate distribution README exists.
+- [x] Map each durable capability from the 41 historical README revisions into the consolidated planning base for 1.8.18.
+- [x] Record any permitted active metadata alignment separately from the immutable README scope reference.
+- [x] Validate and commit the 1.8.18 planning base without replacing the README scope document.
+
+## 17. README publication consolidation request
+
+- [x] Build a section-by-section matrix across the 41 root README revisions and the current README.
+- [x] Identify all release references that describe the active package rather than historical evidence or fixture state.
+- [x] Consolidate the README into foundation, engine, productization, API, extension, security, package, development, CLI, repository, history and current-scope sections while preserving historical evidence accurately.
+- [x] Validate the README-facing update through `npm pack --dry-run`; the resulting `@wenathlan/saddle@1.8.17` package contains the root README.

package/docs/todo-1.8.18.md

@@ -0,0 +1,152 @@
+# Saddle 1.8.18 — isolated execution and binary-processing plan
+
+> This plan contains **920 individual actions**. It uses 92 unchecked work packages, each with ten ordered actions: **inspect, extract, classify, design, implement, test, boundary-test, review, document, and record**. The ten actions apply to the exact subject named by each work package; a package may be marked complete only after all ten actions have evidence.
+
+## Completion guardrails
+
+| Rule | Requirement |
+| --- | --- |
+| Truthfulness | A contract may describe, plan, validate, or invoke isolation. It must not claim to provide a VPS, micro-VM, browser isolation, persistent database, GPU, signing, or a remote service unless the caller supplies and verifies the corresponding adapter. |
+| Isolation | Untrusted bytes are never executed by the transport-neutral root. Execution requires a caller-owned isolated-runner adapter and an explicit policy. |
+| Storage | Remote storage is durable state, not literal RAM or VRAM. Materialization remains bounded, measurable, and caller-owned. |
+| Effects | Network, browser, container, filesystem, database, credentials, dispatch, retention, and deletion remain explicit privileged effects. |
+| Compatibility | New contracts are additive, TypeScript-first, dependency-free, serializable, root-first, and use deterministic tests. |
+| Publishing | Release work begins only after all gates pass and every version-bearing manifest agrees on `1.8.18`. |
+
+## 1. Scope source audit — actions 001–100
+
+- [ ] **001–010.** Read README source lines 001–200; extract architecture, mode, and naming requirements.
+- [ ] **011–020.** Read README source lines 201–400; extract execution, binary, and isolation requirements.
+- [ ] **021–030.** Read README source lines 401–600; extract storage, memory, and provider assertions.
+- [ ] **031–040.** Read README source lines 601–800; extract runner, workflow, and deployment assertions.
+- [ ] **041–050.** Read README source lines 801–1000; extract agent, browser, scrape, and bot assertions.
+- [ ] **051–060.** Read README source lines 1001–1200; extract protocol, database, and API assertions.
+- [ ] **061–070.** Read README source lines 1201–1400; extract package, native, and extension assertions.
+- [ ] **071–080.** Read README source lines 1401–1600; extract web, playground, and UI assertions.
+- [ ] **081–090.** Read README source lines 1601–1848; extract release, quality, and governance assertions.
+- [ ] **091–100.** Compare the extracted source claims with current 1.8.17 code, tests, manifests, and shipped artifacts.
+
+## 2. Feasibility, terminology, and capability evidence — actions 101–200
+
+- [ ] **101–110.** Classify every source claim as shipped, adapter-ready, research-only, deferred, infeasible, or policy-rejected.
+- [ ] **111–120.** Define precise vocabulary for process plan, isolated execution, sandbox adapter, container adapter, micro-VM adapter, and remote runner.
+- [ ] **121–130.** Define precise vocabulary for durable storage, working set, cache, mmap, tmpfs, memory pressure, and materialization.
+- [ ] **131–140.** Define precise vocabulary for binary inspection, binary transform, binary execution, binary artifact, and binary provenance.
+- [ ] **141–150.** Define precise vocabulary for browser transport, browser session, browser isolation, browser action, and browser evidence.
+- [ ] **151–160.** Define precise vocabulary for edge processing, third-party runner, provider chain, job lease, and artifact boundary.
+- [ ] **161–170.** Define a claim-evidence schema that distinguishes declared capability from verified capability and observed result.
+- [ ] **171–180.** Define a capability receipt schema for platform, architecture, isolation mechanism, limits, and adapter identity.
+- [ ] **181–190.** Define a policy vocabulary for allowed, denied, approval-required, unknown, expired, and unsupported execution requests.
+- [ ] **191–200.** Document the non-goals: no false VPS, no hidden credentials, no arbitrary code execution in the root, and no quota evasion.
+
+## 3. Execution-policy contracts — actions 201–300
+
+- [ ] **201–210.** Design the serializable execution-request contract with input reference, target, policy, and artifact destination.
+- [ ] **211–220.** Design the serializable execution-policy contract with network, filesystem, process, time, memory, and output limits.
+- [ ] **221–230.** Design the serializable execution-plan contract that separates planning from privileged execution.
+- [ ] **231–240.** Design the serializable execution-receipt contract for adapter identity, limits, timings, exit classification, and artifacts.
+- [ ] **241–250.** Design the serializable execution-evidence contract for hashes, logs, retention intent, and verification state.
+- [ ] **251–260.** Design the isolated-runner adapter interface without importing Docker, Firecracker, Playwright, or provider SDKs in the root.
+- [ ] **261–270.** Design the cancellation and unknown-remote-state contract with no false rollback claims.
+- [ ] **271–280.** Design the admission-control contract for queue budget, concurrency budget, working-set budget, and execution quota.
+- [ ] **281–290.** Design the explicit approval token and consent correlation contract for privileged execution requests.
+- [ ] **291–300.** Design deterministic fixture shapes for accepted, denied, expired, unsupported, cancelled, and unknown execution states.
+
+## 4. Binary inspection and transformation contracts — actions 301–400
+
+- [ ] **301–310.** Define a binary-source contract for inline bytes, durable artifact references, and caller-owned streams.
+- [ ] **311–320.** Define bounded binary metadata inspection based on magic bytes, size, digest, and declared media type.
+- [ ] **321–330.** Define binary classification results for archive, executable, document, image, model, unknown, and malformed input.
+- [ ] **331–340.** Define the binary-transform plan contract with deterministic input, options, cache identity, and output expectations.
+- [ ] **341–350.** Define the transform adapter interface for caller-owned WASM, native, container, or remote execution paths.
+- [ ] **351–360.** Define archive-inspection contracts that list entries and limits without extracting untrusted content.
+- [ ] **361–370.** Define archive-extraction plans that require a caller-owned extraction adapter and explicit path controls.
+- [ ] **371–380.** Define binary-output verification for digest, byte count, media type, expected structure, and provenance.
+- [ ] **381–390.** Define binary-processing failure taxonomy for malformed, oversized, unsupported, denied, timeout, and verification failure.
+- [ ] **391–400.** Define deterministic binary fixtures and fuzz boundaries without storing unsafe executable payloads in the repository.
+
+## 5. Working-set, storage, and materialization contracts — actions 401–500
+
+- [ ] **401–410.** Define working-set admission estimates for byte size, range support, locality, and required transforms.
+- [ ] **411–420.** Define bounded range materialization plans for local, remote, chunked, and content-addressed storage adapters.
+- [ ] **421–430.** Define cache identity, cache freshness, cache evidence, and caller-owned eviction plans.
+- [ ] **431–440.** Define temporary materialization lifecycle states from planned through verified cleanup intent.
+- [ ] **441–450.** Define storage capability receipts for range reads, writes, integrity checks, regions, and retention constraints.
+- [ ] **451–460.** Define integrity verification for chunks, manifests, content addresses, and reconstructed binary artifacts.
+- [ ] **461–470.** Define storage-pool policy for primary, mirror, fan-out, quorum, repair planning, and no-background-retry limits.
+- [ ] **471–480.** Define memory-pressure decisions that remain declarative and never claim local or remote RAM ownership.
+- [ ] **481–490.** Define storage-to-execution handoff records with bytes, hash, policy identity, and recipient adapter identity.
+- [ ] **491–500.** Define deterministic tests for working-set budgets, range support, corrupt members, and cleanup-plan generation.
+
+## 6. Runner, provider-chain, and remote-isolation adapters — actions 501–600
+
+- [ ] **501–510.** Define runner capability declarations for process, container, micro-VM, browser, network, and hardware attributes.
+- [ ] **511–520.** Define runner eligibility evaluation with explicit requirements and no provider-specific implicit fallback.
+- [ ] **521–530.** Define deterministic provider-chain selection from declared capabilities, policy, preference, and evidence.
+- [ ] **531–540.** Define runner dispatch plans that remain effect-free until a caller-provided adapter executes them.
+- [ ] **541–550.** Define GitHub Actions runner adapter requirements without treating an ephemeral workflow as a permanent VPS.
+- [ ] **551–560.** Define Forgejo, Gitea, GitLab, Codeberg, and Woodpecker adapter requirements without embedding tokens or endpoints.
+- [ ] **561–570.** Define container-runner adapter requirements for image identity, read-only input, bounded mounts, resource limits, and receipt evidence.
+- [ ] **571–580.** Define micro-VM adapter requirements for kernel/image provenance, CPU/memory limits, network policy, and lifecycle receipt.
+- [ ] **581–590.** Define remote cancellation, observation, and handoff semantics when provider state is delayed, unknown, or unavailable.
+- [ ] **591–600.** Define deterministic fake-runner tests proving planning, policy denial, adapter selection, and receipt validation without remote execution.
+
+## 7. Agent browser, scrape, and MCP capability contracts — actions 601–700
+
+- [ ] **601–610.** Define browser-session capability receipts for transport, isolation claim, headless state, and permitted actions.
+- [ ] **611–620.** Define browser-action request and evidence contracts for navigation, click, type, capture, and download planning.
+- [ ] **621–630.** Define browser isolation requirements that require a caller-owned transport and cannot be inferred from a UI label.
+- [ ] **631–640.** Define snapshot, frame, tab, and context-budget handoffs between browser adapters and agent logic.
+- [ ] **641–650.** Define scrape-request consent, robots, freshness, cache, provenance, and bounded-output policy contracts.
+- [ ] **651–660.** Define crawler frontier, domain budget, retry, queue, and cancellation contracts with explicit persistence ownership.
+- [ ] **661–670.** Define proxy and captcha boundaries as caller-owned evidence or adapters, never bundled bypass behavior.
+- [ ] **671–680.** Define MCP tool declarations for execution planning, binary inspection, capability evaluation, and artifact evidence.
+- [ ] **681–690.** Define SaddleBot task boundaries for explicit operator commands, message provenance, and no autonomous credential handling.
+- [ ] **691–700.** Define deterministic tests for browser evidence, scraper freshness, crawl budgets, MCP serialization, and bot policy rejection.
+
+## 8. Persistence, database, protocol, and observability contracts — actions 701–800
+
+- [ ] **701–710.** Define persistence interfaces for execution plans, receipts, evidence, artifacts, approvals, and resumable tasks.
+- [ ] **711–720.** Evaluate Drizzle ORM only as an optional caller-owned persistence adapter, not as a root dependency or required database.
+- [ ] **721–730.** Define relational schema projections for jobs, artifacts, leases, receipts, evidence, approvals, and retention decisions.
+- [ ] **731–740.** Define migration ownership, database credentials, tenancy, and backup policy as application-layer responsibilities.
+- [ ] **741–750.** Define JSON, NDJSON, SSE, block, and MCP representations for execution states and binary-processing progress.
+- [ ] **751–760.** Define event correlation identifiers across job, runner, artifact, approval, browser, and delivery boundaries.
+- [ ] **761–770.** Define redaction controls for logs, metadata, URLs, headers, secrets, and binary-derived strings.
+- [ ] **771–780.** Define health, heartbeat, queue depth, working-set pressure, and adapter freshness observations without false availability claims.
+- [ ] **781–790.** Define audit trail integrity for plan-to-receipt transitions, evidence references, and operator-visible denial reasons.
+- [ ] **791–800.** Define deterministic persistence-adapter tests using in-memory fakes and no mandatory database server.
+
+## 9. Unified `web/` playground — actions 801–900
+
+- [ ] **801–810.** Audit the existing root-first `web/` site, routes, assets, build script, and deployment-neutral base-path behavior.
+- [ ] **811–820.** Define the playground information architecture for capability planning, binary inspection, execution policy, receipt viewing, and integration guidance.
+- [ ] **821–830.** Define a browser-only demonstration model that uses local fixtures and does not execute uploaded or remote binaries.
+- [ ] **831–840.** Define a playground execution-plan form with explicit policy fields, bounded input options, and denial explanations.
+- [ ] **841–850.** Define a playground binary-inspection form limited to metadata and caller-selected safe sample fixtures.
+- [ ] **851–860.** Define a playground storage-to-working-set visualization that explains stages and limits without claiming RAM conversion.
+- [ ] **861–870.** Define a playground runner-selection view that compares declared capabilities and leaves dispatch disabled without an adapter.
+- [ ] **871–880.** Define a playground browser and scrape view that displays evidence boundaries, consent needs, and caller-owned transport requirements.
+- [ ] **881–890.** Define a playground integration view for library import, adapters, database option, container option, and hosted-operation prerequisites.
+- [ ] **891–900.** Define responsive, accessible, deterministic UI tests and static build verification for every new playground state.
+
+## 10. Security, quality, packaging, and 1.8.18 release — actions 901–920
+
+- [ ] **901–910.** Perform the 1.8.18 threat-model review for untrusted bytes, remote dispatch, archive handling, secrets, browser actions, SSRF, and provider boundaries.
+- [ ] **911–920.** Run final source, test, package, native, documentation, version, artifact, release-note, and registry-readiness gates before creating any 1.8.18 tag.
+
+## 11. Unified internal API architecture — actions 921–970
+
+- [x] **921–930.** Define internal API boundaries for gateway, planner, materializer, executor, persistence, and receipt projection within the single `web/` surface.
+- [x] **931–940.** Define a hard default policy that rejects user-hardware access, local execution, remote dispatch, paid providers, and free-tier providers until the caller explicitly supplies an adapter and approval.
+- [x] **941–950.** Define in-memory demonstration adapters for the six internal API boundaries that are deterministic, do not call the network, and do not execute supplied bytes.
+- [x] **951–960.** Define browser-facing internal API request and response envelopes for plan creation, policy evaluation, binary metadata inspection, and receipt projection.
+- [x] **961–970.** Define test cases proving that a missing adapter, unapproved provider, remote URL, local hardware target, or binary execution request yields a structured denial without side effects.
+
+## 12. Final version alignment and commit — actions 971–980
+
+- [x] **971–980.** Align active npm, lockfile, Maven, NuGet, RubyGems, extension, desktop, Capacitor, crawler and iOS metadata to `1.8.18`; create the candidate release note, run the release gates, inspect the npm package, configure `iakadion` authorship, commit, and push the verified source revision.
+
+## Evidence ledger
+
+Every completed ten-action work package must link its evidence to the final release record: source revision or research URL, design note, code path, deterministic test name, boundary test, documentation update, validation command, result, reviewer state, and disposition. The 970 actions deliberately start with factual classification; implementation may proceed only for capabilities that are both technically feasible and expressible without false infrastructure claims.

package/docs/workflowoperations.md

@@ -0,0 +1,32 @@
+# Workflow operations
+
+Saddle keeps executable GitHub workflow definitions in `.github/workflows`. GitHub requires workflow YAML files in that directory. The repository currently uses lower-case `.yml` names for every workflow definition.[1]
+
+Composite action metadata remains in `.github/actions/<action>/action.yml`. Those files are not standalone workflows: the repository invokes them as local actions from their directory, so moving them into the workflow directory would break their executable local-action path. Dependabot configuration remains at `.github/dependabot.yml`, which is the path GitHub requires on the default branch; it is dependency-update configuration rather than a runnable workflow.[2]
+
+## Mobile release policy
+
+The Android job first uses caller-provided production signing material only when all required repository secrets exist. If a release is published without that material, it automatically generates a temporary `ci-test-key`, attaches the APK and AAB, and records `ci-test-key` in the Android manifest. This keeps the release artifact flow automatic without representing the result as production-signed. Manual Android runs remain opt-in for the same fallback through `allow_test_signing=true`. iOS remains disabled until the caller enables its separate signing and provisioning path.
+
+## Cache retention policy
+
+The `cache retention` workflow runs after CodeQL completes and on a daily schedule. A manual run defaults to reporting candidates only; its `apply` input must be set to `true` to delete anything. It receives only `actions: write` and `contents: read`, and uses the repository-scoped cache API. It does not access artifacts, releases, packages, source checkouts, or external repositories.
+
+| Scope                                  | Retention rule                                                                  |
+| -------------------------------------- | ------------------------------------------------------------------------------- |
+| `refs/heads/main` CodeQL caches        | Retain the three most recently accessed entries.                                |
+| `refs/heads/main` Node caches          | Retain the two most recently accessed entries.                                  |
+| `refs/heads/main` Java or other caches | Retain the most recently accessed entry per family.                             |
+| Non-default refs                       | Retain entries accessed within the latest six hours, then delete older entries. |
+
+The policy is intentionally bounded because GitHub cache entries are mutable accelerators, not release evidence. GitHub documents default seven-day inactivity eviction and a default 10 GB per-repository quota; proactively keeping a small recent set prevents repeated CodeQL overlays and tag-scoped entries from consuming the whole quota.[3]
+
+Release-only target planning and GitHub Packages npm publication explicitly disable the Node package-manager cache. Those jobs receive little benefit from a tag-scoped cache and otherwise create entries that cannot be reused by the default branch.
+
+Cache deletion is idempotent: a cache may expire or be evicted between the list and delete requests. A `404` for such an entry is logged and does not stop retention of the remaining candidates.
+
+## References
+
+[1]: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions "Workflow syntax for GitHub Actions"
+[2]: https://docs.github.com/en/code-security/concepts/supply-chain-security/about-the-dependabot-yml-file "About the dependabot.yml file"
+[3]: https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching "Dependency caching reference"

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Saddle browser bridge",
-  "version": "1.8.16",
+  "version": "1.8.18",
   "description": "User initiated page snapshots through the Saddle browser contract.",
   "minimum_chrome_version": "110",
   "permissions": ["activeTab", "scripting", "storage"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/saddle",
-  "version": "1.8.16",
+  "version": "1.8.18",
   "description": "binary computing engine that turns distributed storage into a publishable working set",
   "type": "module",
   "private": false,
@@ -83,7 +83,8 @@
     "./surface-requirements": "./dist/surfaces/requirements.js",
     "./worker": "./dist/runtime/worker.js",
     "./binary-archive": "./dist/binary/archive.js",
-    "./binary-transform": "./dist/binary/transform.js"
+    "./binary-transform": "./dist/binary/transform.js",
+    "./isolation": "./dist/isolation/contracts.js"
   },
   "files": [
     "dist",

package/docs/plans/00.index.md

@@ -1,50 +0,0 @@
-# Index
-
-Project: **UKA** — computer use agent, sandbox for AI and captcha bypass. Super bot with computational memory. Package `@wenathlan/saddle`. Domain acquired.
-
-Theme: computer use, bypasses, captcha, sandbox for AI, container for AI, multi-platform bot, storage-to-compute memory transformation.
-
-## Planning Documents (`docs/plans`)
-
-| # | File | Subject |
-|---|------|---------|
-| 01 | [architecture.md](./01.architecture.md) | General system architecture |
-| 02 | [research.computer.use.md](./02.research.computer.use.md) | Research: computer use agents 2026 |
-| 03 | [research.captcha.bypass.md](./03.research.captcha.bypass.md) | Research: hcaptcha cloudflare recaptcha bypass |
-| 04 | [research.sandbox.ai.md](./04.research.sandbox.ai.md) | Research: virtual sandbox and containers for AI |
-| 05 | [capture.platform.md](./05.capture.platform.md) | Browser movement capture platform |
-| 06 | [dependencies.md](./06.dependencies.md) | 60+ project dependencies |
-| 07 | [captcha.test.page.md](./07.captcha.test.page.md) | Test page with hcaptcha cloudflare |
-| 08 | [production.infra.md](./08.production.infra.md) | Production infra (vercel/netlify) and sandbox backend |
-| 09 | [database.schema.md](./09.database.schema.md) | Database schema (drizzle/prisma/mysql2) |
-| 10 | [cloudinary.storage.md](./10.cloudinary.storage.md) | Data storage on cloudinary |
-| 11 | [movement.logs.json.md](./11.movement.logs.json.md) | JSON movement log format (brave) |
-| 12 | [research.atlas.agent.browser.md](./12.research.atlas.agent.browser.md) | Atlas: agent browser repos with same classification |
-| 28 | [action.plan.md](./28.action.plan.md) | Action plan and next steps |
-
-## Super Bot Documentation (`docs/plans`)
-
-| # | File | Subject |
-|---|------|---------|
-| 45 | [robotarchitecture.md](./45.robotarchitecture.md) | Super bot architecture overview |
-| 37 | [deploystrategy.md](./37.deploystrategy.md) | Deploy strategies (Netlify, Vercel, CI/CD, Docker, VM) |
-| 36 | [computational.memory.md](./36.computational.memory.md) | Storage-to-compute memory transformation system |
-| 39 | [multi.platform.bot.md](./39.multi.platform.bot.md) | Multi-platform bot (GitHub, GitLab, Forgejo, Gitea, Discord) |
-| 40 | [npm.publish.md](./40.npm.publish.md) | NPM package publishing (`@wenathlan/saddle`) |
-| 46 | [scdnintegration.md](./46.scdnintegration.md) | SCDN integration for assets and deployment |
-| 44 | [reference.md](./44.reference.md) | Reference index for all saddle documentation |
-| 33 | [bots.codigo.revisao.md](./33.bots.codigo.revisao.md) | Best AI code review bots (research) |
-| 32 | [bots.automacao.computacional.md](./32.bots.automacao.computacional.md) | Best computational automation bots (research) |
-| 34 | [bots.seguranca.cicd.md](./34.bots.seguranca.cicd.md) | Bot research (security + CI/CD) |
-
-## Folders
-
-- `docs/plans/` — planning and research (this index)
-- `docs/talks/` — decision transcripts
-- `docs/logs/` — JSON movement logs from Brave (`examplesession.json`)
-- `tests/` — unit tests (`examples/`, `output/`, `scripts/`)
-- `web/` — production site, deployed to Vercel or Netlify (files at root, no `src/`)
-
-## Phase Decision
-
-We are in **planning + research**. Platform implementation starts **only after user approval** (see `28.action.plan.md`).

package/docs/plans/01.architecture.md

@@ -1,86 +0,0 @@
-# 01 Architecture
-
-## Goal
-
-Build **UKA**, a computer use agent for ai that:
-
-1. Captures human movement in the browser (virtual mouse, virtual arrow, click, rotation, coordinates) in a real environment (brave / chromium).
-2. Exports movement as json logs to `docs/logs/`.
-3. Runs in a virtual sandbox to isolate ai agent execution.
-4. Faces strong captchas (hcaptcha, cloudflare turnstile, recaptcha) in controlled tests, opening test pages in brave.
-5. Persists data in production via a deployed site (vercel/netlify) plus db (drizzle/prisma/mysql2) plus cloudinary.
-
-## Architecture rules (skill arch)
-
-- No `src/` folder. Logic lives at the root of `web/`.
-- No vercel functions. No netlify functions. Use prisma, drizzle, mysql2, socket.
-- No localhost. Host is parametrized (`host`). Ports randomized then locked.
-- Files lowercase. No underscore. No hyphen. English docs. Jsdoc comments.
-- Logic grouped. Up to 20 related logics per file.
-- Runs as a library across modes (computer, browser, cli, binary, headless, etc).
-
-## Atlas (the browser)
-
-Atlas is the real browser component of UKA. It works across the 30 modes from the
-architecture skill (computer, browser, cli, binary, headless, etc) and its primary
-job is to bypass hcaptcha so the agent can act. It serves both the agent and the
-sandbox, and talks to our own database on vercel/netlify. See
-[12 research atlas agent browser](./12-research-atlas-agent-browser.md) for the
-prior-art survey and the p1 stealth / p2 vlm / p3 token fallback layering.
-
-## Components
-
-```
-atlas (web/atlas.js + deps)
-  - real browser across 30 modes
-  - stealth layer + hcaptcha bypass (vlm or token api fallback)
-  - feeds agent and sandbox
-
-capture ui (web/*.html + web/capture.js)
-  - virtual arrow / virtual mouse injected via cdp
-  - captures click, drag, scroll, coordinates, rotation
-  - exports json to docs/logs/
-
-sandbox (web/ + @vercel/sandbox)
-  - isolated firecracker microvm per session/agent
-  - chrome/brave ready, novnc streaming
-  - api https (post/get) to the deployed site
-
-production backend (web/, deployed to vercel/netlify)
-  - open node server (hono/express), not platform functions
-  - db (drizzle + mysql2 + prisma schema)
-  - cloudinary for assets and replays
-```
-
-## Main flows
-
-### A. Capture (local/dev)
-1. Open brave via playwright/chromium with `chrome.debugger` (cdp).
-2. Inject svg cursor sprite plus event listeners (`Input.dispatchMouseEvent`).
-3. Record each event with timestamp, type, coordinates, target, rng seed.
-4. Compact trajectories and export to `docs/logs/<session>.json`.
-
-### B. Captcha test
-1. Open test page (`tests/examples/hcaptchatest.html` or a real site).
-2. Run solver (hcaptcha challenger / vision) or record manual bypass.
-3. Save evidence (screenshot, token, log) to `tests/output/`.
-
-### C. Production
-1. Agent calls the deployed site api (`web/`).
-2. Backend writes session to db (drizzle/mysql2) and assets to cloudinary.
-3. Logs and replays available via get https.
-
-## Key technologies (details in `06-dependencies.md`)
-
-- Browser automation: `playwright`, `puppeteer`, `chromium-bidi`, `@playwright/test`
-- Human mouse: `bezier-js`, `@napi-rs/canvas`, `d3`
-- Ai / vision: `ai`, `@ai-sdk/*`, `@xenova/transformers`, `onnxruntime-web`, `tesseract.js`
-- Sandbox: `@vercel/sandbox`, `vercel`
-- Server: `hono`, `express`, `cors`, `helmet`, `socket.io` (socket realtime)
-- Db: `drizzle-orm`, `mysql2`, `@prisma/client`, `prisma`
-- Storage: `cloudinary`
-- Validation: `zod`, `valibot`, `arktype`
-
-## Next steps
-
-See `action-plan.md`. Implementation starts after user approval.