arcane-os 0.54.1 → 0.55.0

package/browser-runtime/core/contracts.mjs

@@ -0,0 +1,84 @@
+export const CORE_PROTOCOL='arcane/1';
+export const CORE_READY_EVENTS=['transport.ready','core.ready'];
+
+/** Wire descriptions, not method admission or application policy. */
+export const CORE_FRAME_CONTRACTS={
+    request:{type:'request',fields:['protocol','type','id','method','parameters','sentAt']},
+    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']}
+};
+
+/** These names describe existing methods; installed services determine availability. */
+export const CORE_METHOD_CONTRACTS={
+    'system.ping':{input:'empty-object-v1',output:'system-ping-result-v1',meaning:'Dispatcher response, not application or model readiness.'},
+    'version.current':{input:'empty-object-v1',output:'version-string-v1',meaning:'Active host release version.'},
+    'app.current':{input:'empty-object-v1',output:'application-descriptor-v1'},
+    'capabilities.list':{input:'empty-object',output:'{app,grants,methods}'},
+    'platform.status':{input:'empty-object-v1',output:'platform-status-v1'},
+    'network.status':{input:'empty-object-v1',output:'network-status-v1',meaning:'A non-loopback interface is present; this is not proof of Internet reachability.'},
+    'apps.list':{input:'empty-object-v1',output:'application-catalog-v1'},
+    'apps.launch':{input:'application-launch-v1',output:'application-launch-result-v1',meaning:'Host acceptance, not application readiness.'},
+    'external.open':{input:'external-open-v1',output:'external-open-result-v1',meaning:'Host acceptance, not confirmation of a user action.'},
+    'filesystem.directory.select':{input:'directory-selection-options',output:'directory-selection-result'},
+    'storage.list':{input:'empty-object',output:'{keys}'},
+    'storage.get':{input:'{key}',output:'{key,found,value}'},
+    'storage.set':{input:'{key,value}',output:'{key,value}'},
+    'storage.delete':{input:'{key}',output:'{key,deleted}'},
+    'preferences.list':{input:'empty-object',output:'{keys}'},
+    'preferences.get':{input:'{key}',output:'{key,found,value}'},
+    'preferences.set':{input:'{key,value}',output:'{key,value}'},
+    'preferences.setMany':{input:'{entries}',output:'preference-batch-result'},
+    'preferences.delete':{input:'{key}',output:'{key,deleted}'},
+    'terminal.start':{input:'terminal-start-v1',output:'terminal-session-v1'},
+    'terminal.list':{input:'empty-object-v1',output:'terminal-list-v1'},
+    'terminal.write':{input:'terminal-write-v1',output:'terminal-write-result-v1'},
+    'terminal.resize':{input:'terminal-resize-v1',output:'terminal-resize-result-v1'},
+    'terminal.signal':{input:'terminal-signal-v1',output:'terminal-signal-result-v1'},
+    'terminal.close':{input:'terminal-session-id-v1',output:'terminal-close-result-v1'},
+    'environment.list':{input:'empty-object-v1',output:'environment-list-result-v1'},
+    'environment.get':{input:'environment-name-v1',output:'environment-get-result-v1'},
+    'environment.set':{input:'environment-set-v1',output:'environment-set-result-v1'},
+    'environment.delete':{input:'environment-name-v1',output:'environment-delete-result-v1'},
+    'mail.send':{input:'mail-send-v1',output:'mail-send-result-v1'},
+    'user.current':{input:'empty-object-v1',output:'user-identity-v1'}
+};
+
+export class CoreError extends Error{
+    constructor(value){
+        const source=value!==null&&typeof value==='object'
+            ?value
+            :{message:value===undefined?'Arcane operation failed.':String(value)};
+        super(source.message??source.userMessage??'Arcane operation failed.');
+        for(const key of Object.getOwnPropertyNames(source))this[key]=source[key];
+        this.name=source.name??'ArcaneError';
+        this.code=source.code??'ARCANE_ERROR';
+        this.resolution=source.resolution??null;
+        this.diagnosticId=source.diagnosticId??null;
+        this.technicalMessage=source.technicalMessage??source.message??null;
+        const hresult=String(source.message??'').match(/\b0x[0-9a-f]{8}\b/iu);
+        this.hresult=source.hresult??hresult?.[0]?.toUpperCase()??null;
+        this.causeName=source.causeName??(source.name&&source.name!=='ArcaneError'?source.name:null);
+        if(source.stack!==undefined)this.stack=source.stack;
+        if(source.cause!==undefined)this.cause=source.cause;
+    }
+}
+
+export function serializeCoreError(error){
+    if(error===null||typeof error!=='object'){
+        return {name:'Error',code:'ARCANE_ERROR',message:String(error)};
+    }
+    const record=Object.fromEntries(Object.getOwnPropertyNames(error).map(key=>[key,error[key]]));
+    for(const key of ['name','message','stack','cause']){
+        if(error[key]!==undefined)record[key]=key==='cause'&&error[key] instanceof Error
+            ?serializeCoreError(error[key]):error[key];
+    }
+    if(Array.isArray(error.errors)){
+        record.errors=error.errors.map(value=>value instanceof Error?serializeCoreError(value):value);
+    }
+    if(record.name===undefined)record.name='Error';
+    if(record.code===undefined)record.code='ARCANE_ERROR';
+    if(record.message===undefined)record.message='Arcane operation failed.';
+    return record;
+}

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/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/reference/README.md

