arcane-os 0.56.0 → 0.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -39,6 +39,8 @@
     "./speech-playback": "./runtime/arcane/modules/SpeechPlayback.js",
     "./speech-text": "./browser-runtime/speech-text.mjs",
     "./ai/browser-wasm": "./browser-runtime/ai/browser-wasm.mjs",
+    "./ai/core-local": "./browser-runtime/ai/core-local.mjs",
+    "./ai/core-onnx": "./browser-runtime/ai/core-onnx.mjs",
     "./ai/browser-decisions": "./browser-runtime/ai/browser-decisions.mjs",
     "./ai/tool-text-stream": "./browser-runtime/ai/tool-text-stream.mjs",
     "./ai/twin-cloud": "./browser-runtime/ai/twin-cloud.mjs",
@@ -49,12 +51,22 @@
     "./native": "./src/native-plan.mjs",
     "./native-provider": "./src/native-provider-loader.mjs",
     "./native/portable-provider": "./src/native/portable-provider.mjs",
+    "./native/windows-provider": "./src/native/windows-provider.mjs",
+    "./native/macos-provider": "./src/native/macos-provider.mjs",
     "./core/client": "./browser-runtime/core/client.mjs",
     "./core/contracts": "./browser-runtime/core/contracts.mjs",
     "./core/classic-source": "./src/core-classic-source.mjs",
     "./core/runtime": "./src/core/runtime.mjs",
     "./core/stdio": "./src/core/stdio.mjs",
     "./core/host": "./src/core/host.mjs",
+    "./core/packaged-web": "./src/core/services/packaged-web.mjs",
+    "./core/preferences": "./src/core/services/preferences.mjs",
+    "./core/diarization": "./src/diarization/service.mjs",
+    "./core/local-ai": "./src/core/services/local-ai.mjs",
+    "./diarization": "./src/diarization/index.mjs",
+    "./diarization/build": "./src/diarization/build.mjs",
+    "./local-ai": "./src/local-ai/install.mjs",
+    "./local-ai/onnx": "./src/local-ai/onnx.mjs",
     "./integrated-provider": "./src/integrated-provider-loader.mjs",
     "./packager": "./src/packager/core.mjs",
     "./release-bundle": "./src/release-bundle.mjs",
@@ -96,8 +108,8 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/conversation-closing-report.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-host.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
-    "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-portable-provider.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-host.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
+    "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-macos-provider.test.mjs test/native-plan.test.mjs test/native-portable-provider.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/html-import-packaged-script.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",
     "check:release": "node tools/check-source.mjs --package-only && npm run test:release",

package/runtime/arcane/modules/LocalAIReadiness.js

@@ -555,7 +555,9 @@ async function probeRequiredServices({
                         arcane,
                         requirements.llm.model
                     )
-                    :unavailableBrowserOllama()
+                    :is.function(arcane?.localAI?.status)
+                        ?probeNativeOllama(arcane,requirements.llm.model)
+                        :unavailableBrowserOllama()
             :null,
         requiresSpeech
             ?mode==='native'

package/schemas/arcane-app.schema.json

@@ -119,6 +119,19 @@
           "oneOf": [{ "$ref": "#/$defs/rasterIcon" }, { "type": "null" }]
         },
         "order": { "type": "integer", "minimum": 0 },
+        "services": {
+          "description": "Explicit application-owned Core factory modules from the selected native release. Factories receive authored options first and launch context second.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["module"],
+            "properties": {
+              "module": { "$ref": "#/$defs/relativePath" },
+              "options": {}
+            }
+          }
+        },
+        "localAI": { "$ref": "#/$defs/localAI" },
         "bundledApps": {
           "type": "array",
           "uniqueItems": true,
@@ -167,7 +180,7 @@
       "minItems": 1,
       "uniqueItems": true,
       "items": {
-        "enum": ["android-arm64", "browser", "linux-arm64", "linux-x64", "portable", "windows-x64"]
+        "enum": ["android-arm64", "browser", "linux-arm64", "linux-x64", "macos-arm64", "macos-x64", "portable", "windows-x64"]
       }
     }
   },
