arcane-os 0.54.1 → 0.56.0

package/docs/reference/core-client.md

@@ -0,0 +1,163 @@
+# Core browser client
+
+`arcane-os/core/client` is the browser-safe `arcane/1` RPC owner. It exports
+`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;
+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.
+
+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.
+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.
+
+`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
+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.
+
+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
+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',
+    replayRuntimeState:true
+});
+// 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.
+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
+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.

package/docs/reference/core-native-packaging.md

@@ -0,0 +1,149 @@
+# Portable Core packaging
+
+`arcane-os/native/portable-provider` owns the portable native payload in the SDK
+package. It does not load Arcane OS source, choose models, download a runtime,
+or compile an executable. Windows, Linux and macOS hosts may compose this
+Node-based payload; Android needs its separate native host adaptation. The
+current CLI's portable platform selections remain Windows and Linux. A portable
+artifact is not a Windows executable, Linux package or Android application.
+
+`loadArcaneNativeProvider({target:'portable'})` selects the installed SDK provider
+without an `arcaneRoot`. Supplying an explicit `arcaneRoot` retains the existing
+checkout-provider route. Other native targets remain with their actual platform
+providers; the loader does not substitute this payload for an unavailable host.
+
+## Provider and selected input
+
+The default export and `arcaneNativeBuilderProvider` are the same provider.
+`createPortableNativeProvider({services:[]})` creates one with application-owned
+service configuration. All implement `arcane-native-builder/1`:
+
+- `describe()` identifies the portable target and `executable:false`.
+- `doctor({targetRequest, signal, onEvent})` reports missing SDK Core source files.
+- `prepare({targetRequest, signal, onEvent})` returns the selected SDK version and
+  package root. Neither operation builds or imports application services.
+- `build(request)` assembles one selected release and its explicit dependencies.
+- `verify({artifact, targetRequest, signal, onEvent})` explicitly reads its semantic
+  manifest and observes that the listed output files exist. It does not execute
+  a host or establish native behavior. Build does not implicitly run verification.
+- `run()` reports `ARCANE_NATIVE_RUN_UNSUPPORTED`; portable is not an executable.
+
+Use the existing `createNativeBuildPlan()` / `executeNativeBuildPlan()` public
+contract. Build receives `appDescriptor`, `appReleaseRoot`, `release`,
+`readReleaseFile`, `dependencies`, `minimumCoreVersion`, `protectedRoots`,
+`outputRoot`, `targetRequest`, `selectedSdk`, `signal` and `onEvent`. Dependencies provide their
+`appId`, `releaseRoot`, `release` and `readReleaseFile`. The selected release's
+`files` inventory is copied completely through its supplied reader. Direct
+callers may supply the release root for ordinary file reads instead.
+
+Both the current flat signing selection and the CLI's nested signing selection
+are accepted by the planning boundary. Portable assembly adds no signing,
+receipts, hashes, content limits or security policy. The package-relative source
+root comes from the provider module's own location, not `toolchainRoot` or an
+Arcane OS machine bundle.
+
+## Output and host contract
+
+Each build creates a fresh `arcane-portable-*` directory beneath `outputRoot`.
+The result is `{app, target, manifest}`, with its actual directory at
+`target.rootDir`. Existing artifacts are preserved. Cancellation or a failed
+assembly removes only that build's newly created directory. Source/release roots
+cannot be overwritten with generated output.
+
+The selected app is copied unchanged under `app/`. Dependencies are copied
+unchanged under `dependencies/<index>/`; the manifest relates each directory to
+its actual app identifier and selected release. No HTML, payload, line ending,
+application import, or base URL is rewritten by this provider. Dependency
+navigation and service imports remain explicit host/application composition;
+the payload does not invent cross-app routes.
+
+`node_modules/arcane-os/` contains the SDK consumer source, runtime, schemas,
+commands, package metadata and legal files. Its installed published runtime
+dependency tree is included with licenses and actual nested dependency
+resolution. The generated Core entry uses the ordinary public
+`arcane-os/core/host` import. Application service modules can use those public
+SDK exports through Node's normal package resolution. Existing app-owned
+`node_modules` content remains authoritative where the selected app supplies it;
+its own dependency completeness remains part of that app's selected release.
+For the direct installed browser layout, the ordinary native selection also
+supplies `selectedSdk:{packageRoot,packageSource}` from the application's actual
+installed SDK. Assembly completes its browser-only package directory with
+missing files and dependencies from that selected package, preserving every
+selected file. It never fills an older projection with the builder's newer
+package metadata. An already-supplied `package.json` remains app-owned, without
+replacement or automatic completion. `manifest.appSdk` identifies this app
+package separately from the builder SDK. Low-level callers composing services
+with a partial direct SDK projection must supply the actual selected package
+source; a file inventory alone does not identify its version or Node exports.
+No dependency installer or package script runs. No OS model, Shell, Provisioner,
+catalog, prompt, or native compiler is added.
+
+The semantic `arcane-native.json` names the web root, selected start URL, Node
+Core entry, classic client, dependencies and complete file inventory. A native
+host must:
+
+1. Mount `app/` at the root of its local application URL origin, preserving the
+   selected start path and all navigable documents.
+2. Inject `runtime/arcane-api.js` at document creation. It is produced by the
+   canonical `createCoreClassicSource()` generator, not a copied OS client.
+3. Start `runtime/arcane-core.mjs` with the host's supported Node runtime and
+   connect the existing framed stdin/stdout transport.
+4. Close input and await Core's drain before terminating the child process.
+
+The selected release must contain one shared `sdk/event-manager.mjs` path,
+possibly nested under its SDK payload directory, or the direct installed
+`node_modules/<package-or-alias>/browser-runtime/event-manager.mjs` path.
+The classic client imports that
+same owner with an origin-root URL, including on nested pages. It does not create
+a second event implementation. A plain file-URL launch without this host mapping
+is not the native serving contract. No host is launched during packaging.
+
+## Explicit application services
+
+Pass native service modules already included in the selected app release:
+
+```js
+import {createPortableNativeProvider} from 'arcane-os/native/portable-provider';
+
+const nativeBuilder = createPortableNativeProvider({
+    services: [{module:'native/moon-ledger.mjs', options:{ledgerName:'Cheese debts'}}]
+});
+```
+
+Each module default-exports a synchronous factory returning the existing Core
+service definition. Its options must be JSON-serializable data. Module imports
+and factories run only when the generated Core entry is launched, never during
+packaging. Put asynchronous initialization in `start()`, not a top-level await
+or asynchronous factory, so unrelated services and dispatcher readiness remain
+independent. Factories own product configuration and any service dependencies;
+the packager does not discover, install or execute them.
+
+```js
+// native/moon-ledger.mjs, owned by the application
+export default function createMoonLedger({ledgerName}) {
+    return {
+        name: 'moon-ledger',
+        methods: {
+            'moon.describe': function describeLedger() {
+                return {name:ledgerName, message:'The cheese debts are astronomical.'};
+            }
+        }
+    };
+}
+```
+
+`startCoreHost({application, version, services, input, output, onError, signal})`
+is also available directly from `arcane-os/core/host`. It returns the existing
+stdio owner's `{runtime, closed, close}` without another lifecycle controller.
+An optional abort signal invokes that same idempotent drain. Dispatcher readiness
+does not wait for service/model readiness. Accepted `lifetime:'service'` work
+survives renderer cancellation and is drained before shutdown. Errors remain
+observable through `onError` and `closed`; no process is killed or forcibly exited.
+See [the Core runtime contract](core-runtime.md) for request and service lifetime
+details and [the client contract](core-client.md) for native bridge integration.
+
+This source increment supplies portable assembly and service composition.
+Desktop WebView executables, platform child-process ownership, Android dispatch
+and executable build toolchains require their own completed adapters. Published
+consumers must adopt the numeric package that includes this increment; a source
+checkout or a successful source push is not that public package authority.

