arcane-os 0.54.1 → 0.56.0

package/docs/architecture.md

@@ -35,11 +35,12 @@ Arcane OS installation, source checkout or private Arcane OS import.
 Arcane OS is an SDK consumer like other applications. Its orchestrator,
 launcher, Shell, Provisioner, system AI application and internal tools use the
 same SDK modules and components rather than maintaining private runtime copies.
-Arcane OS and Core own the privileged host implementations, app/session
-admission and authorization, native transport and lifecycle, launcher and
-Shell orchestration, and system-AI policy specific to the Shell. The SDK may
-publish the capability-neutral Core bridge contract and adapters, but it does
-not embed Core or inherit another application's policy.
+The SDK owns reusable Core protocol, browser client, native runtime, service
+lifecycle and portable payload packaging. Privileged execution stays native;
+the browser client imports no native implementation. Arcane OS retains its
+product host composition, app/session policy, launcher, Shell, Provisioner and
+system-AI orchestration. Applications explicitly supply their service modules;
+the SDK does not discover or inherit another application's services or policy.
 
 Each application owns its branding, prompts, data, tools, business policy,
 model authorities and app-specific orchestration. Apply this decision order:
@@ -47,7 +48,8 @@ model authorities and app-specific orchestration. Apply this decision order:
 | Responsibility | Canonical owner |
 |---|---|
 | Reusable by any portable application | Arcane SDK |
-| Host privilege, launcher, Shell or app/session admission | Arcane OS / Core |
+| Native execution | Native host using SDK runtime and explicit app services |
+| Arcane OS product composition, launcher, Shell and app/session policy | Arcane OS |
 | Behavior unique to one product | That application |
 
 Do not copy a reusable implementation between the SDK, Arcane OS and an app,
@@ -405,18 +407,25 @@ safety remain in effect.
 
 The SDK implements protocol `arcane-native-build-plan/1` and the injected
 provider contract `arcane-native-builder/1`. Pairing is process-local; it never
-registers a mutable global provider or searches for a toolchain. For each
-supported native target, the CLI loads one fixed provider module from the
-explicit `--arcane-root` Arcane OS checkout. Provider code is bound to one
-process generation; if a pull changes loaded provider code, the caller starts a
-fresh worker. One paired toolchain can perform this lifecycle:
+registers a mutable global provider or searches for a toolchain. With no
+`--arcane-root`, the portable CLI target loads the provider from this installed
+SDK package. An explicit root retains the fixed Arcane OS provider selection;
+executable targets still require that override and their platform toolchains.
+Normal Node module resolution owns the loaded module. The pairing reports
+`providerSource` as `sdk-package` or `arcane-checkout`. One paired toolchain can
+perform this lifecycle:
 
 ```text
 doctor -> prepare -> plan -> build -> run
 ```
 
-The portable provider reports honestly that run is unavailable because its
-result is a directory. Windows x64, Linux x64,
+The package-owned portable provider copies the complete selected app and
+dependency payloads and generates a Core entry and synchronous classic facade.
+It accepts explicitly selected service modules through
+`createPortableNativeProvider({services:[{module,options}]})`. Its result is a
+directory, so run reports unavailable. It supplies no executable platform host,
+installer, model assets or OS product services. The explicit Arcane OS
+providers for Windows x64, Linux x64,
 Linux ARM64, and Android ARM64 implement same-process launch and owned
 cancellation when their compatible host/device requirements are present.
 Windows uses a retained per-build broker and host readiness. The
@@ -439,16 +448,15 @@ paths are withheld from the native provider. The provider copies the complete
 selected release rather than accepting an unrelated source path. Verification
 is a separate explicit operation for a selected release artifact.
 
-The current native build contract requires Arcane Core `0.8.12` or newer.
-Compatibility is contractual rather than exact-version pinning: the prepared Core must meet
-the highest minimum declared by the runtime, selected app, and bundled app
-dependencies; keep each app's Arcane protocol generation; and provide every
-declared feature, capability, and method. Missing requirements stop before
-provider build; a newer compatible Core is accepted. Browser-only apps may omit
-`minimumCoreVersion`, and missing permissions or optional security declarations
-normalize to empty records. The provider paths have
-been validated from independent workspaces. They do not copy proprietary source
-into the Arcane checkout.
+The native plan preserves the selected descriptors, dependency releases and
+minimum Core requirement for the provider. It accepts the CLI's nested
+`signing:{mode,profileId}` request and existing flat `signing`/`signingProfileId`
+inputs, emitting the same flat plan request. Payload assembly alone does not
+establish that a composed host supplies an app's required methods or services.
+See the [portable native packaging guide](reference/core-native-packaging.md)
+for the SDK provider's actual output and composition boundary. Browser-only apps
+may omit `minimumCoreVersion`; ordinary browser operation remains independent
+of Core.
 
 See [compatibility.md](compatibility.md) for the complete app and bundled-app
 compatibility rule and the required handling of breaking contract changes.