@@ -67,12 +67,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

@@ -229,8 +229,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

package/docs/reference/core-client.md

@@ -0,0 +1,120 @@
+# Core browser client
+
+`arcane-os/core/client` is the browser-safe `arcane/1` RPC owner. It exports
+`createCoreClient`, `createCoreFacade` and `installCoreClient`.
+`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;
+they do not select application policy or decide which services are installed.
+
+## Native connection and explicit adapters
+
+```js
+import {installCoreClient} from 'arcane-os/core/client';
+
+const client=installCoreClient();
+const stop=client.events.when('core.ready',state=>{
+    console.log('The moon-base dispatcher is connected.',state);
+});
+```
+
+Installation immediately supplies `globalThis.Arcane`, `__arcaneReceive`,
+synchronous `Arcane.runtime.current()` and `Arcane.events.completed(name)`.
+Repeated installation returns the same client. Existing namespace method names
+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.
+
+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.
+Native process startup and shutdown belong to the native host/runtime, not
+this browser module.
+
+For a separately owned transport, use `createCoreClient({transport})` with
+`transport.name`, `send(frame)`, and an optional `subscribe(receive)` returning
+an unsubscribe function. Alternatively deliver responses/events through
+`client.receive(frame)`. An adapter may return a promise from `send`; rejection
+rejects the associated pending request. If cancellation, timeout or a response
+has already settled it, `onError` observes the later send failure. A transport
+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.
+
+`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
+to transports that require it; values crossing those transports must be
+JSON-compatible. There is no client method allowlist or content limit.
+The default request timeout is ten minutes; `timeoutMs:0` disables that timer.
+The compatibility facade retains its operation-specific timeouts and streaming
+callbacks. Streaming IDs and isolated-operation IDs are separate protocol
+correlation fields alongside the supplied request fields.
+
+## Events and request lifetime
+
+`events.on(name, listener)`, `once(name, listener)` and
+`when(name, listener)` return unsubscribe functions. Named listeners receive
+the original `data`; `on('*', listener)` receives `{event, data}`. The shared
+SDK event owner provides delivery, with one source per client and no competing
+event bus. `when` replays the first authoritative `transport.ready` or
+`core.ready` state once, on a microtask. `completed` is synchronous.
+
+Transport connection, Core dispatcher readiness, application-service state,
+repository synchronization and model readiness are different states.
+`core.ready` does not claim that a model is loaded or an app repository synced.
+Other service events pass through normally; this client does not fabricate
+service readiness.
+
+Abort/timeout sends `request.cancel`; `cancelAll()` and page hide send
+`requests.cancelAll` for pending renderer requests. Late responses cannot
+resolve a cancelled request. These controls do not promise to roll back an
+accepted mutation. Accepted saves, operation journals and graceful drain belong
+to the service/runtime owner. `client.close()` releases its subscriptions,
+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.
+
+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
+where the native error does not already supply them. Errors without a native
+code receive the adapter's bridge-call failure code. Keep those details in
+developer diagnostics, rather than ordinary
+product status surfaces. The optional `onError(error)` callback observes
+transport/event-owner failures outside individual request promises.
+
+## Classic native-host injection
+
+```js
+import {createCoreClassicSource} from 'arcane-os/core/classic-source';
+
+const source=await createCoreClassicSource({
+    eventOwnerModuleURL:'/arcane/sdk/event-manager.mjs'
+});
+// Supply source to the native host's existing classic-script injection owner.
+```
+
+This Node-only source generator reads the canonical client and contracts in the
+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.
+
+The generated facade, native receive callback and current-state methods install
+synchronously. When the shared event owner already exists, it is reused
+immediately. Document-created injection can precede the page's import map, so
+only its event-owner module import waits until document parsing completes.
+Page rendering and RPC setup continue independently. Complete early event
+frames, subscription operations and response deliveries remain ordered until
+the event owner connects. Work received reentrantly during that handoff joins
+the end of the existing queue, including new subscriptions and response frames.
+Final response completion follows earlier event
+delivery, preserving streaming callbacks before their completion cleanup.
+`client.eventsReady` observes that connection; failures are also reported
+through `onError` and reject pending requests.
+
+The SDK's [portable native provider](core-native-packaging.md) assembles the
+Core runtime and selected app services without a native-provider checkout.
+It does not distribute a Core executable or change OS callers. Executable
+platform hosts and their cutover remain separately owned work.