arcane-os 0.55.0 → 0.56.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.56.0
+
+- Add explicit `package.nativeResources` selection for native-only application
+  files and directories. Browser selection remains unchanged; non-browser
+  packaging keeps additional resources outside browser transformations and
+  stages them in a separate target output. Applications select their complete
+  required source closure, and target adapters receive the effective target
+  and browser-PWA selection.
+- Add `getInstalledCoreClient()` to read the exact live SDK-installed client
+  without connecting or changing globals. Terminal `failTransport(error)` and
+  the owned native failure callback preserve complete errors, settle pending
+  requests, and release the failed installation's callbacks and subscriptions.
+- Add opt-in `replayRuntimeState` for Core clients and classic injection. The
+  runtime replays its actual readiness and current service state for newly
+  connected documents without restarting services or delaying page startup.
+
+- Preserve complete UTF-8 process output when a character spans stdout or stderr
+  chunks. Independent readable-stream decoders feed the same text to captured
+  results and existing event delivery; ordering, backpressure, cancellation,
+  graceful drain, nonzero error details and line-event behavior remain unchanged.
+- Include committed Windows and Linux Core process-transport source and the
+  generic Windows SEA launcher source as native-host groundwork. These sources
+  do not activate a platform host or deliver a public native executable; app
+  host composition and the remaining native integration stay independently owned.
+- Clarify development `latest` tracking, production-designated pins, matching
+  requester notices, and required documentation/site release follow-through.
+- No new dependency, application service, automatic runtime installation,
+  application default change or saved-data migration is introduced.
+
 ## 0.55.0
 
 - Add public Core client, protocol contracts and classic-script source generation

package/README.md

@@ -20,9 +20,11 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.55.0` SDK contract. Applications pin one exact npm
-version and lockfile; registry state is deliberately not baked into application
-artifacts.
+This checkout defines the `0.56.0` SDK contract. Development applications declare
+`arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
+designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
+to refresh and compare the installed SDK and lockfile with the published channel;
+registry state is deliberately not baked into application artifacts.
 
 Standalone browser apps use their repository root and installed npm package directly, without a
 generated workspace `arcane/` directory or `arcane.lock.json`. Select the

package/browser-runtime/core/client.mjs

@@ -2,6 +2,7 @@ import {arcaneEvents} from '../event-manager.mjs';
 import {CORE_PROTOCOL,CORE_READY_EVENTS,CoreError,serializeCoreError} from './contracts.mjs';
 
 const CORE_CLIENT_KEY=Symbol.for('arcane-os.core.client');
+const CORE_CLIENT_INSTALLATION=Symbol.for('arcane-os.core.client.installation');
 const CORE_EVENT='core.rpc.event';
 const LONG_OPERATION_TIMEOUT=50*60*1000;
 