package/docs/compatibility.md

@@ -23,7 +23,16 @@ When the selected target actually uses Arcane Core, compatibility requires:
 The effective Core floor for a native build is the highest minimum explicitly
 declared by the SDK runtime, the selected app, and its complete bundled-app
 closure. Browser-only targets do not invent a Core floor. The native build plan
-checks every member of that closure before producing output.
+forwards the complete selected descriptors, release records and minimum to the
+provider. Creating a portable payload does not establish host or service
+compatibility; the composed host must actually supply the required contracts.
+
+The portable CLI selects its provider from the installed SDK unless an explicit
+`--arcane-root` chooses the existing checkout provider. Other native target
+selection and the integrated shared-development provider remain unchanged.
+Programmatic native plans accept both nested CLI signing options and the
+existing flat signing/profile fields, retaining the flat plan result. The
+package-owned portable output is a payload, not an executable host or installer.
 
 This permits normal non-breaking Arcane upgrades. For example, an app requiring
 Core `0.8.12` can run on `0.8.13` or `0.9.0` when the required protocol,

package/docs/consumer-updates.md

@@ -0,0 +1,82 @@
+# Consumer updates
+
+Development applications track the published npm `latest` channel. Declare
+`"arcane-os": "latest"` in the application's existing dependency section.
+Preserve an existing package alias where the application needs it; Arcane OS,
+for example, uses `"arcane-sdk": "npm:arcane-os@latest"` to avoid a name collision.
+Pin an application's SDK version only when Roshi explicitly designates it as a
+production build. An exact version recorded in `package-lock.json` records what
+was installed; it does not turn a development application into a production pin.
+
+## Development refresh
+
+Each application's existing owner performs its refresh through the public npm
+package workflow in its canonical `main` checkout. Coordinate the dependency
+and Git mutation window before cleanup, preserve active processes and other
+owners' work, and establish applicable dependency permissions before removing
+the installed tree. Respect explicit project stops, including Lifeline.
+
+1. Keep the SDK declaration at `latest` and preserve `package-lock.json`.
+2. Resolve the exact application path and remove only that application's
+   disposable `node_modules`, before pulling. Do not sweep sibling projects or
+   shared caches.
+3. Run `git pull` and observe the result. Preserve existing changes and stop the
+   affected operation if the pull fails or leaves conflicts.
+4. Run `npm i` through the application's supported install workflow, retaining
+   its applicable lifecycle-script options.
+5. Explicitly run `npm update arcane-os` to refresh only the SDK. For an existing
+   alias, target its dependency key, such as `npm update arcane-sdk`.
+6. Before materializing managed files or building, obtain npm's published
+   `latest` version with a fresh registry lookup, such as
+   `npm view arcane-os@latest version --prefer-online`. Read the actual installed
+   package version and the lockfile's resolved SDK version. Both must match that
+   published version. If the tag advances during the operation, refresh the SDK
+   again and report the actual selected version.
+7. Update managed SDK projections only through the application's supported
+   public package workflow. Commit the intended declaration, retained updated
+   lockfile, managed files, and relevant instructions through its normal owner.
+
+A `latest` declaration and `npm i` alone are insufficient: an existing lockfile
+can preserve an older resolution. Keep and update the lockfile instead of
+deleting it and re-resolving unrelated dependencies. Surface installation and
+compatibility failures; do not claim current adoption from a manifest label.
+
+This dependency-result comparison is part of the requested refresh. It does
+not authorize application tests, unrelated checks or dependency updates,
+recurring polling, broad cleanup, or production administration. A later release
+can advance `latest`; record the exact version selected by each refresh.
+
+## Production builds
+
+On Roshi's explicit production designation, record the selected exact SDK
+version consistently in the dependency declaration, lockfile, managed
+projections, and application instructions. Use the supported locked install
+workflow, normally `npm ci`, to reproduce that selection. A production pin
+records reproducibility, not a permanent ceiling on otherwise authorized
+needed updates. Preserve an explicit update deferral or actual compatibility
+constraint.
+
+## Feature requests and release notices
+
+Inspect the published SDK's public API and documentation before implementing a
+request. If it already supports the requested behavior, tell the requesting
+application owner which API and usage provide it and link directly to the
+relevant documentation. Do not present unpublished source as available support.
+
+After a release's npm version and channel are confirmed, notify only existing
+application owners whose requests it addresses. Notify every requester covered
+by matching, similar, or bundled requests when one shared feature serves them.
+Do not send routine release broadcasts to unrelated consumers.
+
+Each notice includes the exact published version and channel, requested
+functionality delivered, its relevance, release notes or a changelog link,
+direct API and usage documentation references, and required compatibility or
+adoption steps. Keep publication evidence distinct from application behavior.
+Deduplicate by version and recipient and retain send outcomes in the release
+handoff. Report unreachable owners and resume missing deliveries.
+
+After every release and applicable requester notices, update the documentation
+and existing SDK website for all affected public contracts, including releases
+with no requesters. Record those delivery outcomes separately. The SDK owner
+retains this follow-through; application upgrades and tests remain with their
+owners and never gate SDK publication. See [npm publication](publishing.md).

