arcane-os 0.54.1 → 0.56.0

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,272 @@
       "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, cancellation and runtime.replay control 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,replayRuntimeState=false,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; retains FIFO event-owner handoff; failTransport(error) settles pending RPCs and acknowledgements with the complete failure and releases the client lifetime; opt-in replayRuntimeState sends one observed nonblocking runtime.replay control after transport readiness"
+    },
+    {
+      "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, native receive callback and terminal transport-failure 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; close/failTransport release owned resources and restore prior globals only while still owned; __arcaneTransportFailed preserves the complete host failure without killing Core"
+    },
+    {
+      "id": "core-client:getInstalledCoreClient",
+      "name": "getInstalledCoreClient",
+      "displayName": "getInstalledCoreClient()",
+      "kind": "function",
+      "signature": "getInstalledCoreClient(global=globalThis)",
+      "entrypoints": ["arcane-os/core/client"],
+      "primaryImport": "arcane-os/core/client",
+      "group": "Core browser client",
+      "summary": "Returns the exact live SDK-installed client or null without installing, connecting or changing globals.",
+      "availability": "Browser and native WebView JavaScript hosts",
+      "protocol": "arcane/1 renderer client ownership",
+      "normalization": "Recognizes ESM and classic SDK installation identity; returns null after close or terminal failure and does not treat a foreign Arcane facade as an SDK client"
+    },
+    {
+      "id": "core-classic-source:createCoreClassicSource",
+      "name": "createCoreClassicSource",
+      "displayName": "createCoreClassicSource()",
+      "kind": "function",
+      "signature": "async createCoreClassicSource({eventOwnerModuleURL,replayRuntimeState=false}={})",
+      "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 event-owner module connection when document parsing is incomplete; forwards explicit runtime replay selection with a false default"
+    },
+    {
+      "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 complete results/errors, cancels only request-lifetime work and drains accepted service work; runtime.replay publishes current dispatcher/service state without restart and preserves reentrant lifecycle publication order"
+    },
+    {
+      "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
@@ -79,9 +88,11 @@ Explicit host document lists use the separate root-exported
 described below; they do not enter app discovery.
 
 The application dependency boundary is conditional. Only an application that
-actually consumes Arcane declares one exact published `arcane-os` version in
-its own `package.json` and resolves it through that project's normal install
-into its own `node_modules`. An application that does not currently consume
+actually consumes Arcane declares `arcane-os` in its own `package.json` and
+resolves it through that project's normal install into its own `node_modules`.
+During development the declaration tracks `latest`; the lockfile and installed
+package record the exact selected version. An explicitly selected production
+build may declare an exact version. An application that does not currently consume
 Arcane adds no `arcane-os` dependency solely because of this rule; the user or
 governing task may direct that application to adopt Arcane later, at which point
 the same app-owned package, install, projection, and artifact boundary applies.
@@ -236,6 +247,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
 
@@ -366,10 +383,11 @@ layouts; the default nested scaffold continues to use its development dependency
 ## Installed SDK runtime materialization
 
 `materializeInstalledSdkRuntime()` is the Node entrypoint for refreshing one
-external workspace's checked-in `arcane/` projection from its one exact
-installed SDK declaration. Import the function through the dependency key that
+external workspace's checked-in `arcane/` projection from its one declared and
+installed SDK dependency. Import the function through the dependency key that
 the workspace actually declares: `arcane-os` for the canonical package name or,
-for example, `arcane-sdk` for the exact `npm:arcane-os@<version>` alias. No
+for example, `arcane-sdk` for the development alias `npm:arcane-os@latest`. The
+lockfile and installed package retain the exact resolved version. No
 application- or Arcane OS-local copier owns this operation.
 
 The operation resolves that declaration while holding the shared
@@ -548,8 +566,8 @@ exactly `dependencyName`, `packageSource`,
 `canonicalPackageRoot`, `packageName`, `packageVersion`, `runtimeRoot`,
 and `browserRuntimeRoot`. A
 workspace may use the canonical dependency name or one npm alias such as
-`npm:arcane-os@0.51.1`; the installed package manifest identifies `arcane-os`
-and supplies its actual version. The resolver requires one declaration and a
+`npm:arcane-os@latest`; the installed package manifest identifies `arcane-os`
+and supplies its actual exact version. The resolver requires one declaration and a
 direct physical installation with runtime and browser-runtime directories.
 The application's normal npm declaration and lockfile own version selection.
 
@@ -984,9 +1002,12 @@ reachable.
 
 ### macOS
 
-No macOS target, native bridge, Core host, artifact, or run contract is exposed
-by this SDK version. A browser may still run browser-only application code, but
-that does not create a native Arcane host or satisfy a native capability.
+No macOS executable target, native bridge, platform host, artifact, or run
+contract is exposed by this SDK version. A browser may still run browser-only
+application code. A separately composed macOS host may use the reusable Node
+Core runtime, framed stdio transport, host composition, and portable payload,
+but those SDK primitives do not create a native bridge or executable host and
+do not by themselves satisfy a native capability.
 
 ## Development and remote HTTP transport
 
@@ -1068,8 +1089,11 @@ The common contract ends where platform truth must remain different:
   artifact kind, and some diagnostic/result fields remain platform-specific;
 - unsupported platforms fail or return a documented unsupported state; they do
   not run an unrelated browser implementation as a substitute;
-- this SDK version requires a selected checkout and Core to provide the current
-  native plan's protocol, version, feature, capability, method, and provider;
+- the portable target defaults to the installed SDK provider and assembles a
+  non-executable payload without an Arcane OS checkout;
+- executable native targets require their explicit checkout/provider, and the
+  composed host must supply the protocol, version, features, capabilities,
+  methods, and services that its application contract requires;
 - that current-build compatibility does not promise that a future SDK will accept
   this Core or that this SDK will accept a future Core.
 

package/docs/reference/pwa.md

@@ -206,6 +206,23 @@ manifest carries release information. Non-PWA and native packaging use the same
 [clean local resource URLs](asset-versioning.md). Native packaging does not
 generate the browser PWA worker, installation manifest or registration bootstrap.
 
+## Package without browser PWA output
+
+Select `browserPwa:false` for an artifact, such as an application directory
+inside an extension-owned root. The package omits `arcane.webmanifest`,
+`arcane-offline.json`, `arcane-sw.js`, and `arcane-pwa.mjs`. Before native-module
+processing, it removes active SDK-marked `data-arcane-pwa` scripts and manifest
+relationships that resolve to that package's `arcane.webmanifest` from the
+selected application document set.
+
+This is a package-output choice, not a source or saved-setting change. It
+preserves unrelated manifest links and link relationships, comments, templates,
+other inactive HTML, unselected documents, and authored PWA configuration. The
+application remains responsible for any extension manifest, permissions,
+background process, toolbar launcher, or other outer host. See the
+[native-module output contract](protocols.md#native-module-package-output) and
+[`packageApp()` options](sdk-api.md#packageapp) for the complete boundary.
+
 ## Development and hosting
 
 Use the ordinary `arcane dev --app <id>` command after editing the selected