package/docs/reference/core-runtime.md

@@ -0,0 +1,185 @@
+# Native Core runtime
+
+The SDK owns the reusable native dispatcher and framed stdio transport.
+The composing application or native host supplies its identity, version and
+services. Product prompts, model selections, filesystem locations, host
+privileges and application policy remain with that owner.
+
+```js
+import {createCoreRuntime} from 'arcane-os/core/runtime';
+import {startCoreStdio} from 'arcane-os/core/stdio';
+import catalogStore from './catalog-store.mjs';
+
+const runtime = createCoreRuntime({
+    application: {id: 'moon-cheese-catalog', name: 'Moon Cheese Catalog'},
+    version: '1.0.0',
+    services: [{
+        name: 'catalog',
+        methods: {
+            'catalog.save': {
+                lifetime: 'service',
+                async handle(record) {
+                    // catalogStore is supplied by this application's native owner.
+                    return catalogStore.save(record);
+                }
+            }
+        },
+        async drain() {
+            await catalogStore.flush();
+        },
+        async dispose() {
+            await catalogStore.close();
+        }
+    }]
+});
+
+const transport = startCoreStdio({runtime});
+await transport.closed;
+```
+
+The example's store is an application dependency, not an SDK-created database.
+The runtime passes each request's `parameters` to its registered handler
+unchanged. It preserves complete results and diagnostic errors; it neither
+selects product data nor supplies replacement results.
+
+## Registration and startup
+
+`createCoreRuntime({application, version, services})` creates a dispatcher.
+Supply the application's real descriptor and host release version. The built-in
+`app.current` and `version.current` methods return those values; `system.ping`
+returns `{ok:true}`. A ping establishes dispatcher responsiveness, not model,
+service or application readiness.
+
+`runtime.registerService({name, methods, start, drain, dispose})` registers one
+native service. Method names are complete RPC names, such as `catalog.save`.
+A method is either a handler function or `{handle, lifetime}`. A handler function
+has request lifetime by default. Duplicate service or method names, including
+the three built-in methods, are reported rather than replacing another owner.
+Registration is a native composition API, not a browser command.
+
+Registration returns `{ready, current}`. Reading `ready` starts that service and
+returns its shared startup promise; `current()` exposes its state and actual
+error. `runtime.start()` starts all registered services independently and returns
+the current dispatcher state without waiting for them. A service registered
+after startup starts independently as well. A method waits only for its own
+service's startup before invoking its handler. State errors use the shared
+complete diagnostic serialization; the startup promise retains its original
+rejection value.
+
+Each lifecycle hook receives `{application, service, emit}`. Each request handler
+receives `(parameters, {application, service, emit, requestId, signal})`, with
+`this` bound to its service definition. A hook or handler may publish a complete
+service-owned event through `emit(event, data)`.
+
+## State and frames
+
+`runtime.current()` returns dispatcher state, application, version, per-service
+state/errors and active request identities, methods and lifetimes.
+`runtime.subscribe(listener, {emitCurrent:true, signal})` immediately replays the
+current state and then observes changes through the canonical SDK event owner.
+It returns an unsubscribe function. `runtime.onFrame(listener, {signal})`
+observes outgoing protocol frames and also returns an unsubscribe function.
+Attach transport listeners before starting the runtime to observe initial frames.
+
+The shared `arcane-os/core/contracts` module owns `CORE_PROTOCOL` (`arcane/1`),
+`CoreError` and `serializeCoreError`. Requests are:
+
+```js
+{
+    protocol: 'arcane/1',
+    type: 'request',
+    id: 'request-1',
+    method: 'catalog.save',
+    parameters: {name: 'Lunar cheddar', notes: 'Keep the complete supplied text.'}
+}
+```
+
+`await runtime.handle(frame)` returns and emits the correlated response:
+`{protocol, type:'response', id, ok:true, result, time}` or
+`{protocol, type:'response', id, ok:false, error, time}`. Framing and method
+availability errors remain observable; unavailable services are not replaced
+with browser behavior.
+
+Events have `{protocol, type:'event', event, data, time}`:
+
+- `core.ready`: the dispatcher is connected; service/model readiness is separate.
+- `core.state`: the current complete runtime state.
+- `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
+in ordinary chat history or a fabricated conversation turn.
+
+## Cancellation and shutdown
+
+The `request.cancel` control names `requestId`; `requests.cancelAll` applies to
+active request-lifetime operations. Cancellation is cooperative. The handler's
+signal is aborted. An otherwise successful cancelled operation returns
+`REQUEST_ABORTED` after its owned work settles; a handler's own rejection remains
+the actual reported error. If startup is still pending, cancellation is checked before
+the handler runs. A service that does not finish or respond to cancellation is
+still unfinished; the SDK does not report a forced timeout as successful cleanup.
+
+Use `lifetime:'service'` for accepted work, such as a save, that must survive a
+renderer cancellation or disconnect. These operations are not aborted by the
+request cancellation controls or by normal Core shutdown. The service still
+owns its persistence, queueing and failure semantics.
+
+`runtime.close()` is idempotent and retains the same completion promise. It stops
+accepting new requests, cancels request-lifetime operations, waits for accepted
+responses, then drains and disposes services. Independent services close
+concurrently; each service's startup, drain and dispose remain ordered.
+Shutdown errors remain complete and reject the close promise. A failed drain
+does not prevent the service's dispose hook from running.
+
+The final closed state is published before event subscriptions are released.
+`current()` remains available afterward; the disposed runtime is not restarted.
+The host must observe completion before terminating Core. The SDK does not call
+`process.exit()`, kill a host or claim durability after an operating-system crash
+or a host-forced termination.
+
+## Stdio transport
+
+`startCoreStdio({runtime, input, output, onError})` attaches a runtime and starts
+it. Streams default to `process.stdin` and `process.stdout`; diagnostics default
+to `console.error`, leaving stdout for protocol frames. It returns
+`{runtime, closed, close}`. Observe `closed` for final completion or failure.
+
+Frames use the existing `Content-Length` header followed by UTF-8 JSON. Length
+is transport-local framing only. `encodeCoreFrame(frame)` and
+`createCoreFrameDecoder(onFrame)` are also exported for host adapters. The
+decoder accepts fragmented or multiple frames through `push(chunk)`;
+`finish()` reports an incomplete final frame rather than dropping it.
+
+Requests dispatch concurrently. Outgoing frames preserve their queued order and
+wait for each writable-stream callback. Input EOF starts runtime shutdown, waits
+for accepted service work and queued output, and resolves `closed` afterward.
+An input stream closed without its normal EOF event also initiates this drain;
+an already ended or destroyed input is handled when attached. Transport failures
+reach `onError` and reject `closed`. The transport detaches
+its listeners and pauses its input; it does not end caller-owned output streams
+or take ownership of the host process.
+
+## Platform and delivery boundary
+
+These modules use portable Node and JavaScript facilities for Windows, Linux
+and macOS native hosts. Android requires its native transport/host adaptation;
+the module is not a Node runtime embedded inside a WebView. Browser callers use
+the separate [Core client](core-client.md).
+
+The dispatcher/transport sources are one part of Core extraction. They do not
+by themselves replace existing native host bundles, platform adapters, provider
+loading, packaging or OS composition. Those owners must adopt the selected
+published SDK boundary and preserve their real shutdown and service lifecycles.