arcane-os 0.54.0 → 0.55.0

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"
     }
   ]
 }

package/docs/reference/protocols.md

@@ -39,7 +39,7 @@ a nonzero CLI status.
 Machine output uses `arcane-cli-events/1`. Native planning and providers use:
 
 - `arcane-target-adapter/1` for target adapters;
-- `arcane-native-build-plan/1` for single-attempt native plans;
+- `arcane-native-build-plan/1` for native plans with complete selected release inputs;
 - `arcane-native-builder/1` for injected native builders;
 - `arcane-integrated-toolchain/1` for the fixed integrated shared/Core provider.
 
@@ -47,6 +47,15 @@ These protocols normalize orchestration and results. They do not normalize a
 Windows EXE, Linux DEB, Android APK, and portable directory into the same
 artifact kind.
 
+Portable CLI operations load the installed SDK's
+`arcane-os/native/portable-provider` by default. Explicit `--arcane-root`
+selection retains the checkout provider route; executable targets still need
+their platform provider/toolchain. `arcane-os/core/host` composes the reusable
+native runtime with explicitly supplied app services. Neither export is a
+browser import, executable host or installer. The synchronous classic facade
+and browser-safe client retain their separate public entries. Integrated
+shared checks keep their existing Arcane OS development provider.
+
 App-scoped managed browser imports have three supported control-plane entrypoints. The CLI
 uses `arcane import-map`; Node callers use
 `executeOperation('import-map', options)` or
@@ -236,6 +245,12 @@ For an extension, select `browserPwa:false` for that artifact and place the
 complete SDK-produced app beneath the app-owned extension root. The application
 owns its manifest, toolbar/background launcher and permissions. Ordinary browser
 PWA configuration and generated browser output remain independently available.
+Before native-module processing, the stage removes active `data-arcane-pwa`
+scripts and manifest relationships targeting the package's `arcane.webmanifest`
+from the existing selected PWA document set. Authored bases resolve those links;
+unrelated manifest URLs, other link relationships, comments, templates and other
+inactive HTML retain their content. Source documents and saved PWA settings
+remain unchanged; the operation does not sweep every packaged HTML file.
 
 ## Installed-package browser routes