package/docs/platform-targets.md

@@ -16,8 +16,10 @@ toolchain, platform, architecture, format, signing mode, declared dependency
 releases, and destination. Verification is a separate operation only when the
 user explicitly selects it for the release artifact.
 
-Native targets are available by explicitly pairing the SDK with fixed provider
-modules in a compatible Arcane OS checkout. Every native request also requires
+The portable target pairs with the installed SDK provider by default. An explicit
+`--arcane-root` retains fixed-provider selection from an Arcane OS checkout;
+Windows, Linux and Android executable targets still require that override and
+their platform toolchains. Every native request also requires
 the canonical app descriptor to declare the exact target selected on the
 command line. The SDK package does not silently search for a toolchain, infer a
 descriptor target, embed the Arcane machine bundle, or substitute browser
@@ -29,8 +31,8 @@ npx arcane-os@latest new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run import-map
-npm exec -- arcane native-doctor --target portable --arcane-root "../Arcane OS"
-npm exec -- arcane build --target portable --arcane-root "../Arcane OS"
+npm exec -- arcane native-doctor --target portable
+npm exec -- arcane build --target portable
 
 # In an app scaffolded with --target windows-x64:
 npm exec -- arcane build --target windows-x64 --arcane-root "../Arcane OS"
@@ -66,11 +68,16 @@ or `android-arm64`) before running the corresponding command.
 `native-prepare` remains a standalone diagnostic. The normal build recipe omits
 it and lets `build` prepare the selected toolchain state.
 
-The portable output is an app-scoped Arcane Core directory. It is an explicit
-portable builder payload, not an executable, and it has no direct run operation.
-The external workspace defaults to `build/portable/`; integrated Arcane work
-must use the same canonical checkout for `--workspace` and `--arcane-root`, and
-must name an `--output-root` outside that checkout.
+The portable output is an app-scoped payload directory with complete selected
+app and dependency files, a generated Core entry and classic client source.
+It is not an executable and has no direct run operation. Explicit service
+composition uses `createPortableNativeProvider({services:[{module,options}]})`;
+the default adds no OS or application services. See
+[Core native packaging](reference/core-native-packaging.md).
+The external workspace defaults to `build/portable/`. Integrated Arcane work
+must name an `--output-root` outside that checkout. Explicit checkout providers
+still use the same canonical checkout for `--workspace` and `--arcane-root`;
+the default SDK portable provider instead uses its installed package root.
 
 Compatibility uses the highest minimum Core version declared by the SDK runtime,
 selected app, and bundled app dependencies, plus each app's Arcane protocol and
@@ -81,7 +88,7 @@ for the complete compatibility and breaking-change rule.
 | Target | Formats | Development status |
 |---|---|---|
 | `browser` | `directory` | Available |
-| `portable` | `portable` directory | Available with explicit `--arcane-root`; not executable |
+| `portable` | `portable` directory | SDK package provider by default; explicit checkout override retained; not executable |
 | `windows-x64` | `exe` bundle | Available with explicit `--arcane-root`; unsigned local development only |
 | `linux-x64` | `deb` | Available with explicit `--arcane-root`; unsigned local development only |
 | `linux-arm64` | `deb` | Available with explicit `--arcane-root` on a compatible native ARM64 toolchain; unsigned local development only |
@@ -89,7 +96,9 @@ for the complete compatibility and breaking-change rule.
 
 macOS can consume browser applications and portable JavaScript capabilities
 within their declared runtimes. The current target registry has no macOS native
-package adapter; it exposes only the six targets above. A source-development
+package adapter, and the portable CLI request currently selects only Windows
+or Linux. macOS native packaging and Android host adaptation remain incomplete;
+the SDK portable payload does not supply executable hosts. A source-development
 native wrapper is also not an exposed `arcane dev` target. Native `run` uses the
 selected packaged application through its paired provider.
 

package/docs/publishing.md