@@ -12,6 +13,7 @@ export function createCoreClient({
     eventOwner=arcaneEvents,
     eventOwnerReady,
     autoConnect=true,
+    replayRuntimeState=false,
     onError=error=>global.console?.error('Arcane Core client failed.',error)
 }={}){
     const pending=new Map();
@@ -25,8 +27,14 @@ export function createCoreClient({
     let transport=null;
     let closed=false;
     let eventOwnerFailure=null;
+    let transportFailure=null;
+    let transportFailureReported=false;
 
     function report(error){
+        if(error===transportFailure){
+            if(transportFailureReported)return;
+            transportFailureReported=true;
+        }
         try{onError(error instanceof CoreError?error:new CoreError(error));}
         catch(reportError){global.console?.error('Arcane Core error listener failed.',reportError,error);}
     }
@@ -260,7 +268,7 @@ export function createCoreClient({
         throw new CoreError({code:'ARCANE_TRANSPORT_UNAVAILABLE',message:'This interface is not connected to an Arcane native host.'});
     }
     function connect(){
-        if(closed)throw new CoreError({code:'ARCANE_CLIENT_CLOSED',message:'The Core client is closed.'});
+        if(closed)throw transportFailure??new CoreError({code:'ARCANE_CLIENT_CLOSED',message:'The Core client is closed.'});
         if(transport)return transport;
         const cleanupStart=cleanups.length;
         try{
@@ -271,7 +279,11 @@ export function createCoreClient({
             transport=selected;
             if(typeof transport.subscribe==='function'){
                 const unsubscribe=transport.subscribe(receive);
-                if(typeof unsubscribe==='function')cleanups.push(unsubscribe);
+                if(typeof unsubscribe==='function'){
+                    if(closed){
+                        try{unsubscribe();}catch(error){report(error);}
+                    }else cleanups.push(unsubscribe);
+                }
             }
         }catch(error){
             transport=null;
@@ -280,7 +292,11 @@ export function createCoreClient({
             }
             throw error;
         }
+        if(closed)throw transportFailure??new CoreError({code:'ARCANE_CLIENT_CLOSED',message:'The Core client is closed.'});
         complete('transport.ready',{protocol:CORE_PROTOCOL,transport:transport.name});
+        if(replayRuntimeState&&!closed)sendControl({protocol:CORE_PROTOCOL,type:'control',control:'runtime.replay'});
+        // A native callback may close the client synchronously during replay.
+        if(closed)throw transportFailure??new CoreError({code:'ARCANE_CLIENT_CLOSED',message:'The Core client is closed.'});
         return transport;
     }
     function runtimeSnapshot(){
@@ -312,6 +328,7 @@ export function createCoreClient({
         return true;
     }
     function invoke(method,parameters={},options={}){
+        if(transportFailure)return Promise.reject(transportFailure);
         if(eventOwnerFailure)return Promise.reject(eventOwnerFailure);
         let selected;
         try{selected=connect();}catch(error){return Promise.reject(error);}
@@ -343,23 +360,37 @@ export function createCoreClient({
         }catch(error){sendFailed(error);}
         return promise;
     }
-    function close(){
-        if(closed)return false;
-        closed=true;
-        cancelAll();
+    function disposeTransport(error){
         for(const record of acknowledgements.values()){
             clearTimeout(record.timer);
-            record.reject(new CoreError({code:'ARCANE_CLIENT_CLOSED',message:'The Core client is closed.'}));
+            record.reject(error);
         }
         acknowledgements.clear();
         for(const cleanup of cleanups.splice(0)){
             try{cleanup();}catch(error){report(error);}
         }
-        source?.dispose();
+        try{source?.dispose();}catch(disposeError){report(disposeError);}
+        source=null;
+        transport=null;
         // Registration closures and already-delivered payloads belong to this
         // client lifetime and are released when the owner explicitly closes it.
         eventActions.length=0;
         completedEvents.clear();
+    }
+    function failTransport(error){
+        if(closed)return false;
+        transportFailure=error instanceof CoreError?error:new CoreError(error);
+        closed=true;
+        for(const id of pending.keys())settle(id,transportFailure);
+        disposeTransport(transportFailure);
+        report(transportFailure);
+        return true;
+    }
+    function close(){
+        if(closed)return false;
+        closed=true;
+        cancelAll();
+        disposeTransport(new CoreError({code:'ARCANE_CLIENT_CLOSED',message:'The Core client is closed.'}));
         return true;
     }
     if(typeof global.addEventListener==='function'){
@@ -369,7 +400,7 @@ export function createCoreClient({
     if(autoConnect){
         try{connect();}catch(error){if(error.code!=='ARCANE_TRANSPORT_UNAVAILABLE')report(error);}
     }
-    return {protocol:CORE_PROTOCOL,Error:CoreError,invoke,receive,connect,close,cancelAll,events,eventsReady,runtime:{current:runtimeSnapshot},uuid};
+    return {protocol:CORE_PROTOCOL,Error:CoreError,invoke,receive,connect,close,failTransport,cancelAll,events,eventsReady,runtime:{current:runtimeSnapshot},uuid};
 }
 
 /** Existing namespace call shapes; method implementations remain host-owned. */
@@ -461,28 +492,58 @@ export function createCoreFacade(client){
     };
 }
 
+/** Reads an installed SDK client without creating a transport or changing globals. */
+export function getInstalledCoreClient(global=globalThis){
+    const client=global?.[CORE_CLIENT_KEY];
+    const installation=client?.[CORE_CLIENT_INSTALLATION];
+    return installation?.global===global&&installation.active?client:null;
+}
+
 /** Installs the same synchronous facade used by classic native-host scripts. */
 export function installCoreClient(global=globalThis,options={}){
     if(global[CORE_CLIENT_KEY])return global[CORE_CLIENT_KEY];
     const client=createCoreClient({...options,global,autoConnect:false});
     const facade=createCoreFacade(client);
+    const installation={global,active:true};
+    client[CORE_CLIENT_INSTALLATION]=installation;
+    const previousFacade=global.Arcane;
     global.Arcane=facade;
     global[CORE_CLIENT_KEY]=client;
     const previous=global.__arcaneReceive;
     global.__arcaneReceive=client.receive;
+    const previousFailure=global.__arcaneTransportFailed;
+    function nativeTransportFailed(error){return client.failTransport(error);}
+    global.__arcaneTransportFailed=nativeTransportFailed;
     const close=client.close;
-    client.close=function closeInstalledClient(){
-        const changed=close();
+    const failTransport=client.failTransport;
+    let installedTransportFailure=null;
+    function releaseInstalledClient(){
+        installation.active=false;
         if(global[CORE_CLIENT_KEY]===client)delete global[CORE_CLIENT_KEY];
-        if(global.Arcane===facade)delete global.Arcane;
+        if(global.Arcane===facade){
+            if(previousFacade===undefined)delete global.Arcane;
+            else global.Arcane=previousFacade;
+        }
         if(global.__arcaneReceive===client.receive){
             if(previous===undefined)delete global.__arcaneReceive;
             else global.__arcaneReceive=previous;
         }
-        return changed;
+        if(global.__arcaneTransportFailed===nativeTransportFailed){
+            if(previousFailure===undefined)delete global.__arcaneTransportFailed;
+            else global.__arcaneTransportFailed=previousFailure;
+        }
+    }
+    client.close=function closeInstalledClient(){
+        installation.active=false;
+        try{return close();}finally{releaseInstalledClient();}
+    };
+    client.failTransport=function failInstalledTransport(error){
+        if(installation.active)installedTransportFailure=error instanceof CoreError?error:new CoreError(error);
+        releaseInstalledClient();
+        return failTransport(installedTransportFailure??error);
     };
     try{client.connect();}catch(error){
-        if(error.code!=='ARCANE_TRANSPORT_UNAVAILABLE'){
+        if(error!==installedTransportFailure&&error.code!=='ARCANE_TRANSPORT_UNAVAILABLE'){
             if(options.onError)options.onError(error);
             else global.console?.error('Arcane Core transport initialization failed.',error);
         }

package/browser-runtime/core/contracts.mjs

@@ -7,7 +7,8 @@ export const CORE_FRAME_CONTRACTS={
     response:{type:'response',fields:['protocol','type','id','ok'],success:['result'],failure:['error'],optional:['time']},
     event:{type:'event',fields:['protocol','type','event','data'],optional:['time']},
     cancel:{type:'control',control:'request.cancel',fields:['protocol','type','control','requestId']},
-    cancelAll:{type:'control',control:'requests.cancelAll',fields:['protocol','type','control']}
+    cancelAll:{type:'control',control:'requests.cancelAll',fields:['protocol','type','control']},
+    replay:{type:'control',control:'runtime.replay',fields:['protocol','type','control']}
 };
 
 /** These names describe existing methods; installed services determine availability. */

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/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) |

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. |

package/docs/reference/core-client.md

@@ -1,7 +1,8 @@
 # Core browser client
 
 `arcane-os/core/client` is the browser-safe `arcane/1` RPC owner. It exports
-`createCoreClient`, `createCoreFacade` and `installCoreClient`.
+`createCoreClient`, `createCoreFacade`, `installCoreClient` and
+`getInstalledCoreClient`.
 `arcane-os/core/contracts` exports `CORE_PROTOCOL`, `CORE_READY_EVENTS`,
 `CORE_FRAME_CONTRACTS`, `CORE_METHOD_CONTRACTS`, `CoreError` and
 `serializeCoreError`. Contracts describe transport and existing method shapes;
@@ -25,6 +26,23 @@ remain available through this facade; their implementations and availability
 belong to the selected host. No repository, app list, model selection or service
 implementation is installed by importing this client.
 
+An application using a host-installed client can read it without installing or
+replacing anything:
+
+```js
+import {getInstalledCoreClient} from 'arcane-os/core/client';
+
+const client=getInstalledCoreClient();
+// null means this global has no live SDK-installed client.
+```
+
+`getInstalledCoreClient(global=globalThis)` returns the exact live SDK-installed
+client, including one installed by classic document-created injection. It does
+not connect, install a client or replace an existing `Arcane` object. Applications
+need not inspect private installation fields. It returns `null` after that
+installation closes or fails. A
+foreign application's `Arcane` object is not evidence of an SDK installation.
+
 The native adapters select WebView2, WebKitGTK or Android WebView. Ordinary
 browsers remain `standalone`; they do not probe a local server. Development
 HTTP is selected only by the existing explicit `__ARCANE_DEV_HTTP__` flag.
@@ -41,6 +59,14 @@ without callable `send(frame)` remains disconnected and reports
 `ARCANE_TRANSPORT_INVALID`; it does not announce `transport.ready`.
 `autoConnect:false` defers connection until `connect()` or the first invocation.
 
+`replayRuntimeState:true` sends one `runtime.replay` control after the transport's
+receive listener and `transport.ready` are established. The default is `false`,
+preserving existing hosts. The send is observed without delaying page startup;
+delivery errors reach `onError`. A host supporting this control supplies its
+current dispatcher and service state for a newly connected document, without
+restarting services. Repeated `connect()` calls on the same connection do not
+send another replay. See [runtime replay](core-runtime.md#state-and-frames).
+
 `client.invoke(method, parameters, {signal, timeoutMs})` returns the actual
 response result or rejects with `CoreError`. Parameters, result fields and
 event data retain their complete supplied content. JSON encoding belongs only
@@ -75,6 +101,20 @@ native callbacks, timers and pending renderer requests; it does not kill Core.
 Call `stop()` to remove an individual subscription and `client.close()` when
 the client owner ends its lifetime.
 
+For an actual terminal child-process or transport failure, the host calls
+`client.failTransport(error)`. Installed clients also own the native callback
+`globalThis.__arcaneTransportFailed(error)`. This boundary rejects pending RPCs
+and WebKit acknowledgements with the complete actual `CoreError`, reports that
+failure once, releases callbacks/subscriptions/timers and rejects future
+invocations with the same failure. It sends no cancellation frames to a failed
+transport and does not invent response identifiers or results. A normal close
+still uses cancellation rather than reporting a transport failure.
+
+Closing or failing an installation restores its previous `Arcane` object and
+native callbacks only when those globals still belong to that installation.
+Another owner's later replacements remain unchanged. The read-only accessor
+returns `null` before the installed failure is reported to `onError`.
+
 Errors retain complete native fields, including diagnostics and stack/cause
 information. WebView2 and Android bridge failures retain native error codes,
 messages and diagnostic fields; the request method and transport are added
@@ -90,7 +130,8 @@ transport/event-owner failures outside individual request promises.
 import {createCoreClassicSource} from 'arcane-os/core/classic-source';
 
 const source=await createCoreClassicSource({
-    eventOwnerModuleURL:'/arcane/sdk/event-manager.mjs'
+    eventOwnerModuleURL:'/arcane/sdk/event-manager.mjs',
+    replayRuntimeState:true
 });
 // Supply source to the native host's existing classic-script injection owner.
 ```
@@ -100,6 +141,8 @@ installed SDK. It emits the same implementation as a classic script, without
 copying another client or adding a bundler. The caller supplies the actual
 served SDK event-manager URL; the example URL must match its selected layout.
 That module and its existing managed import map must be included by packaging.
+Select `replayRuntimeState:true` only when composing a host with the current
+runtime replay control; omitting it preserves the existing no-replay default.
 
 The generated facade, native receive callback and current-state methods install
 synchronously. When the shared event owner already exists, it is reused

package/docs/reference/core-runtime.md

@@ -107,6 +107,16 @@ Events have `{protocol, type:'event', event, data, time}`:
 - `core.service.state`: a service's name, state and serialized error when present.
 - `core.error`: a lifecycle or transport diagnostic.
 
+A newly connected document may send
+`{protocol:'arcane/1', type:'control', control:'runtime.replay'}`. The runtime
+publishes one current snapshot: `core.ready` only when the dispatcher is ready,
+then `core.state`, followed by `core.service.state` for every registered service.
+Complete service errors and active request state are retained. Replay does not
+start or restart services, dispatch a request, poll readiness or create a second
+lifecycle owner. The runtime completes that snapshot before publishing lifecycle
+changes triggered reentrantly by its listeners. A draining runtime reports its
+draining state rather than announcing readiness.
+
 Service states are `registered`, `starting`, `ready`, `failed`, `draining` and
 `closed`. Dispatcher states are `created`, `ready`, `draining` and `closed`.
 Complete diagnostics belong in the host's developer-facing error handling, not