arcane-os 0.54.1 → 0.55.0

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,175 @@
+# 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.
+
+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.

package/docs/reference/inventory/package-api.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.51.1",
+  "sdkVersion": "0.55.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 226,
+  "memberCount": 244,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
@@ -340,7 +340,7 @@
       "name": "assertIntegratedNativeToolchain",
       "displayName": "assertIntegratedNativeToolchain()",
       "kind": "function",
-      "signature": "assertIntegratedNativeToolchain({workspaceMode, workspaceRoot, toolchainRoot, target}={})",
+      "signature": "assertIntegratedNativeToolchain({workspaceMode, workspaceRoot, toolchainRoot, target, providerSource='arcane-checkout'}={})",
       "entrypoints": [
         "arcane-os",
         "arcane-os/toolchain"
@@ -540,7 +540,7 @@
       "name": "createNativeBuildPlan",
       "displayName": "createNativeBuildPlan()",
       "kind": "function",
-      "signature": "async createNativeBuildPlan({ nativeBuilder, toolchainRoot, toolchainReceipt, appReleaseRoot, appReleaseReceipt, appDescriptor, dependencyReleases=[], providerGeneration, minimumCoreVersion, protectedRoots=[], outputRoot, targetRequest, signal, onEvent }={})",
+      "signature": "async createNativeBuildPlan({ nativeBuilder, toolchainRoot, toolchain, appReleaseRoot, release, appDescriptor, selectedSdk, dependencyReleases, minimumCoreVersion, protectedRoots=[], outputRoot, targetRequest, signal, onEvent }={})",
       "entrypoints": [
         "arcane-os",
         "arcane-os/native"
@@ -1037,7 +1037,7 @@
       "name": "loadArcaneNativeProvider",
       "displayName": "loadArcaneNativeProvider()",
       "kind": "function",
-      "signature": "loadArcaneNativeProvider({ arcaneRoot, target, inspect=lstat, canonicalize=realpath, readModule=readFile, importModule=specifier=>import(specifier), generationCache=providerGenerationCache, signal, onEvent }={})",
+      "signature": "async loadArcaneNativeProvider({ arcaneRoot, target, inspect=lstat, canonicalize=realpath, importModule=specifier=>import(specifier), signal, onEvent }={})",
       "entrypoints": [
         "arcane-os",
         "arcane-os/native-provider"
@@ -3619,6 +3619,258 @@
       "availability": "Node and Browser",
       "protocol": "Shared AI cancellation",
       "normalization": "Preserves an existing ARCANE_AI_REQUEST_ABORTED value or returns an AbortError with that code and the supplied cause"
+    },
+    {
+      "id": "core-contracts:CORE_PROTOCOL",
+      "name": "CORE_PROTOCOL",
+      "displayName": "CORE_PROTOCOL",
+      "kind": "constant",
+      "signature": "const CORE_PROTOCOL = 'arcane/1'",
+      "entrypoints": ["arcane-os/core/contracts"],
+      "primaryImport": "arcane-os/core/contracts",
+      "group": "Core protocol contracts",
+      "summary": "Identifies Arcane Core request, response, event and control frames.",
+      "availability": "Node and browser/bundler",
+      "protocol": "arcane/1",
+      "normalization": "Exact protocol string; it identifies a frame contract without granting a method, service, transport or model capability"
+    },
+    {
+      "id": "core-contracts:CORE_READY_EVENTS",
+      "name": "CORE_READY_EVENTS",
+      "displayName": "CORE_READY_EVENTS",
+      "kind": "constant",
+      "signature": "const CORE_READY_EVENTS",
+      "entrypoints": ["arcane-os/core/contracts"],
+      "primaryImport": "arcane-os/core/contracts",
+      "group": "Core protocol contracts",
+      "summary": "Lists the transport and dispatcher events that the Core client treats as durable completions.",
+      "availability": "Node and browser/bundler",
+      "protocol": "arcane/1 client readiness",
+      "normalization": "Contains transport.ready and core.ready; neither event asserts application-service, repository or model readiness"
+    },
+    {
+      "id": "core-contracts:CORE_FRAME_CONTRACTS",
+      "name": "CORE_FRAME_CONTRACTS",
+      "displayName": "CORE_FRAME_CONTRACTS",
+      "kind": "constant",
+      "signature": "const CORE_FRAME_CONTRACTS",
+      "entrypoints": ["arcane-os/core/contracts"],
+      "primaryImport": "arcane-os/core/contracts",
+      "group": "Core protocol contracts",
+      "summary": "Describes the public fields on Core request, response, event and cancellation frames.",
+      "availability": "Node and browser/bundler",
+      "protocol": "arcane/1 wire descriptions",
+      "normalization": "Descriptive data only; it does not admit methods, validate application policy or create a transport"
+    },
+    {
+      "id": "core-contracts:CORE_METHOD_CONTRACTS",
+      "name": "CORE_METHOD_CONTRACTS",
+      "displayName": "CORE_METHOD_CONTRACTS",
+      "kind": "constant",
+      "signature": "const CORE_METHOD_CONTRACTS",
+      "entrypoints": ["arcane-os/core/contracts"],
+      "primaryImport": "arcane-os/core/contracts",
+      "group": "Core protocol contracts",
+      "summary": "Describes existing Core method input, output and semantic shapes.",
+      "availability": "Node and browser/bundler",
+      "protocol": "arcane/1 method descriptions",
+      "normalization": "Descriptive data only; the active host and its registered services remain the authority for method availability"
+    },
+    {
+      "id": "core-contracts:CoreError",
+      "name": "CoreError",
+      "displayName": "CoreError",
+      "kind": "class",
+      "signature": "new CoreError(value)",
+      "entrypoints": ["arcane-os/core/contracts"],
+      "primaryImport": "arcane-os/core/contracts",
+      "group": "Core protocol contracts",
+      "summary": "Creates the common Core error while retaining supplied native diagnostic fields.",
+      "availability": "Node and browser/bundler",
+      "protocol": "arcane/1 error response",
+      "normalization": "Preserves own fields, stack and cause; supplies Arcane defaults for absent name, code, message, resolution and diagnostic metadata"
+    },
+    {
+      "id": "core-contracts:serializeCoreError",
+      "name": "serializeCoreError",
+      "displayName": "serializeCoreError()",
+      "kind": "function",
+      "signature": "serializeCoreError(error)",
+      "entrypoints": ["arcane-os/core/contracts"],
+      "primaryImport": "arcane-os/core/contracts",
+      "group": "Core protocol contracts",
+      "summary": "Projects an error into a complete plain diagnostic record for Core responses and events.",
+      "availability": "Node and browser/bundler",
+      "protocol": "arcane/1 error response",
+      "normalization": "Retains own properties and ordinary name, message, stack and cause fields; recursively projects Error causes and AggregateError members"
+    },
+    {
+      "id": "core-client:createCoreClient",
+      "name": "createCoreClient",
+      "displayName": "createCoreClient()",
+      "kind": "function",
+      "signature": "createCoreClient({global=globalThis,transport=null,eventOwner=arcaneEvents,eventOwnerReady,autoConnect=true,onError}={})",
+      "entrypoints": ["arcane-os/core/client"],
+      "primaryImport": "arcane-os/core/client",
+      "group": "Core browser client",
+      "summary": "Creates one correlated Arcane Core RPC client with explicit transport, readiness, events, cancellation and lifetime ownership.",
+      "availability": "Browser and native WebView JavaScript hosts; custom transports require a callable send(frame)",
+      "protocol": "arcane/1 over the selected host transport",
+      "normalization": "Preserves complete request, result and event data; rejects invalid transports before readiness, retains FIFO handoff to the shared event owner and reports transport failures that arrive after request settlement"
+    },
+    {
+      "id": "core-client:createCoreFacade",
+      "name": "createCoreFacade",
+      "displayName": "createCoreFacade()",
+      "kind": "function",
+      "signature": "createCoreFacade(client)",
+      "entrypoints": ["arcane-os/core/client"],
+      "primaryImport": "arcane-os/core/client",
+      "group": "Core browser client",
+      "summary": "Projects a Core client into the established application-facing Arcane namespace.",
+      "availability": "Browser and native WebView JavaScript hosts with a Core client",
+      "protocol": "arcane/1 compatibility facade",
+      "normalization": "Routes existing namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation"
+    },
+    {
+      "id": "core-client:installCoreClient",
+      "name": "installCoreClient",
+      "displayName": "installCoreClient()",
+      "kind": "function",
+      "signature": "installCoreClient(global=globalThis,options={})",
+      "entrypoints": ["arcane-os/core/client"],
+      "primaryImport": "arcane-os/core/client",
+      "group": "Core browser client",
+      "summary": "Installs one synchronous global Arcane facade and native receive callback for the selected renderer lifetime.",
+      "availability": "Browser and native WebView JavaScript hosts",
+      "protocol": "arcane/1 renderer facade",
+      "normalization": "Repeated installation returns the same client; closing releases subscriptions, callbacks, timers and pending renderer requests without killing Core"
+    },
+    {
+      "id": "core-classic-source:createCoreClassicSource",
+      "name": "createCoreClassicSource",
+      "displayName": "createCoreClassicSource()",
+      "kind": "function",
+      "signature": "async createCoreClassicSource({eventOwnerModuleURL}={})",
+      "entrypoints": ["arcane-os/core/classic-source"],
+      "primaryImport": "arcane-os/core/classic-source",
+      "group": "Core classic client projection",
+      "summary": "Generates the native host's classic injection script from the installed canonical Core client and contracts.",
+      "availability": "Node; generated source runs in browser and native WebView renderers",
+      "protocol": "arcane/1 classic-script injection",
+      "normalization": "Returns the complete canonical client projection; installs synchronous facade shapes while deferring only the shared event-owner module connection when document parsing is incomplete"
+    },
+    {
+      "id": "core-runtime:createCoreRuntime",
+      "name": "createCoreRuntime",
+      "displayName": "createCoreRuntime()",
+      "kind": "function",
+      "signature": "createCoreRuntime({application,version,services=[]}={})",
+      "entrypoints": ["arcane-os/core/runtime"],
+      "primaryImport": "arcane-os/core/runtime",
+      "group": "Native Core runtime",
+      "summary": "Creates an app-neutral Core dispatcher with explicit services, request lifetimes, events and graceful drain.",
+      "availability": "Node on Windows, Linux and macOS native hosts; Android requires its host adaptation",
+      "protocol": "arcane/1 dispatcher and service lifecycle",
+      "normalization": "Starts services independently, preserves request correlation and complete results/errors, cancels only request-lifetime work and waits accepted service-lifetime responses before ordered service drain and disposal"
+    },
+    {
+      "id": "core-stdio:encodeCoreFrame",
+      "name": "encodeCoreFrame",
+      "displayName": "encodeCoreFrame()",
+      "kind": "function",
+      "signature": "encodeCoreFrame(frame)",
+      "entrypoints": ["arcane-os/core/stdio"],
+      "primaryImport": "arcane-os/core/stdio",
+      "group": "Native Core stdio transport",
+      "summary": "Encodes one Core frame as UTF-8 JSON with the native Content-Length transport header.",
+      "availability": "Node",
+      "protocol": "Content-Length framed arcane/1 stdio",
+      "normalization": "Returns a Buffer containing one transport frame; framing length remains transport-local and the JSON payload retains the supplied frame fields"
+    },
+    {
+      "id": "core-stdio:createCoreFrameDecoder",
+      "name": "createCoreFrameDecoder",
+      "displayName": "createCoreFrameDecoder()",
+      "kind": "function",
+      "signature": "createCoreFrameDecoder(onFrame)",
+      "entrypoints": ["arcane-os/core/stdio"],
+      "primaryImport": "arcane-os/core/stdio",
+      "group": "Native Core stdio transport",
+      "summary": "Creates the incremental decoder for fragmented or consecutive native Core frames.",
+      "availability": "Node",
+      "protocol": "Content-Length framed arcane/1 stdio",
+      "normalization": "push(chunk) delivers each complete parsed JSON value in order; finish() reports an incomplete final header or body instead of dropping it"
+    },
+    {
+      "id": "core-stdio:startCoreStdio",
+      "name": "startCoreStdio",
+      "displayName": "startCoreStdio()",
+      "kind": "function",
+      "signature": "startCoreStdio({runtime,input=process.stdin,output=process.stdout,onError}={})",
+      "entrypoints": ["arcane-os/core/stdio"],
+      "primaryImport": "arcane-os/core/stdio",
+      "group": "Native Core stdio transport",
+      "summary": "Attaches an existing Core runtime to framed input and output with concurrent dispatch and graceful shutdown.",
+      "availability": "Node with readable input and writable output streams",
+      "protocol": "Content-Length framed arcane/1 stdio",
+      "normalization": "Returns {runtime,closed,close}; preserves queued output order, reports parser and stream failures, drains accepted runtime work on EOF and never exits the host or ends caller-owned output"
+    },
+    {
+      "id": "native-portable-provider:createPortableNativeProvider",
+      "name": "createPortableNativeProvider",
+      "displayName": "createPortableNativeProvider()",
+      "kind": "function",
+      "signature": "createPortableNativeProvider({services=[]}={})",
+      "entrypoints": ["arcane-os/native/portable-provider"],
+      "primaryImport": "arcane-os/native/portable-provider",
+      "group": "Portable native provider",
+      "summary": "Creates the SDK-owned provider that assembles one selected app and explicit services into a portable Core payload.",
+      "availability": "Node; produces a portable payload rather than an executable host",
+      "protocol": "arcane-native-builder/1 portable provider",
+      "normalization": "Preserves complete selected app and dependency releases, uses explicit service module factories, reports executable:false and never substitutes for an unavailable platform host"
+    },
+    {
+      "id": "native-portable-provider:arcaneNativeBuilderProvider",
+      "name": "arcaneNativeBuilderProvider",
+      "displayName": "arcaneNativeBuilderProvider",
+      "kind": "singleton",
+      "signature": "const arcaneNativeBuilderProvider",
+      "entrypoints": ["arcane-os/native/portable-provider"],
+      "primaryImport": "arcane-os/native/portable-provider",
+      "group": "Portable native provider",
+      "summary": "Package-owned portable provider with no preconfigured application services.",
+      "availability": "Node; produces a portable payload rather than an executable host",
+      "protocol": "arcane-native-builder/1 portable provider",
+      "normalization": "Binding identity is exactly equal to the subpath default export; describe, doctor, prepare, build and verify retain portable semantics while run reports unsupported"
+    },
+    {
+      "id": "native-portable-provider:default",
+      "name": "default",
+      "displayName": "arcaneNativeBuilderProvider default export",
+      "kind": "singleton",
+      "signature": "default as arcaneNativeBuilderProvider",
+      "entrypoints": ["arcane-os/native/portable-provider"],
+      "primaryImport": "arcane-os/native/portable-provider",
+      "group": "Portable native provider",
+      "summary": "Default package binding for the same portable provider exposed by arcaneNativeBuilderProvider.",
+      "availability": "Node; produces a portable payload rather than an executable host",
+      "protocol": "arcane-native-builder/1 portable provider",
+      "normalization": "Binding identity is exactly equal to the named arcaneNativeBuilderProvider export"
+    },
+    {
+      "id": "core-host:startCoreHost",
+      "name": "startCoreHost",
+      "displayName": "startCoreHost()",
+      "kind": "function",
+      "signature": "startCoreHost({application,version,services=[],input,output,onError,signal}={})",
+      "entrypoints": ["arcane-os/core/host"],
+      "primaryImport": "arcane-os/core/host",
+      "group": "Native Core host composition",
+      "summary": "Composes explicitly supplied application services with the shared Core runtime and stdio lifecycle.",
+      "availability": "Node with readable input and writable output streams",
+      "protocol": "arcane/1 over Content-Length framed stdio",
+      "normalization": "Returns the existing {runtime,closed,close} transport owner; an optional abort signal invokes the same idempotent drain without killing the process, replacing service readiness or cancelling accepted service-lifetime work"
     }
   ]
 }