@@ -11,8 +11,12 @@ the npm `dev` dist-tag, while bare numeric stable versions select
 
 The package version and `publishConfig.tag` must agree exactly: `-dev` uses
 `dev`, and a bare numeric stable version uses `latest`. npm is the canonical
-SDK distribution: application repositories add an exact `arcane-os` project
-dependency and invoke its local CLI with `npm exec -- arcane`. A separate
+SDK distribution: development applications declare `arcane-os` as `latest` and
+invoke its local CLI with `npm exec -- arcane`. An exact application SDK pin
+begins only when Roshi designates that application as a production build.
+Keep the lockfile and explicitly refresh and compare its resolution and the
+installed SDK with npm's published version before materializing or building;
+see [Consumer updates](consumer-updates.md). A separate
 global installer, standalone SDK executable, NuGet package, Homebrew formula,
 or OS package is not part of this release surface.
 
@@ -30,8 +34,8 @@ agreement, and required license notices. One unprivileged producer packs one
 artifact with a recorded run id, artifact id, version, and source commit. It
 does not impose byte counts, hashes, digests, provenance receipts, or unrelated
 test suites as ordinary development gates. Broader integration, regression,
-platform, browser, presentation, and documentation work remains separately
-user selected.
+and platform work remains separately user selected. Documentation and website
+updates are required post-publication follow-through as described below.
 
 `publish-dev.yml` can run only when manually dispatched from `main` in
 `TheWizardNexus/arcane-os-sdk`. Dispatch supplies the exact successful Check
@@ -59,14 +63,15 @@ The unscoped package installs both `arcane` and `arcane-os`. The short command
 is the documented default; `arcane-os` is the collision-safe fallback. npm
 package names are unique, but executable names are not globally reserved.
 
-When `npm view arcane-os@dev version` reports the package unavailable, run
-`npm run pack:local` in this SDK checkout for local development, scaffold with
-`node ./bin/arcane.mjs new ...`, and install the resulting `.tgz` into the app
+External applications consume published npm releases. An unavailable release
+does not authorize them to use an unpublished SDK checkout or tarball. Only
+tasks explicitly collaborating on an SDK update inside this project may use
+the local `npm run pack:local` workflow and its resulting `.tgz`. That local
+workflow can scaffold with `node ./bin/arcane.mjs new ...` and install the tarball
 with `npm install --save-dev --save-exact <path>`. Keep the tarball at the path
-recorded by `package-lock.json`; subsequent `npm ci` uses that declared package.
-Arcane reads the installed package's name and version against the root
-dependency declaration. A local directory `file:` install is intentionally unsupported because
-it may be linked.
+recorded by `package-lock.json` for subsequent `npm ci`. Arcane reads the installed
+package's name and version against the root dependency declaration. A local
+directory `file:` install is unsupported because it may be linked.
 
 The npm package already has its trusted-publishing relationship. Each later
 release therefore follows the same direct selected-artifact path: push the
@@ -77,9 +82,11 @@ dist-tag after publication. Never rebuild or repack the artifact under
 publication authority, and never substitute a different source revision.
 
 Generated app CI uses `npm ci --ignore-scripts`, so its lock must exist and its
-dependency source must be reachable by the runner. A sibling local tarball is a
-workstation workflow, not a portable GitHub dependency source; switch to the
-exact registry release (or deliberately vendor the tarball) before remote CI.
+dependency source must be reachable by the runner. External application CI uses
+the published registry package recorded in the committed lockfile. A locked
+install reproduces that selected version; it does not establish that the SDK is
+currently npm's `latest`. Complete the development refresh before preparing and
+committing managed application files and the updated lockfile for CI.
 
 ## Reusable application release workflow
 
@@ -111,8 +118,23 @@ GitHub release, and no release creates a Git branch for an npm dist-tag.
 
 ## Documentation publication
 
-Documentation publication occurs only when the user explicitly selects it. The
-Pages job checks out that selected `main` revision without persistent
+After every successful npm release and its applicable requester notices, the
+SDK owner updates documentation and the existing SDK website for all added,
+removed, or modified features, APIs, members, methods, and affected public
+contracts. Include the relevant signatures, inputs, outputs, defaults,
+lifecycle, errors, platform availability, and usage examples. This standing
+duty also applies when a release has no requesting applications. Record the
+actual documentation and website delivery outcomes in the release handoff and
+report any unfinished work. See [Consumer updates](consumer-updates.md) for
+request intake and notice requirements.
+
+Documentation and website content outside the selected npm payload does not
+block npm publication. Prepare and deliver those updates through the existing
+documentation/site workflow after publication; do not wait for consumer
+adoption or application tests. This duty does not authorize ChatGPT Sites or
+production-server administration.
+
+The Pages job checks out the selected `main` revision without persistent
 credentials and uploads only the static `site/` tree. It does not automatically
 run the SDK test suite, checks, generators, or repository build code.
 
