arcane-os 0.54.1 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.54.1",
+  "version": "0.55.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -48,6 +48,13 @@
     "./targets": "./src/targets/index.mjs",
     "./native": "./src/native-plan.mjs",
     "./native-provider": "./src/native-provider-loader.mjs",
+    "./native/portable-provider": "./src/native/portable-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",
     "./integrated-provider": "./src/integrated-provider-loader.mjs",
     "./packager": "./src/packager/core.mjs",
     "./release-bundle": "./src/release-bundle.mjs",
@@ -89,8 +96,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/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-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-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: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/schemas/native-build-plan.schema.json

@@ -23,6 +23,14 @@
     "toolchainRoot": { "type": "string", "minLength": 1 },
     "toolchain": { "type": "object" },
     "appDescriptor": { "type": "object" },
+    "selectedSdk": {
+      "description": "Actual selected app SDK installation used to complete a partial native package projection without replacing selected files.",
+      "type": "object",
+      "properties": {
+        "packageRoot": { "type": "string" },
+        "packageSource": { "type": "string" }
+      }
+    },
     "application": { "$ref": "#/$defs/releaseSelection" },
     "dependencies": {
       "type": "array",

package/src/cli/main.mjs

@@ -75,8 +75,8 @@ Usage:
   ${CLI_NAME} verify [--app <id>]
   ${CLI_NAME} bundle [--app <id>] [--artifact <file>${APP_BUNDLE_EXTENSION}] [--overwrite]
   ${CLI_NAME} verify-bundle <file${APP_BUNDLE_EXTENSION}>
-  ${CLI_NAME} native-doctor --target <native-target> --arcane-root <directory>
-  ${CLI_NAME} native-prepare --target <native-target> --arcane-root <directory>
+  ${CLI_NAME} native-doctor --target <native-target> [--arcane-root <directory>]
+  ${CLI_NAME} native-prepare --target <native-target> [--arcane-root <directory>]
   ${CLI_NAME} build --target <target> [--arcane-root <directory>] [--output-root <directory>] [--format <format>] [--signing <mode>]
   ${CLI_NAME} run [--target <target>] [--app <id>] [--cert <pem>] [--key <pem>] [--port 8000] [--http-port 0] [--arcane-root <directory>] [--output-root <directory>] [--format <format>] [--signing <mode>]
   ${CLI_NAME} update-check
@@ -105,9 +105,10 @@ Global:
   --version                     Show the SDK version.
 
 The npm package is ${SDK_NAME}. Both the ${CLI_NAME} and arcane-os executables
-invoke this same headless toolchain. Every native operation requires one explicit
---arcane-root. Available providers build portable directories, Windows x64 EXE
-bundles, Linux x64 or ARM64 DEBs, and development-signed Android APKs.`;
+invoke this same headless toolchain. Portable uses the installed SDK provider
+by default and produces a non-executable app payload. An explicit --arcane-root
+selects the Arcane OS provider instead. Windows EXE, Linux DEB, and Android APK
+targets still require an explicit --arcane-root and their platform toolchains.`;
 
 function usage(message){
     throw new ArcaneError(ERROR_CODES.usage,message);
@@ -810,7 +811,7 @@ async function pairNativeProvider(command,options,loadProvider,{signal,onEvent}=
         usage(`${command} requires one native target.`);
     }
     const targetRequest=createNativeTargetRequest(options);
-    if(!options.arcaneRoot){
+    if(!options.arcaneRoot&&options.target!=='portable'){
         usage(`${command} for target ${options.target} requires --arcane-root <directory>.`);
     }
     const loaded=await loadProvider({
@@ -823,6 +824,7 @@ async function pairNativeProvider(command,options,loadProvider,{signal,onEvent}=
         ...options,
         nativeBuilder:loaded.nativeBuilder,
         toolchainRoot:loaded.toolchainRoot,
+        providerSource:loaded.providerSource,
         targetRequest
     };
 }

package/src/core/host.mjs

@@ -0,0 +1,23 @@
+import {createCoreRuntime} from './runtime.mjs';
+import {startCoreStdio} from './stdio.mjs';
+
+/** 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});
+    const host = startCoreStdio({runtime, input, output, onError});
+    if (!signal) return host;
+
+    function closeHostOnAbort() {
+        // The transport owns cancellation, accepted-service work and final output.
+        host.close();
+    }
+
+    function releaseAbortListener() {
+        signal.removeEventListener('abort', closeHostOnAbort);
+    }
+
+    signal.addEventListener('abort', closeHostOnAbort, {once: true});
+    host.closed.then(releaseAbortListener, releaseAbortListener);
+    if (signal.aborted) closeHostOnAbort();
+    return host;
+}

package/src/core/runtime.mjs

@@ -0,0 +1,333 @@
+import Is from 'strong-type';
+import {createArcaneEventSource} from '../event-manager.mjs';
+import {CORE_PROTOCOL, CoreError, serializeCoreError} from '../../browser-runtime/core/contracts.mjs';
+
+const is = new Is(false);
+const STATE_EVENT = 'core.runtime.state';
+const FRAME_EVENT = 'core.runtime.frame';
+
+function failure(code, message) {
+    return new CoreError({code, message});
+}
+
+function requireFunction(value, name) {
+    if (!is.function(value)) throw new TypeError(`${name} must be a function.`);
+}
+
+function aborted(controller) {
+    if (controller.signal.aborted) throw controller.signal.reason;
+}
+
+/** App-neutral dispatch. Hosts own services, privileges and process lifetime. */
+class CoreRuntime {
+    #application;
+    #version;
+    #events;
+    #state = 'created';
+    #services = new Map();
+    #methods = new Map();
+    #requests = new Map();
+    #responses = new Set();
+    #publications = [];
+    #publishing = false;
+    #closing = null;
+
+    constructor({application, version, services = []} = {}) {
+        this.#application = application;
+        this.#version = version;
+        this.#events = createArcaneEventSource(
+            this,
+            {source: 'core-runtime', eventTypes: [STATE_EVENT, FRAME_EVENT]}
+        );
+        for (const service of services) this.registerService(service);
+    }
+
+    current() {
+        return {
+            state: this.#state,
+            application: this.#application,
+            version: this.#version,
+            services: [...this.#services.values()].map(
+                function serviceState(service) {
+                    return {name: service.name, state: service.state, error: service.error};
+                }
+            ),
+            activeRequests: [...this.#requests.values()].map(
+                function requestState(request) {
+                    return {id: request.id, method: request.method, lifetime: request.lifetime};
+                }
+            )
+        };
+    }
+
+    subscribe(listener, {emitCurrent = true, signal} = {}) {
+        requireFunction(listener, 'listener');
+        function deliverState(occurrence) {
+            listener(occurrence.detail);
+        }
+        const unsubscribe = this.#events.on(STATE_EVENT, deliverState, {signal});
+        try {
+            if (emitCurrent && !signal?.aborted) listener(this.current());
+        } catch (error) {
+            unsubscribe();
+            throw error;
+        }
+        return unsubscribe;
+    }
+
+    onFrame(listener, {signal} = {}) {
+        requireFunction(listener, 'listener');
+        function deliverFrame(occurrence) {
+            listener(occurrence.detail);
+        }
+        return this.#events.on(FRAME_EVENT, deliverFrame, {signal});
+    }
+
+    #publish() {
+        this.#publications.push(this.current());
+        if (this.#publishing) return;
+        this.#publishing = true;
+        try {
+            // A synchronous subscriber can change the lifecycle. Finish each
+            // state publication before delivering its reentrant successor.
+            while (this.#publications.length) {
+                const state = this.#publications.shift();
+                this.#events.dispatch(STATE_EVENT, state);
+                this.emit('core.state', state);
+            }
+        } finally {
+            this.#publishing = false;
+        }
+    }
+
+    emit(event, data) {
+        const frame = {protocol: CORE_PROTOCOL, type: 'event', event, data, time: new Date().toISOString()};
+        this.#events.dispatch(FRAME_EVENT, frame);
+        return frame;
+    }
+
+    registerService(definition) {
+        if (this.#closing) throw failure('CORE_CLOSING', 'Core is closing.');
+        const {name, methods = {}, start, drain, dispose} = definition;
+        if (!is.string(name) || !name) throw new TypeError('Service name must be a nonempty string.');
+        if (this.#services.has(name)) throw failure('CORE_SERVICE_EXISTS', `Service ${name} is already registered.`);
+        for (const [hook, value] of Object.entries({start, drain, dispose})) {
+            if (value !== undefined) requireFunction(value, `Service ${hook}`);
+        }
+        const registrations = [];
+        for (const [method, value] of Object.entries(methods)) {
+            if (this.#methods.has(method) || ['system.ping', 'app.current', 'version.current'].includes(method)) {
+                throw failure('CORE_METHOD_EXISTS', `Method ${method} is already registered.`);
+            }
+            const handle = is.function(value) ? value : value.handle;
+            const lifetime = is.function(value) ? 'request' : value.lifetime ?? 'request';
+            requireFunction(handle, `Method ${method}`);
+            if (lifetime !== 'request' && lifetime !== 'service') {
+                throw new TypeError('Method lifetime must be request or service.');
+            }
+            registrations.push({method, handle, lifetime});
+        }
+        const service = {name, definition, state: 'registered', error: null, task: null};
+        this.#services.set(name, service);
+        for (const registration of registrations) this.#methods.set(registration.method, {...registration, service});
+        if (this.#state === 'ready') this.#startService(service);
+        const runtime = this;
+        return {
+            get ready() {
+                return runtime.#startService(service);
+            },
+            current() {
+                return {name: service.name, state: service.state, error: service.error};
+            }
+        };
+    }
+
+    #serviceContext(service) {
+        const runtime = this;
+        return {
+            application: this.#application,
+            service: service.name,
+            emit(event, data) {
+                return runtime.emit(event, data);
+            }
+        };
+    }
+
+    #serviceState(service, state, error) {
+        service.state = state;
+        service.error = state === 'failed' || (error !== undefined && error !== null)
+            ? serializeCoreError(error)
+            : null;
+        this.emit('core.service.state', {name: service.name, state, error: service.error});
+        this.#publish();
+    }
+
+    #startService(service) {
+        if (service.task) return service.task;
+        if (this.#closing) return Promise.reject(failure('CORE_CLOSING', 'Core is closing.'));
+        const runtime = this;
+        // Publish after task assignment so a synchronous state subscriber cannot
+        // start the same service twice.
+        service.task = Promise.resolve().then(
+            async function initializeService() {
+                runtime.#serviceState(service, 'starting');
+                try {
+                    await service.definition.start?.(runtime.#serviceContext(service));
+                    runtime.#serviceState(service, 'ready');
+                } catch (error) {
+                    runtime.#serviceState(service, 'failed', error);
+                    throw error;
+                }
+            }
+        );
+        service.task.catch(function observeServiceStartupFailure() {});
+        return service.task;
+    }
+
+    start() {
+        if (this.#closing) throw failure('CORE_CLOSING', 'Core is closing.');
+        if (this.#state === 'ready') return this.current();
+        this.#state = 'ready';
+        for (const service of this.#services.values()) this.#startService(service);
+        this.emit('core.ready', {version: this.#version, app: this.#application});
+        this.#publish();
+        return this.current();
+    }
+
+    async handle(frame) {
+        if (frame?.protocol !== CORE_PROTOCOL) throw failure('INVALID_RPC_REQUEST', 'Unknown Core protocol.');
+        if (frame.type === 'control') {
+            if (frame.control === 'request.cancel') return this.#cancel(frame.requestId);
+            if (frame.control === 'requests.cancelAll') {
+                for (const request of this.#requests.values()) this.#cancel(request.id);
+                return;
+            }
+            throw failure('INVALID_RPC_CONTROL', 'Unknown Core control.');
+        }
+        if (frame.type !== 'request' || !is.string(frame.id) || !frame.id || !is.string(frame.method)) {
+            throw failure('INVALID_RPC_REQUEST', 'A Core request requires an id and method.');
+        }
+        const task = this.#answer(frame);
+        this.#responses.add(task);
+        try {
+            return await task;
+        } finally {
+            this.#responses.delete(task);
+        }
+    }
+
+    async #answer(frame) {
+        let result;
+        let error;
+        let ok = true;
+        try {
+            if (this.#state !== 'ready') throw failure('CORE_NOT_READY', 'Core is not accepting requests.');
+            if (this.#requests.has(frame.id)) throw failure('RPC_REQUEST_ID_ACTIVE', 'The request id is already active.');
+            if (frame.method === 'system.ping') result = {ok: true};
+            else if (frame.method === 'version.current') result = this.#version;
+            else if (frame.method === 'app.current') result = this.#application;
+            else result = await this.#request(frame);
+        } catch (caught) {
+            ok = false;
+            error = caught;
+        }
+        const response = {
+            protocol: CORE_PROTOCOL,
+            type: 'response',
+            id: frame.id,
+            ...(ok ? {ok: true, result} : {ok: false, error: serializeCoreError(error)}),
+            time: new Date().toISOString()
+        };
+        this.#events.dispatch(FRAME_EVENT, response);
+        return response;
+    }
+
+    #request(frame) {
+        const registration = this.#methods.get(frame.method);
+        if (!registration) throw failure('METHOD_NOT_ALLOWED', `Core does not expose ${frame.method}.`);
+        const {service, handle, lifetime} = registration;
+        const controller = new AbortController();
+        const request = {id: frame.id, method: frame.method, lifetime, controller, task: null};
+        const runtime = this;
+        this.#requests.set(frame.id, request);
+        request.task = Promise.resolve().then(
+            async function executeCoreRequest() {
+                try {
+                    await runtime.#startService(service);
+                    aborted(controller);
+                    const result = await handle.call(
+                        service.definition,
+                        frame.parameters,
+                        {...runtime.#serviceContext(service), requestId: frame.id, signal: controller.signal}
+                    );
+                    aborted(controller);
+                    return result;
+                } finally {
+                    if (runtime.#requests.get(frame.id) === request) runtime.#requests.delete(frame.id);
+                    runtime.#publish();
+                }
+            }
+        );
+        this.#publish();
+        return request.task;
+    }
+
+    #cancel(id) {
+        const request = this.#requests.get(id);
+        if (!request || request.lifetime === 'service' || request.controller.signal.aborted) return false;
+        const error = failure('REQUEST_ABORTED', 'The Core request was cancelled.');
+        error.name = 'AbortError';
+        request.controller.abort(error);
+        return true;
+    }
+
+    close() {
+        if (this.#closing) return this.#closing;
+        this.#state = 'draining';
+        const runtime = this;
+        // A synchronous state listener may call close again. Retain the owner
+        // before announcing draining, and never let a renderer cancel saves.
+        this.#closing = Promise.resolve().then(
+            async function drainCoreRuntime() {
+                const failures = [];
+                for (const request of runtime.#requests.values()) runtime.#cancel(request.id);
+                await Promise.allSettled([...runtime.#responses]);
+                await Promise.all(
+                    [...runtime.#services.values()].map(
+                        async function closeCoreService(service) {
+                            const serviceFailures = [];
+                            if (service.task) {
+                                try { await service.task; } catch (error) { serviceFailures.push(error); }
+                            }
+                            runtime.#serviceState(service, 'draining');
+                            for (const hook of ['drain', 'dispose']) {
+                                try {
+                                    await service.definition[hook]?.(runtime.#serviceContext(service));
+                                } catch (error) {
+                                    serviceFailures.push(error);
+                                    runtime.emit('core.error', serializeCoreError(error));
+                                }
+                            }
+                            const error = serviceFailures.length
+                                ? new AggregateError(serviceFailures, `Service ${service.name} shutdown failed.`)
+                                : null;
+                            failures.push(...serviceFailures);
+                            runtime.#serviceState(service, 'closed', error);
+                        }
+                    )
+                );
+                runtime.#state = 'closed';
+                runtime.#publish();
+                runtime.#events.dispose();
+                if (failures.length) throw new AggregateError(failures, 'Core service shutdown failed.');
+                return runtime.current();
+            }
+        );
+        this.#publish();
+        return this.#closing;
+    }
+}
+
+export function createCoreRuntime(options) {
+    return new CoreRuntime(options);
+}

package/src/core/stdio.mjs

@@ -0,0 +1,209 @@
+import {finished} from 'node:stream';
+import Is from 'strong-type';
+import {CoreError, serializeCoreError} from '../../browser-runtime/core/contracts.mjs';
+
+const is = new Is(false);
+
+/** Content-Length is used only for the existing native transport framing. */
+export function encodeCoreFrame(frame) {
+    const body = Buffer.from(JSON.stringify(frame), 'utf8');
+    return Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii'), body]);
+}
+
+export function createCoreFrameDecoder(onFrame) {
+    let header = Buffer.alloc(0);
+    let remaining = null;
+    let parts = [];
+    const utf8 = new TextDecoder('utf-8', {fatal: true});
+
+    function push(chunk) {
+        let input = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        while (input.length || remaining === 0) {
+            if (remaining === null) {
+                header = Buffer.concat([header, input]);
+                const marker = header.indexOf('\r\n\r\n');
+                if (marker < 0) return;
+                const match = header.subarray(0, marker).toString('ascii').match(
+                    /(?:^|\r\n)Content-Length:\s*(\d+)(?:\r\n|$)/i
+                );
+                if (!match) throw new CoreError({code: 'IPC_LENGTH_MISSING', message: 'IPC content length is missing.'});
+                remaining = Number(match[1]);
+                if (!is.safeInteger(remaining) || remaining < 0) {
+                    throw new CoreError({code: 'IPC_LENGTH_INVALID', message: 'IPC content length is invalid.'});
+                }
+                input = header.subarray(marker + 4);
+                header = Buffer.alloc(0);
+            }
+            const consumed = Math.min(remaining, input.length);
+            if (consumed) parts.push(input.subarray(0, consumed));
+            input = input.subarray(consumed);
+            remaining -= consumed;
+            if (remaining > 0) return;
+            const body = Buffer.concat(parts);
+            parts = [];
+            remaining = null;
+            onFrame(JSON.parse(utf8.decode(body)));
+        }
+    }
+
+    function finish() {
+        if (header.length || remaining !== null) {
+            throw new CoreError({code: 'IPC_FRAME_INCOMPLETE', message: 'IPC ended during a frame.'});
+        }
+    }
+
+    return {push, finish};
+}
+
+function reportStdioError(error) {
+    console.error('Arcane Core transport failed:', error);
+}
+
+/** Attach an existing runtime; EOF drains accepted service work, never exits. */
+export function startCoreStdio({runtime, input = process.stdin, output = process.stdout, onError = reportStdioError}) {
+    let closing = null;
+    let writes = Promise.resolve();
+    let outputFailed = false;
+    let inputCompleted = false;
+    let resolveInputCompletion;
+    const inputCompletion = new Promise(function observeInputCompletion(resolve) {
+        resolveInputCompletion = resolve;
+    });
+    const pending = new Set();
+    const failures = [];
+    let resolveClosed;
+    let rejectClosed;
+    const closed = new Promise(
+        function createClosedPromise(resolve, reject) {
+            resolveClosed = resolve;
+            rejectClosed = reject;
+        }
+    );
+    // Every background error is reported to onError and retained by closed.
+    closed.catch(function observeReportedTransportFailure() {});
+
+    function report(error) {
+        if (failures.includes(error)) return;
+        failures.push(error);
+        try { onError(error); } catch (reportError) { failures.push(reportError); }
+    }
+
+    function failOutput(error) {
+        outputFailed = true;
+        report(error);
+        close();
+    }
+
+    function queueFrame(frame) {
+        if (outputFailed) return;
+        let encoded;
+        try { encoded = encodeCoreFrame(frame); } catch (error) { failOutput(error); return; }
+        writes = writes.then(
+            function writeNextFrame() {
+                if (outputFailed) return;
+                return new Promise(
+                    function writeFrame(resolve, reject) {
+                        output.write(
+                            encoded,
+                            function frameWritten(error) {
+                                if (error) reject(error);
+                                else resolve();
+                            }
+                        );
+                    }
+                );
+            }
+        ).catch(failOutput);
+    }
+
+    const unsubscribe = runtime.onFrame(queueFrame);
+
+    function receiveFrame(frame) {
+        const task = runtime.handle(frame);
+        pending.add(task);
+        task.then(
+            function requestSettled() {
+                pending.delete(task);
+            },
+            function requestFailed(error) {
+                pending.delete(task);
+                report(error);
+                try { runtime.emit('core.error', serializeCoreError(error)); } catch (eventError) { report(eventError); }
+            }
+        );
+    }
+
+    const decoder = createCoreFrameDecoder(receiveFrame);
+
+    function receiveInput(chunk) {
+        try { decoder.push(chunk); } catch (error) { report(error); close(); }
+    }
+
+    function inputEnded() {
+        try { decoder.finish(); } catch (error) { report(error); }
+        close();
+    }
+
+    function inputFailed(error) {
+        report(error);
+        close();
+    }
+
+    function detachInput() {
+        input.off('data', receiveInput);
+        input.off('end', inputEnded);
+        input.off('close', inputEnded);
+        input.pause();
+    }
+
+    async function releaseTransportListeners() {
+        unsubscribe();
+        output.off('error', failOutput);
+        // destroy(error) marks a stream destroyed before its scheduled error
+        // and close events. The native completion owner observes their delivery;
+        // stream flags alone do not establish that pending errors were observed.
+        if (input.destroyed && !inputCompleted) await inputCompletion;
+        cleanupInputCompletion();
+        input.off('error', inputFailed);
+    }
+
+    function close() {
+        if (closing) return closed;
+        detachInput();
+        closing = Promise.resolve().then(
+            async function drainTransport() {
+                try { await runtime.close(); } catch (error) { report(error); }
+                await Promise.allSettled([...pending]);
+                await writes;
+                await releaseTransportListeners();
+                if (failures.length) rejectClosed(new AggregateError(failures, 'Core transport closed with errors.'));
+                else resolveClosed(runtime.current());
+            }
+        );
+        closing.catch(
+            async function shutdownFailed(error) {
+                report(error);
+                await releaseTransportListeners();
+                rejectClosed(new AggregateError(failures, 'Core transport shutdown failed.'));
+            }
+        );
+        return closed;
+    }
+
+    const cleanupInputCompletion = finished(input, {readable: true, writable: false}, function inputLifecycleComplete() {
+        inputCompleted = true;
+        resolveInputCompletion();
+    });
+    input.on('data', receiveInput);
+    input.on('end', inputEnded);
+    input.on('close', inputEnded);
+    input.on('error', inputFailed);
+    output.on('error', failOutput);
+    try { runtime.start(); } catch (error) { report(error); close(); }
+    if (!closing) {
+        if (input.errored) report(input.errored);
+        if (input.readableEnded || input.destroyed) inputEnded();
+        else input.resume();
+    }
+    return {runtime, closed, close};
+}