@@ -240,6 +253,47 @@
     }
   ],
   "$defs": {
+    "localAI": {
+      "type": "object",
+      "required": ["runtimes"],
+      "description": "Required Core AI runtimes. Development ensures selected runtimes locally; native builds bundle their upstream runtime distributions. Model selection remains application-owned.",
+      "properties": {
+        "runtimes": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "enum": ["llama.cpp", "ollama", "onnx"] },
+              {
+                "type": "object",
+                "required": ["id"],
+                "properties": {
+                  "id": { "enum": ["llama.cpp", "ollama", "onnx"] },
+                  "version": { "type": "string" },
+                  "url": { "type": "string" }
+                }
+              }
+            ]
+          }
+        },
+        "llamaCpp": {
+          "type": "object",
+          "properties": {
+            "url": { "type": "string" },
+            "model": { "type": "string" },
+            "modelsDirectory": { "type": "string" },
+            "args": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "ollama": {
+          "type": "object",
+          "properties": {
+            "url": { "type": "string" },
+            "modelsDirectory": { "type": "string" },
+            "args": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
     "pwa": {
       "type": "object",
       "additionalProperties": false,

package/schemas/arcane-package.schema.json

@@ -57,6 +57,9 @@
     "localAIModelPolicy": {
       "$ref": "#/$defs/localAIModelPolicy"
     },
+    "localAI": {
+      "$ref": "#/$defs/localAI"
+    },
     "pwa": {
       "$ref": "#/$defs/pwa"
     },
@@ -144,6 +147,47 @@
     }
   ],
   "$defs": {
+    "localAI": {
+      "type": "object",
+      "required": ["runtimes"],
+      "description": "Required Core AI runtimes. Development ensures selected runtimes locally; native builds bundle their upstream runtime distributions. Model selection remains application-owned.",
+      "properties": {
+        "runtimes": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              { "enum": ["llama.cpp", "ollama", "onnx"] },
+              {
+                "type": "object",
+                "required": ["id"],
+                "properties": {
+                  "id": { "enum": ["llama.cpp", "ollama", "onnx"] },
+                  "version": { "type": "string" },
+                  "url": { "type": "string" }
+                }
+              }
+            ]
+          }
+        },
+        "llamaCpp": {
+          "type": "object",
+          "properties": {
+            "url": { "type": "string" },
+            "model": { "type": "string" },
+            "modelsDirectory": { "type": "string" },
+            "args": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "ollama": {
+          "type": "object",
+          "properties": {
+            "url": { "type": "string" },
+            "modelsDirectory": { "type": "string" },
+            "args": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
     "pwa": {
       "type": "object",
       "additionalProperties": false,

package/schemas/native-build-plan.schema.json

@@ -117,7 +117,7 @@
             {
               "properties": {
                 "target": { "const": "portable" },
-                "platform": { "enum": ["windows", "linux"] },
+                "platform": { "enum": ["windows", "linux", "macos"] },
                 "architecture": { "enum": ["x64", "arm64"] },
                 "format": { "const": "portable" }
               }
@@ -163,6 +163,32 @@
             }
           ]
         },
+        {
+          "allOf": [
+            { "$ref": "#/$defs/unsignedTargetRequest" },
+            {
+              "properties": {
+                "target": { "const": "macos-arm64" },
+                "platform": { "const": "macos" },
+                "architecture": { "const": "arm64" },
+                "format": { "const": "app" }
+              }
+            }
+          ]
+        },
+        {
+          "allOf": [
+            { "$ref": "#/$defs/unsignedTargetRequest" },
+            {
+              "properties": {
+                "target": { "const": "macos-x64" },
+                "platform": { "const": "macos" },
+                "architecture": { "const": "x64" },
+                "format": { "const": "app" }
+              }
+            }
+          ]
+        },
         {
           "type": "object",
           "required": ["target", "platform", "architecture", "format", "signing", "signingProfileId"],

package/schemas/target-adapter.schema.json

@@ -48,6 +48,7 @@
           "any",
           "windows",
           "linux",
+          "macos",
           "android"
         ]
       }
@@ -73,6 +74,7 @@
           "directory",
           "portable",
           "exe",
+          "app",
           "appimage",
           "deb",
           "rpm",

package/src/app-descriptor.mjs

@@ -5,6 +5,7 @@ import {readFile, writeFile} from 'node:fs/promises';
 import path from 'node:path';
 import {throwIfAborted} from './errors.mjs';
 import {normalizePwaConfig} from './pwa.mjs';
+import {normalizeLocalAIConfig} from './local-ai/config.mjs';
 import {
     ARCANE_MACHINE_BUNDLE_VERSION,
     ARCANE_PROTOCOL,
@@ -235,7 +236,7 @@ function validateDocumentCatalog(value){
 }
 
 function validateNative(value,appId){
-    assertOnlyKeys(value,new Set(['type','icon','order','bundledApps','documentCatalog']),'descriptor.native');
+    assertOnlyKeys(value,new Set(['type','icon','order','bundledApps','documentCatalog','localAI','services']),'descriptor.native');
     if(!NATIVE_TYPES.has(value.type))fail('descriptor.native.type is unsupported.');
     const icon=value.icon===null?null:normalizeRelativePath(value.icon,'descriptor.native.icon');
     if(!is.integer(value.order)||value.order<0){
@@ -245,11 +246,21 @@ function validateNative(value,appId){
         pattern:APP_ID_PATTERN
     });
     const documentCatalog=validateDocumentCatalog(value.documentCatalog);
+    let services;
+    if(value.services!==undefined){
+        if(!is.array(value.services))fail('descriptor.native.services must be an array.');
+        services=value.services.map(function nativeService(service,index){
+            if(!isObject(service))fail(`descriptor.native.services[${index}] must be an object.`);
+            return {...service,module:normalizeRelativePath(service.module,`descriptor.native.services[${index}].module`)};
+        });
+    }
     return completeValue({
         type:value.type,
         icon,
         order:value.order,
         bundledApps,
+        ...(services===undefined?{}:{services}),
+        ...(value.localAI===undefined?{}:{localAI:normalizeLocalAIConfig(value.localAI)}),
         ...(documentCatalog?{documentCatalog}:{})
     });
 }
@@ -337,6 +348,7 @@ export function projectPackageManifest(descriptor){
             mediaOrigins:[...value.security.mediaOrigins]
         }}:{}),
         ...(value.package.localAIModelPolicy?{localAIModelPolicy:value.package.localAIModelPolicy}:{}),
+        ...(value.native.localAI===undefined?{}:{localAI:value.native.localAI}),
         ...(value.package.pwa===undefined?{}:{pwa:value.package.pwa}),
         include:[...value.package.include],
         exclude:[...value.package.exclude],
@@ -382,6 +394,8 @@ export function projectNativeDescriptor(descriptor,{source}={}){
         }}:{}),
         ...(value.native.bundledApps.length?{bundledApps:[...value.native.bundledApps]}:{}),
         ...(value.native.documentCatalog?{documentCatalog:value.native.documentCatalog}:{}),
+        ...(value.native.services===undefined?{}:{services:value.native.services}),
+        ...(value.native.localAI===undefined?{}:{localAI:value.native.localAI}),
         include:[...value.package.include]
     };
 }