@@ -128,5 +150,6 @@ One producer creates the tarball. Publication names that producer's exact Check
 run, artifact, and version and does not rebuild from a later checkout. The
 release workflow checks only the publication contract and required legal
 inventory for that selected output.
-Platform matrices, full product regressions, Pages, and broader presentation
-work remain separate user-selected operations.
+Platform matrices and full product regressions remain separate user-selected
+operations. Documentation and the existing website are required post-release
+follow-through, with their outcomes recorded separately from npm publication.

package/docs/reference/README.md

@@ -17,9 +17,14 @@ high-level page links to the relevant deep section instead of repeating it.
 Install the SDK in your application:
 
 ```sh
-npm install --save-exact arcane-os@latest
+npm pkg set dependencies.arcane-os=latest
+npm install
 ```
 
+The development declaration tracks the current `latest` channel. The lockfile
+and installed package record the exact version actually selected for the
+workspace.
+
 For your first AI call, follow the [TWiN Cloud quick start](ai/twin-cloud.md).
 For local models, native browser voices or cloud speech, follow the [browser speech guide](ai/browser-speech.md)
 and the complete [browser AI demo](https://github.com/TheWizardNexus/arcane-os-sdk/tree/main/examples/wasm-ai-demo).
@@ -38,14 +43,19 @@ alone does not make bare module names resolve in a browser.
 | Use the `arcane` command | [CLI reference](cli.md) |
 | Install an app and cache selected resources offline | [Progressive web applications](pwa.md) |
 | Generate named browser imports or inspect the selected physical runtime | [`arcane import-map`](cli.md#arcane-import-map) and [browser runtime delivery](protocols.md#browser-runtime-delivery) |
+| Connect an application through the shared WebSocket transport | [Shared WebSocket clients](websocket-client.md) |
 | Choose browser, native, cloud, or cross-host behavior | [Availability and normalization](availability-and-normalization.md) |
 | Import a shipped renderer module | [Runtime module catalog](runtime-modules.md) |
 | Use a shared entity | [Runtime entity modules](runtime-entities.md) and [exact export contracts](core/arcane-entities.md) |
 | Load a reusable HTML component | [Runtime component catalog](runtime-components.md) |
 | Submit complete speech parts immediately and play them in order | [`SpeechPlayback`](runtime-modules.md#speechplaybackjs) and the [basic browser example](ai/browser-speech.md#play-a-complete-array-with-speechplayback) |
 | Call `globalThis.Arcane` | [Arcane Core API](core/arcane-api.md) |
+| Connect a browser to one Core transport | [Core browser client](core-client.md) |
+| Compose native Core dispatch, service lifecycle, and stdio hosting | [Native Core runtime](core-runtime.md) |
+| Build an installed-SDK portable Core payload | [Portable Core packaging](core-native-packaging.md) |
 | Subscribe to native events | [Arcane event reference](core/arcane-events.md) |
 | Use provider-neutral AI lifecycle, chat, speech, persistence, or document context | [Normalized AI](#normalized-ai) |
+| Choose a normalized typed browser decision surface | [Browser typed decisions](ai/browser-decisions.md) |
 | Run a caller-selected local LLM in the browser | [Browser-WASM local AI](ai/browser-wasm.md) |
 | Run caller-selected Whisper/Kokoro, native browser recognition/voices or cloud TTS | [Browser speech providers](ai/browser-speech.md) |
 | Send TWiN chat, System One state/questions or image requests | [TWiN Cloud guide](ai/twin-cloud.md) |
@@ -67,12 +77,14 @@ This repository contains explicitly versioned surfaces with different owners:
 | Browser SDK runtime | Selected SDK, `browser-runtime/` | Events, logging, Wllama, local/native/cloud speech, TWiN requests and PWA mechanisms. `listSdkBrowserRuntimeFiles()`, `readSdkBrowserRuntimeFile()`, and `loadSdkBrowserRuntimeRelease()` derive its current inventory directly from the selected directory. |
 | Core reference snapshot | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, protocol `arcane/1` | The application-facing Core contract imported into `docs/reference/core/`, with SDK-local links and package-boundary notes added explicitly. |
 
-The SDK runtime source and Core reference have different owners. A browser
-module comes from the selected SDK runtime tree. A native build selects one
-explicit Arcane OS checkout and Core, then checks the declared protocol,
-version, features, capabilities, methods, and provider contract needed by that
-build. A matching protocol name or higher version alone does not promise
-functional compatibility.
+Browser modules and reusable Core client/runtime/lifecycle source belong to the
+SDK. The portable provider uses this installed package by default and assembles
+an app payload with explicitly selected services; it supplies no executable
+platform host. Explicit Arcane OS provider overrides and integrated shared
+checks remain available. Arcane OS retains its product composition and policy.
+The historical Core reference snapshot describes a separate host contract;
+matching a protocol name or assembling a payload alone does not establish that
+a composed host supplies every required method or service.
 
 See the [Core reference source notes](core/README.md) for the imported inventory
 and the distinction between a documentation snapshot and the selected runtime.

package/docs/reference/availability-and-normalization.md

@@ -58,9 +58,12 @@ false when a probe throws; SDK branching continues through its owning error path
 policy, package-owned model policy, platform support, and dependency readiness
 are independent checks.
 
-The current native host/target matrix covers Microsoft NT, Linux, and Android
-where listed. It exposes no macOS target or Core host contract in this SDK
-version; WebKitGTK availability must not be generalized to macOS.
+The current executable host/target matrix covers Microsoft NT, Linux, and
+Android where listed. This SDK exposes no macOS executable target, native
+bridge, artifact, or run contract; WebKitGTK availability must not be
+generalized to macOS. The reusable Node Core runtime, framed stdio transport,
+host composition, and portable payload can be used by a separately composed
+macOS host, but they do not supply that native platform host or bridge.
 
 ## Capability-first matrix
 
@@ -68,7 +71,9 @@ version; WebKitGTK availability must not be generalized to macOS.
 | --- | --- | --- | --- |
 | Scaffold, inspect, test, package, bundle, build, verify, or run an app | `arcane` CLI or `arcane-os` package functions | **Node**; native targets invoke one explicit provider | CLI events and SDK errors/results are normalized by versioned SDK contracts. Tests and checks run only when explicitly selected; verification is separate and selected-output-specific. |
 | Publish application events or review a complete event history | `arcane-os/event-manager` | **Node** and **Browser**; optional DOM capture needs a browser DOM or compatible host | Live listeners receive original arguments. Ordinary `secure:false` recording preserves complete URLs, public details, and captured stack text in deeply frozen `arcane-event-stack/1` snapshots while credential-named fields remain redacted. The stack format is local diagnostic data, not a host transport. |
+| Share one native WebSocket by exact URI and ordered protocols | `arcane-os/websocket-client` | **Node** and **Browser**, using the host's native `WebSocket` | The selected upstream `ws-share` instance owns the connection pool and global observation. Native socket messages and events remain unchanged; there is no reconnect, heartbeat, application envelope, storage, or fallback. |
 | Build browser UI and app-local behavior | `/arcane/modules/*.js`, shared entities, and components | **Browser**; many modules also run inside every native renderer | Pure modules own their result contracts. Modules that call `Arcane` inherit the bridge boundary described below. |
+| Score caller-supplied typed options with Laya or Julia | `arcane-os/ai/browser-decisions` | **Browser** only; caller-selected upstream runtime/model and backend | Typed decisions retain complete rows and return typed values, scores, probabilities, and diagnostics in caller order. This surface is separate from chat and speech and does not silently change model, precision, backend, or family. |
 | Select and observe independent LLM/STT/TTS roles | `/arcane/modules/AIProviderRuntime.js` and `AIRuntimeState.js` | **Cross-host** controller/state; registered providers retain their own host requirements | Required/projected provider members, route/configuration records, and status fields; per-role lifecycle, cancellation, stream cleanup, sticky state, and startup barriers are normalized. `localOnly` creates no fallback. |
 | Run a caller-selected local LLM entirely in a browser renderer | `arcane-os/ai/browser-wasm` through `createArcaneAI()` | **Browser** only; secure context, WebAssembly, and OPFS/DBOPFS; full WebGPU offload by default or explicit CPU with `gpuLayers:0` | The public AI API module normalizes multi-model lifecycle, status, complete all-choice streaming, cancellation, exact ordered structural tool-call visibility, and session persistence. Model sources are canonical ordered file descriptors; licenses and model choice remain application policy. |
 | Run caller-selected Whisper or Kokoro in a browser renderer | `arcane-os/ai/browser-speech` registered with `AIProviderRuntime` | **Browser** only; DBOPFS, Web Locks, Workers, Fetch/object URLs, and a caller-supplied self-contained runtime/model closure are required | Independent provider/2 lifecycle and status, with `auto`, `webnn-npu`, `webgpu`, or `wasm` execution. Whisper owns one Worker/session; Kokoro defaults to four and accepts one through four. Complete model/runtime selection, offline behavior, cancellation, Worker teardown, and request/result shapes are normalized. No runtime/model content or cloud fallback is supplied. |
@@ -81,6 +86,9 @@ version; WebKitGTK availability must not be generalized to macOS.
 | Print rendered editor content or file previews | `/arcane/modules/PrintView.js`, editor `print()`, and file/history `printPreview()` | **Browser / native WebView** with DOM and browser printing | Complete current rendered content, fonts, and resolved media are captured for print. Explicit requests await view preparation; native Print captures synchronously. Shared `print.css` supplies a light paper palette and one-inch margins; snapshots stay owned through `afterprint`. |
 | Search an app-owned document corpus for explicit chat context | `/arcane/modules/DBOPFSDocumentLibrary.js` | **Browser** or compatible injected DBOPFS adapter | Generation/manifest completion, complete lexical search, partial read failures, and untrusted context labels are normalized. Construction does not search; an explicitly wired context builder performs retrieval for each prepared chat send. |
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
+| Connect browser code to an existing Core transport | `arcane-os/core/client` and `arcane-os/core/contracts` | **Browser / native WebView** with an admitted transport; explicit development HTTP remains opt-in | The reusable client owns `arcane/1` correlation, readiness, cancellation, events, facades, and complete native error fidelity. It supplies no service, policy, or host process. |
+| Compose native Core services and framed stdio hosting | `arcane-os/core/runtime`, `arcane-os/core/stdio`, and `arcane-os/core/host` | **Node** on Windows, Linux, or macOS; the composing native host supplies its process and bridge | The SDK owns reusable dispatch, per-service lifecycle, request/service work ownership, cooperative cancellation, drain, and stdio framing. Product identity, policy, privileges, models, storage, and services remain host-owned. |
+| Assemble a portable Core payload from the installed SDK | `arcane-os/native/portable-provider` | **Node**; portable platform selection is currently Windows or Linux, while separately composed hosts may use the payload | The provider copies the selected app, dependencies, installed SDK runtime, Core client/runtime, and explicit service composition into a non-executable directory. It uses no `arcaneRoot` by default and does not prove host behavior or supply a platform bridge. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use TWiN Cloud from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level chat behavior is normalized by the module. The TWiN access key authenticates remote LLM chat; raw provider diagnostics remain provider-specific. No automatic cloud fallback is inferred from local failure. |
 | Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Rejected Fetch and HTTP 529 share three retries after 3000 ms; HTTP 429 overload retains unlimited three-second retries. Optional `onRetry` reports waiting/requesting phases without blocking recovery. Shared structured-output mapping and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |
@@ -229,8 +237,10 @@ synthesis, and TWiN Cloud/FAL synthesis can be registered through
 `ai.configureSpeechProvider(role,provider,{modelId})`; configuration owns only
 the selected role and performs no network request. Saved selections remain
 application-owned, including selections waiting for provider registration.
-The SDK publishes no privileged Core implementation, credential, model, or
-speech-runtime authority. Capability-only built-in adapters report their
+The SDK supplies reusable Core client/runtime/service-lifecycle primitives and
+portable payload composition; privileged execution stays in a native host.
+It supplies no application credential, selected model or product speech-service
+authority. Capability-only built-in adapters report their
 existing routes without probing, downloading, or changing providers. The sticky
 [`AIRuntimeState`](runtime-modules.md#airuntimestatejs) surface keeps
 application UI independent of transport. A selected route remains explicit:

package/docs/reference/behavioral-testing.md

@@ -43,7 +43,7 @@ development evidence; it is not native artifact or release acceptance.
 | Browser-WASM local AI | The exported namespace, canonical ordered `{id, files:[{name?,url},...]}` descriptor, nonempty provider `sources` catalog, default `secure:false`, dormant `secure:true` intent, public AI API module lifecycle, lazy/manual policy, successful Wllama-load requirement, abort normalization, complete output and reasoning, all-choice validation, required structural-call `arguments.message`, exact call identity, and matching tool-result sequencing are represented in deterministic fixture sources. | A real Chrome exercise may load the selected Wllama runtime and model only after explicit user action. It is not an ordinary publication gate or an implicit model download. |
 | Browser speech | Caller-owned Whisper/Kokoro selection, independent STT/TTS routes, ordinary direct upstream runtime/model use, dormant `secure:true` intent, DBOPFS cache, materialized known-route/native-fallback behavior, NPU-to-GPU-to-CPU automatic selection for both roles, fresh Workers after a failed device load, explicit-device failure without fallback, bounded Kokoro Worker/session pools, out-of-order synthesis settlement with FIFO admission, request-targeted TTS cancellation, destructive lifecycle cleanup, Blob/File STT conversion, WAV TTS conversion, complete text/audio, and no cloud fallback are represented with synthetic artifacts and adapters. | A real runtime/model/voice download, WebNN or WebGPU model load, physical accelerator behavior, and actual transcription or synthesis use the application's selected upstream packages/providers, browser media support, and explicit user action. A selected backend is not proof that every operation ran on that physical accelerator; WebNN may execute unsupported operations through WASM. |
 | Persistent chat and document context | Atomic in-memory/history commit, explicit per-turn persistence, streamed/non-stream fallback, session-owned callback fields, complete data callbacks, per-turn request options, exact per-choice streamed/terminal call correlation before publication, terminal-only call acceptance, ordered parallel-call sequencing, atomic all-ID nonblank executed/declined/cancelled/not-executed result batches, readable unmodified malformed pre-existing rows, complete UI transcript metadata, generic visible failure outcomes with complete console diagnostics, BFCache-preserving component lifecycle, complete bootstrap/search/context, caller-source evaluation, cancellation, and partial-read handling are represented with app-scoped adapters. | Live Core/provider inference and durable browser storage remain separate authorities; tests never treat a fake chat function or in-memory adapter as host/storage proof. |
-| Core bridge docs | Canonical namespace/method/event/entity inventories match their one-per-member guides and required sections. | Live Core conformance belongs in Arcane OS because Core implementation is not shipped as SDK source. |
+| Core bridge docs | Canonical namespace/method/event/entity inventories match their one-per-member guides and required sections. | SDK Core primitives and portable assembly have their own source fixtures. Live composed-host conformance and actual platform behavior remain separate evidence. |
 | Arcane Ollama wrapper | Missing-host error, method forwarding, text/readiness normalization, unload request, and stream-option forwarding run against a deterministic fake `Arcane.ollama`. | Real managed-service, model download/create, GPU/resource admission, and service restart require an admitted Arcane host. |
 | Native providers | Plan/provider protocol, explicit target, complete artifact reading, and unavailable-path honesty are tested with fixtures. | Windows, Linux, or Android artifact verification and launch must run on that actual platform/architecture and only when explicitly selected. |
 
@@ -122,8 +122,9 @@ not prove already-started host, provider, worker, or queue work stopped.
 The SDK owns the singleton authority, its per-realm source adapters, package and
 managed-browser projections, focused event/source/DOM contracts, runtime
 compatibility views, package, CLI, synchronized renderer, documentation, and
-injected provider-boundary behavior. Arcane OS owns live Core dispatch, native host
-bridges, capability policy, host service adapters, and real ArcaneOllama
-integration. A change that crosses both repositories needs focused tests at both
-owners; copying a Core test into this package would not make the SDK the Core
-implementation owner.
+injected provider-boundary behavior, reusable Core client/runtime/service
+lifecycle and package-owned portable assembly. Arcane OS owns its product host
+composition, Shell, Provisioner, model choices and application policy. Source
+fixtures do not establish execution of the composed host, platform executable,
+installer or model service. Verification stays at the selected owning output
+and follows the active testing authority.

package/docs/reference/cli.md

@@ -692,11 +692,13 @@ npm exec -- arcane verify-bundle dist/hello-world-1.0.0.arcane-app.tar.gz
 
 ### Overview
 
-Loads one fixed native provider from one explicit Arcane OS checkout and
-diagnoses the selected target/host prerequisites without building an app.
+Loads the SDK package provider for portable by default, or the fixed provider
+from an explicitly selected Arcane OS checkout. It diagnoses the selected
+provider prerequisites without building an app. Executable targets still
+require `--arcane-root` and their platform toolchains.
 
 ```text
-arcane native-doctor --target <native-target> --arcane-root <directory>
+arcane native-doctor --target <native-target> [--arcane-root <directory>]
 ```
 
 ### Availability
@@ -722,7 +724,7 @@ It is not a prerequisite command to repeat immediately before `build`; `build`
 prepares its own selected toolchain state.
 
 ```text
-arcane native-prepare --target <native-target> --arcane-root <directory>
+arcane native-prepare --target <native-target> [--arcane-root <directory>]
 ```
 
 ### Example
@@ -749,6 +751,12 @@ The command selects one workspace, app, target, architecture, format, signing
 profile, and output root. Current providers emit a portable directory,
 Windows x64 EXE bundle, Linux x64/ARM64 DEB, or development-signed Android APK.
 The output remains target-specific inside the common plan contract.
+Portable uses the SDK package without an OS checkout, copies complete selected
+app/dependency payloads and generates the Core entry/classic client source.
+It adds no executable platform host or automatically discovered app services.
+An explicit `--arcane-root` continues to select the checkout provider.
+Integrated builds retain an output root outside the OS checkout; only an
+explicit checkout provider must share the workspace root.
 The app's `outputDirectory` selects its packaged browser-content input;
 native `--output-root` independently selects native build output.
 `--dry-run` is implemented for the browser build path. Native builds reject it