@@ -425,6 +439,8 @@ function synthesizedDescriptor(packageManifest,nativeDescriptor){
             icon:native.icon??null,
             order:is.integer(native.order)?native.order:100,
             bundledApps:[...(native.bundledApps??[])],
+            ...(native.services===undefined?{}:{services:native.services}),
+            ...((packageManifest.localAI??native.localAI)===undefined?{}:{localAI:packageManifest.localAI??native.localAI}),
             ...(native.documentCatalog?{documentCatalog:native.documentCatalog}:{})
         },
         requirements:{
@@ -433,7 +449,7 @@ function synthesizedDescriptor(packageManifest,nativeDescriptor){
             features:[]
         },
         targets:nativeDescriptor!==undefined
-            ?['android-arm64','browser','linux-arm64','linux-x64','portable','windows-x64']
+            ?['android-arm64','browser','linux-arm64','linux-x64','macos-arm64','macos-x64','portable','windows-x64']
             :['browser']
     },{appId:packageManifest.id});
 }

package/src/cli/main.mjs

@@ -16,6 +16,7 @@ const VALUE_OPTIONS=new Set([
     'app',
     'apps-root',
     'sdk-runtime-source',
+    'local-ai',
     'arcane-root',
     'host',
     'port',
@@ -66,7 +67,7 @@ Usage:
   ${CLI_NAME} upgrade [--workspace <directory>] [--app <id>]
   ${CLI_NAME} doctor [--workspace <directory>] [--arcane-root <directory>]
   ${CLI_NAME} import-map [--workspace <directory>] [--app <id>]
-  ${CLI_NAME} dev [--app <id>] [--public] [--http | --https] [--cert <pem>] [--key <pem>] [--host <address>] [--port 8000] [--http-port 0] [--sdk-runtime-source <sdk-root>]
+  ${CLI_NAME} dev [--app <id>] [--public] [--http | --https] [--cert <pem>] [--key <pem>] [--host <address>] [--port 8000] [--http-port 0] [--sdk-runtime-source <sdk-root>] [--local-ai llama.cpp,ollama,onnx]
   ${CLI_NAME} test [--app <id>] [--scope app]
   ${CLI_NAME} test --scope shared --test-file <repo-relative.test.mjs>
   ${CLI_NAME} check [--app <id>] [--scope app] [--skip-tests]
@@ -97,6 +98,7 @@ Development:
   --host <address>               Override the bind address; takes precedence over --public.
   --http-port <port>             Browser dev/run HTTP redirect port; 0 selects an available port (default).
   --sdk-runtime-source <sdk-root>  Dev-only live SDK checkout; omitted preserves the workspace runtime mode.
+  --local-ai <runtimes>          Add required Core runtimes to app config and ensure them for development.
 
 Global:
   --workspace <directory>       Select an external or integrated Arcane workspace.
@@ -450,6 +452,9 @@ function operationOptions(command,parsed,cwd){
     if(values['sdk-runtime-source']!==undefined&&command!=='dev'){
         usage('--sdk-runtime-source is supported only by dev.');
     }
+    if(values['local-ai']!==undefined&&command!=='dev'){
+        usage('--local-ai is supported only by dev.');
+    }
     if(flags.has('public')&&command!=='dev'){
         usage('--public is supported only by dev.');
     }
@@ -546,6 +551,7 @@ function operationOptions(command,parsed,cwd){
             ...browserServerOptions,
             host:values.host??(flags.has('public')?'0.0.0.0':'127.0.0.1'),
             port:readPort(values.port,8000),
+            ...(values['local-ai']===undefined?{}:{localAI:values['local-ai']}),
             ...(values['sdk-runtime-source']===undefined?{}:{
                 sdkRuntimeSourceRoot:path.resolve(cwd,values['sdk-runtime-source'])
             })
@@ -732,6 +738,16 @@ function operationOptions(command,parsed,cwd){
 }
 
 const NATIVE_REQUESTS={
+    'macos-arm64':{
+        platform:'macos',architecture:'arm64',defaultFormat:'app',formats:new Set(['app']),
+        defaultSigning:'unsigned-local-test',defaultProfileId:null,
+        signingModes:new Set(['unsigned-local-test'])
+    },
+    'macos-x64':{
+        platform:'macos',architecture:'x64',defaultFormat:'app',formats:new Set(['app']),
+        defaultSigning:'unsigned-local-test',defaultProfileId:null,
+        signingModes:new Set(['unsigned-local-test'])
+    },
     'windows-x64':{
         platform:'windows',architecture:'x64',defaultFormat:'exe',formats:new Set(['exe']),
         defaultSigning:'unsigned-local-test',defaultProfileId:null,
@@ -755,9 +771,9 @@ const NATIVE_REQUESTS={
 };
 
 function portableRequestDefinition(){
-    const platform=process.platform==='win32'?'windows':process.platform;
+    const platform=process.platform==='win32'?'windows':process.platform==='darwin'?'macos':process.platform;
     const architecture=process.arch==='x64'?'x64':process.arch==='arm64'?'arm64':process.arch;
-    if(!['windows','linux'].includes(platform)||!['x64','arm64'].includes(architecture)){
+    if(!['windows','linux','macos'].includes(platform)||!['x64','arm64'].includes(architecture)){
         throw new ArcaneError(
             ERROR_CODES.targetUnavailable,
             `The portable native provider does not support ${process.platform}/${process.arch}.`
@@ -811,7 +827,7 @@ async function pairNativeProvider(command,options,loadProvider,{signal,onEvent}=
         usage(`${command} requires one native target.`);
     }
     const targetRequest=createNativeTargetRequest(options);
-    if(!options.arcaneRoot&&options.target!=='portable'){
+    if(!options.arcaneRoot&&!['portable','windows-x64','macos-arm64','macos-x64'].includes(options.target)){
         usage(`${command} for target ${options.target} requires --arcane-root <directory>.`);
     }
     const loaded=await loadProvider({

package/src/constants.mjs

@@ -27,6 +27,8 @@ export const TARGET_IDS=[
     'browser',
     'portable',
     'windows-x64',
+    'macos-arm64',
+    'macos-x64',
     'linux-x64',
     'linux-arm64',
     'android-arm64'

package/src/core/host.mjs

@@ -1,6 +1,29 @@
+import {readFile} from 'node:fs/promises';
+import Is from 'strong-type';
 import {createCoreRuntime} from './runtime.mjs';
 import {startCoreStdio} from './stdio.mjs';
 
+const is = new Is(false);
+
+/**
+ * Read only the explicitly supplied --arcane-launch-config filename.
+ * Return the complete JSON object for the service factories' second argument;
+ * field meanings belong to the launch owner and individual services.
+ */
+export async function readCoreLaunchContext({argv = process.argv.slice(2)} = {}) {
+    const flag = argv.indexOf('--arcane-launch-config');
+    if (flag === -1) return {};
+    const filename = argv[flag + 1];
+    if (filename === undefined || filename === '') {
+        throw new TypeError('--arcane-launch-config requires a filename.');
+    }
+    const context = JSON.parse(await readFile(filename, 'utf8'));
+    if (context === null || !is.object(context) || is.array(context)) {
+        throw new TypeError('Core launch configuration must be a JSON object.');
+    }
+    return context;
+}
+
 /** Compose app services with the shared dispatcher and draining transport. */
 export function startCoreHost({application, version, services = [], input, output, onError, signal} = {}) {
     const runtime = createCoreRuntime({application, version, services});

package/src/core/hosts/macos/ArcaneCoreProcess.h

@@ -0,0 +1,85 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@class ArcaneCoreProcess;
+
+typedef NS_ENUM(NSUInteger, ArcaneCoreOutputStream) {
+    ArcaneCoreStandardOutput,
+    ArcaneCoreStandardError
+};
+
+/**
+ * Callbacks run on process-owned background queues. Each output stream retains
+ * its order; different streams, writes and exit observation can be concurrent.
+ * Marshal UI work at the host. Callbacks must return normally and must not wait
+ * for another callback or for completion. The process retains its delegate
+ * through didCompleteWithErrors, then releases it.
+ *
+ * receivedOutputData delivers every unmodified stdout/stderr chunk. Stdout
+ * includes framing; receivedFrameData additionally delivers each complete
+ * opaque JSON body. No payload is decoded, parsed or rewritten here. Following
+ * a framing error, raw stdout continues to EOF without guessing a new boundary.
+ */
+@protocol ArcaneCoreProcessDelegate <NSObject>
+- (void)coreProcess:(ArcaneCoreProcess *)process didLaunch:(pid_t)processIdentifier;
+- (void)coreProcess:(ArcaneCoreProcess *)process receivedFrameData:(NSData *)data;
+- (void)coreProcess:(ArcaneCoreProcess *)process receivedOutputData:(NSData *)data
+            stream:(ArcaneCoreOutputStream)stream;
+- (void)coreProcess:(ArcaneCoreProcess *)process didEncounterError:(NSError *)error;
+- (void)coreProcess:(ArcaneCoreProcess *)process didExitWithStatus:(int)status
+            reason:(NSTaskTerminationReason)reason;
+/**
+ * Last callback: launch/exit observation, accepted writes and both streams have
+ * settled, successfully or with reported errors. Launch failure has no exit
+ * callback; an exit-observation failure is not proof that the child exited.
+ */
+- (void)coreProcess:(ArcaneCoreProcess *)process didCompleteWithErrors:(NSArray<NSError *> *)errors;
+@end
+
+/**
+ * Foundation-only ownership of one explicit Core executable and framed pipes.
+ * Compile with Objective-C ARC and blocks; no third-party runtime is linked.
+ */
+API_AVAILABLE(macos(11.0))
+@interface ArcaneCoreProcess : NSObject
+
+/**
+ * Starts asynchronously without shell execution, PATH lookup, environment
+ * mutation or a foreground wait. Arguments exclude argv[0]; the selected child
+ * inherits the host environment. Launch failure is reported through the
+ * delegate and completion. Callbacks can begin before this method returns.
+ */
++ (instancetype)startExecutableURL:(NSURL *)executableURL
+                        arguments:(NSArray<NSString *> *)arguments
+              workingDirectoryURL:(NSURL *)workingDirectoryURL
+                         delegate:(id<ArcaneCoreProcessDelegate>)delegate;
+
+/** Zero until a successful launch; the original child PID remains after exit. */
+@property(nonatomic, readonly) pid_t processIdentifier;
+
+/**
+ * Copies and queues the complete opaque JSON body. YES accepts the write and
+ * calls completion exactly once on the input queue. nil completion-error means
+ * the full frame reached child stdin, not that Core accepted or completed its
+ * operation. NO supplies a synchronous error and never calls completion.
+ * A partial/failed write is never retried. Payload length is transport framing
+ * only, never an application limit or policy.
+ */
+- (BOOL)sendJSONData:(NSData *)data
+         completion:(void (^)(NSError * _Nullable error))completion
+              error:(NSError * _Nullable * _Nullable)error;
+
+/**
+ * Idempotent and nonblocking: reject new sends, finish accepted writes, then
+ * close stdin. Keep reading stdout/stderr and observe child exit. There is no
+ * forced termination or deadline. Accepted service work can outlive a renderer;
+ * renderer cancellation belongs to the public Core control protocol.
+ */
+- (void)closeInput;
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+@end
+
+NS_ASSUME_NONNULL_END