arcane-os 0.54.1 → 0.55.0

package/src/core-classic-source.mjs

@@ -0,0 +1,43 @@
+import {readFile} from 'node:fs/promises';
+
+/**
+ * Generate the native host's classic script from the canonical ESM client.
+ * The two owned modules have declaration exports and two explicit imports;
+ * this projection is deliberately not a general JavaScript bundler.
+ */
+export async function createCoreClassicSource({eventOwnerModuleURL}={}){
+    if(typeof eventOwnerModuleURL!=='string'||!eventOwnerModuleURL){
+        throw new TypeError('The classic Core client needs the served SDK event-manager module URL.');
+    }
+    const [contracts,client]=await Promise.all([
+        readFile(new URL('../browser-runtime/core/contracts.mjs',import.meta.url),'utf8'),
+        readFile(new URL('../browser-runtime/core/client.mjs',import.meta.url),'utf8')
+    ]);
+    const declarations=contracts.replace(/^export (?=(?:const|class|function) )/gmu,'');
+    const implementation=client
+        .replace("import {arcaneEvents} from '../event-manager.mjs';",'')
+        .replace("import {CORE_PROTOCOL,CORE_READY_EVENTS,CoreError,serializeCoreError} from './contracts.mjs';",'')
+        .replace(/^export (?=function )/gmu,'');
+    return `(function installArcaneCoreClassic(global){
+    'use strict';
+    const arcaneEvents=global.arcaneEvents??null;
+${declarations}
+${implementation}
+    if(global[CORE_CLIENT_KEY])return;
+    function loadSharedEventOwner(){
+        return import(${JSON.stringify(eventOwnerModuleURL)}).then(function sharedEventOwner(namespace){return namespace.arcaneEvents;});
+    }
+    // Document-created native injection precedes the page's managed import map.
+    // Only the module import waits for parsing; facade/RPC setup below is immediate.
+    const eventOwnerReady=arcaneEvents?Promise.resolve(arcaneEvents)
+        :global.document?.readyState==='loading'
+            ?new Promise(function afterImportMap(resolve,reject){
+                global.document.addEventListener('DOMContentLoaded',function connectSharedEvents(){
+                    loadSharedEventOwner().then(resolve,reject);
+                },{once:true});
+            })
+            :loadSharedEventOwner();
+    installCoreClient(global,{eventOwner:arcaneEvents,eventOwnerReady});
+})(globalThis);
+`;
+}

package/src/import-map.mjs

@@ -42,6 +42,8 @@ const STATIC_RUNTIME_PACKAGE_IMPORTS=new Map([
 const SDK_BROWSER_SELF_IMPORTS=new Map([
     ['arcane-os/event-manager',SDK_BROWSER_ENTRY],
     ['arcane-os/websocket-client','sdk/websocket-client.mjs'],
+    ['arcane-os/core/client','sdk/core/client.mjs'],
+    ['arcane-os/core/contracts','sdk/core/contracts.mjs'],
     ['arcane-os/logging','sdk/logging.mjs'],
     ['arcane-os/browser-device','sdk/browser-device.mjs'],
     ['arcane-os/pwa','sdk/pwa.mjs'],
@@ -2087,6 +2089,66 @@ function scanHtmlStructure(html){
     return {scripts,links,bases,metas,elements,styles,headClose,bodyClose};
 }
 
+/** Remove generated PWA references from a selected output document without changing authored content. */
+export function removePwaEntryReferences(html, {documentUrl, manifestUrl} = {}) {
+    if (!is.string(html)) throw new TypeError('PWA entry HTML must be a string.');
+    const structure = scanHtmlStructure(html);
+    const manifest = new URL(manifestUrl, documentUrl);
+    const base = structure.bases.find(
+        function baseWithHref(element) {
+            return parseTagAttributes(element.open).has('href');
+        }
+    );
+    const baseHref = base ? structuralAttribute(parseTagAttributes(base.open), 'href', 'base') : null;
+    const resourceBase = baseHref ? new URL(baseHref, documentUrl) : documentUrl;
+    const edits = [];
+    for (const link of structure.links) {
+        const attributes = parseTagAttributes(link.open);
+        const href = htmlAttributeView(attributes.get('href') ?? '');
+        const rel = htmlAttributeView(attributes.get('rel') ?? '');
+        if (!href?.decoded || !rel) continue;
+        let target;
+        try {
+            target = new URL(href.decoded, resourceBase);
+        } catch (error) {
+            // An unrelated non-URL reference stays under its authored owner.
+            continue;
+        }
+        if (target.origin !== manifest.origin || target.pathname !== manifest.pathname) continue;
+        const tokens = [...rel.decoded.matchAll(/[^\t\n\f\r ]+/gu)];
+        const manifestTokens = tokens.filter(
+            function manifestRelationship(token) {
+                return asciiLower(token[0]) === 'manifest';
+            }
+        );
+        if (manifestTokens.length === 0) continue;
+        if (manifestTokens.length === tokens.length) {
+            edits.push(
+                {start: link.start, end: link.end, value: ''}
+            );
+            continue;
+        }
+        const position = attributes.positions.get('rel');
+        for (const token of manifestTokens) {
+            edits.push(
+                {
+                    start: link.start + position.start + rel.positions[token.index],
+                    end: link.start + position.start + rel.positions[token.index + token[0].length],
+                    value: ''
+                }
+            );
+        }
+    }
+    for (const script of structure.scripts) {
+        if (parseTagAttributes(script.open).has('data-arcane-pwa')) {
+            edits.push(
+                {start: script.start, end: script.end, value: ''}
+            );
+        }
+    }
+    return applyReferenceEdits(html, edits);
+}
+
 /** Update only active PWA entry references; registration never orders application startup. */
 export function applyPwaEntryReferences(html,{manifestUrl,bootstrapUrl}={}){
     if(!is.string(html))throw new TypeError('PWA entry HTML must be a string.');

package/src/native/portable-layout.mjs

@@ -0,0 +1,184 @@
+import {mkdir, readFile, readdir, realpath, stat, writeFile} from 'node:fs/promises';
+import {createRequire} from 'node:module';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import Is from 'strong-type';
+import {ArcaneError, ERROR_CODES, throwIfAborted} from '../errors.mjs';
+
+const is = new Is(false);
+export const SDK_ROOT = fileURLToPath(new URL('../../', import.meta.url));
+export const CORE_FILES = [
+    'src/core/host.mjs',
+    'src/core/runtime.mjs',
+    'src/core/stdio.mjs',
+    'src/event-manager.mjs',
+    'src/dom-event-instrumentation.mjs',
+    'browser-runtime/core/contracts.mjs',
+    'LICENSE'
+];
+
+export function outputFile(root, relative) {
+    if (!is.string(relative) || !relative || path.isAbsolute(relative)) {
+        throw new ArcaneError(ERROR_CODES.usage, 'A selected output file needs a relative path.');
+    }
+    const destination = path.resolve(root, relative);
+    const within = path.relative(root, destination);
+    if (!within || within === '..' || within.startsWith(`..${path.sep}`) || path.isAbsolute(within)) {
+        throw new ArcaneError(ERROR_CODES.usage, `The selected file leaves its output directory: ${relative}.`);
+    }
+    return destination;
+}
+
+export async function writeOutput(root, relative, content, files, signal) {
+    throwIfAborted(signal);
+    const destination = outputFile(root, relative);
+    await mkdir(path.dirname(destination), {recursive: true});
+    await writeFile(destination, content, {flag: 'wx', signal});
+    files.push(relative.split(path.sep).join('/'));
+}
+
+export async function copyRelease(selection, destination, root, files, signal) {
+    for (const relative of selection.release.files) {
+        throwIfAborted(signal);
+        // The supplied reader owns release selection. No text decoding, URL
+        // rewriting or line-ending conversion occurs at native assembly.
+        const content = is.function(selection.readReleaseFile)
+            ? await selection.readReleaseFile(relative, {signal})
+            : await readFile(outputFile(selection.releaseRoot, relative), {signal});
+        outputFile(path.join(root, destination), relative);
+        await writeOutput(root, `${destination}/${relative}`, content, files, signal);
+    }
+}
+
+async function copyPackageTree(source, relative, root, files, signal, preserved) {
+    throwIfAborted(signal);
+    const sourceRoot = await realpath(source);
+    const outputRelative = path.relative(sourceRoot, root);
+    if (!outputRelative || (!path.isAbsolute(outputRelative)
+        && outputRelative !== '..' && !outputRelative.startsWith(`..${path.sep}`))) {
+        throw new ArcaneError(ERROR_CODES.usage, `Native output would copy itself from ${sourceRoot}.`);
+    }
+    const entries = await readdir(source, {withFileTypes: true});
+    for (const entry of entries) {
+        throwIfAborted(signal);
+        const selected = path.join(source, entry.name);
+        const destination = `${relative}/${entry.name}`;
+        if (preserved.has(destination)) continue;
+        const info = await stat(selected);
+        if (info.isDirectory()) {
+            await copyPackageTree(selected, destination, root, files, signal, preserved);
+        } else if (info.isFile()) {
+            await writeOutput(root, destination, await readFile(selected, {signal}), files, signal);
+        } else {
+            throw new ArcaneError(ERROR_CODES.operationFailed, `Cannot copy the runtime package entry: ${selected}.`);
+        }
+    }
+}
+
+export async function copyCoreRuntime(root, files, signal, {
+    sourceRoot = SDK_ROOT, sdkDestination = 'node_modules/arcane-os'
+} = {}) {
+    const metadata = JSON.parse(await readFile(path.join(sourceRoot, 'package.json'), 'utf8'));
+    // A direct browser projection may already occupy this package directory.
+    // Complete it from its selected installed package without replacing content.
+    const preserved = new Set(files);
+    for (const directory of ['bin', 'src', 'browser-runtime', 'runtime', 'schemas']) {
+        await copyPackageTree(path.join(sourceRoot, directory), `${sdkDestination}/${directory}`, root, files, signal, preserved);
+    }
+    for (const relative of ['package.json', 'LICENSE', 'COMMERCIAL-LICENSE.md', 'NOTICE', 'README.md', 'CHANGELOG.md']) {
+        const destination = `${sdkDestination}/${relative}`;
+        if (!preserved.has(destination)) {
+            await writeOutput(root, destination, await readFile(path.join(sourceRoot, relative), {signal}), files, signal);
+        }
+    }
+
+    // Preserve each dependency's actual installed runtime resolution, including
+    // nested versions. Packaging reads published files; it executes no package.
+    const copied = new Map([[sdkDestination, await realpath(sourceRoot)]]);
+    async function includeDependency(name, from, parentDestination) {
+        throwIfAborted(signal);
+        const require = createRequire(path.join(from, 'package.json'));
+        let packageFile;
+        try {
+            packageFile = require.resolve(`${name}/package.json`);
+        } catch (error) {
+            if (error.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') throw error;
+            let directory = path.dirname(require.resolve(name));
+            for (;;) {
+                const candidate = path.join(directory, 'package.json');
+                try {
+                    const record = JSON.parse(await readFile(candidate, 'utf8'));
+                    if (record.name === name) { packageFile = candidate; break; }
+                } catch (failure) {
+                    if (failure.code !== 'ENOENT') throw failure;
+                }
+                const parent = path.dirname(directory);
+                if (parent === directory) throw error;
+                directory = parent;
+            }
+        }
+        const source = await realpath(path.dirname(packageFile));
+        // Reuse only a resolved ancestor package that Node can actually reach.
+        // This also terminates ordinary circular package dependencies.
+        let ancestor = parentDestination;
+        for (;;) {
+            const candidate = path.posix.join(ancestor, 'node_modules', name);
+            if (copied.has(candidate)) {
+                if (copied.get(candidate) === source) return;
+                break;
+            }
+            try { await stat(outputFile(root, `${candidate}/package.json`)); break; }
+            catch (error) { if (error.code !== 'ENOENT') throw error; }
+            if (ancestor === '.') break;
+            ancestor = path.posix.dirname(ancestor);
+        }
+        const destination = `${parentDestination}/node_modules/${name}`;
+        const record = JSON.parse(await readFile(packageFile, 'utf8'));
+        let included = false;
+        try { await stat(outputFile(root, `${destination}/package.json`)); included = true; }
+        catch (error) { if (error.code !== 'ENOENT') throw error; }
+        if (!included) await copyPackageTree(source, destination, root, files, signal, preserved);
+        copied.set(destination, source);
+        for (const dependency of Object.keys(record.dependencies ?? {})) {
+            await includeDependency(dependency, source, destination);
+        }
+    }
+    for (const dependency of Object.keys(metadata.dependencies ?? {})) {
+        await includeDependency(dependency, sourceRoot, sdkDestination);
+    }
+    return metadata;
+}
+
+export function coreEntrySource(application, version, services) {
+    const imports = services.map(function serviceImport(service, index) {
+        const specifier = '../app/' + service.module.split('/').map(encodeURIComponent).join('/');
+        return `import createService${index} from ${JSON.stringify(specifier)};`;
+    });
+    const definitions = services.map(function serviceDefinition(service, index) {
+        return `    createService${index}(${JSON.stringify(service.options === undefined ? {} : service.options)})`;
+    });
+    return [
+        "import {startCoreHost} from 'arcane-os/core/host';",
+        ...imports,
+        '',
+        'const host = startCoreHost({',
+        `    application: ${JSON.stringify(application)},`,
+        `    version: ${JSON.stringify(version)},`,
+        `    services: [\n${definitions.join(',\n')}\n    ]`,
+        '});',
+        '',
+        'function closeCore() { host.close(); }',
+        "process.on('SIGINT', closeCore);",
+        "process.on('SIGTERM', closeCore);",
+        'try {',
+        '    await host.closed;',
+        '} catch (error) {',
+        "    console.error('Arcane Core host failed:', error);",
+        '    process.exitCode = 1;',
+        '} finally {',
+        "    process.off('SIGINT', closeCore);",
+        "    process.off('SIGTERM', closeCore);",
+        '}',
+        ''
+    ].join('\n');
+}

package/src/native/portable-provider.mjs

@@ -0,0 +1,211 @@
+import {mkdir, mkdtemp, readFile, realpath, rm, stat} from 'node:fs/promises';
+import path from 'node:path';
+import Is from 'strong-type';
+import {createCoreClassicSource} from '../core-classic-source.mjs';
+import {ArcaneError, ERROR_CODES, throwIfAborted} from '../errors.mjs';
+import {SDK_ROOT, CORE_FILES, outputFile, writeOutput, copyRelease, copyCoreRuntime, coreEntrySource} from './portable-layout.mjs';
+
+const is = new Is(false);
+const PROTOCOL = 'arcane-native-builder/1';
+const MANIFEST = 'arcane-native.json';
+
+function portableTarget(value) {
+    if (value?.target !== 'portable') {
+        throw new ArcaneError(ERROR_CODES.targetUnavailable, 'This provider assembles portable Core payloads only.');
+    }
+    return {...value};
+}
+
+async function emit(onEvent, event) {
+    if (is.function(onEvent)) await onEvent(event);
+}
+
+function contains(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
+}
+
+async function futureRealPath(location) {
+    try { return await realpath(location); }
+    catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+        const parent = path.dirname(location);
+        if (parent === location) throw error;
+        return path.join(await futureRealPath(parent), path.basename(location));
+    }
+}
+
+async function outputDirectory(request) {
+    if (!is.string(request.outputRoot) || !request.outputRoot) {
+        throw new ArcaneError(ERROR_CODES.usage, 'Portable assembly requires an outputRoot.');
+    }
+    const output = await futureRealPath(path.resolve(request.outputRoot));
+    const protectedRoots = [SDK_ROOT, request.appReleaseRoot,
+        ...(request.dependencies?.map(function dependencyRoot(item) { return item.releaseRoot; }) ?? []),
+        ...(request.protectedRoots ?? [])];
+    for (const location of protectedRoots) {
+        if (!location) continue;
+        const root = await futureRealPath(path.resolve(location));
+        // SDK/release roots must never be replaced by generated output. A
+        // caller may select its ordinary project-local dist descendant.
+        if (contains(output, root) || (location !== SDK_ROOT && contains(root, output))) {
+            throw new ArcaneError(ERROR_CODES.usage, `Portable output overlaps selected source: ${location}.`);
+        }
+    }
+    await mkdir(output, {recursive: true});
+    return output;
+}
+
+function serviceSelection(services, release) {
+    return services.map(function selectService(service) {
+        if (!is.string(service?.module) || !release.files.includes(service.module)) {
+            throw new ArcaneError(ERROR_CODES.prerequisiteMissing, `The selected release does not contain service module ${String(service?.module)}.`);
+        }
+        return {module: service.module, options: service.options === undefined ? {} : service.options};
+    });
+}
+
+function eventOwnerPath(release) {
+    const paths = release.files.filter(function sdkEventModule(relative) {
+        return relative === 'sdk/event-manager.mjs' || relative.endsWith('/sdk/event-manager.mjs')
+            || /^node_modules\/(?:@[^/]+\/)?[^/]+\/browser-runtime\/event-manager\.mjs$/u.test(relative);
+    });
+    if (paths.length !== 1) {
+        throw new ArcaneError(ERROR_CODES.prerequisiteMissing,
+            'The portable app release must select one shared SDK event-manager module.',
+            {details: {paths}});
+    }
+    // Native hosts mount the complete app directory at one local URL origin.
+    // An origin-root URL keeps nested navigable documents on the same owner.
+    return '/' + paths[0].split('/').map(encodeURIComponent).join('/');
+}
+
+/** Package-owned assembly; never imports an OS checkout or application service. */
+export function createPortableNativeProvider({services = []} = {}) {
+    return {
+        protocol: PROTOCOL,
+        async describe() {
+            return {
+                protocol: PROTOCOL,
+                id: 'arcane-sdk-portable',
+                targets: ['portable'],
+                executable: false,
+                serviceConfiguration: 'explicit release module factories'
+            };
+        },
+        async doctor({targetRequest, signal, onEvent} = {}) {
+            throwIfAborted(signal);
+            portableTarget(targetRequest);
+            const missing = [];
+            for (const relative of CORE_FILES) {
+                try { await stat(path.join(SDK_ROOT, relative)); }
+                catch (error) {
+                    if (error.code !== 'ENOENT') throw error;
+                    missing.push(relative);
+                }
+            }
+            const result = {ready: missing.length === 0, target: 'portable', sdkRoot: SDK_ROOT, missing, executable: false};
+            await emit(onEvent, {type: 'native.doctor.completed', ...result});
+            return result;
+        },
+        async prepare({targetRequest, signal, onEvent} = {}) {
+            throwIfAborted(signal);
+            const target = portableTarget(targetRequest);
+            const metadata = JSON.parse(await readFile(path.join(SDK_ROOT, 'package.json'), 'utf8'));
+            const result = {sdkRoot: SDK_ROOT, sdkVersion: metadata.version, target, executable: false};
+            await emit(onEvent, {type: 'native.prepared', target: 'portable', sdkVersion: metadata.version});
+            return result;
+        },
+        async build(request = {}) {
+            const {appDescriptor, release, signal, onEvent} = request;
+            throwIfAborted(signal);
+            const target = portableTarget(request.targetRequest);
+            const selectedServices = serviceSelection(services, release);
+            const eventOwnerModuleURL = eventOwnerPath(release);
+            const output = await outputDirectory(request);
+            throwIfAborted(signal);
+            // Unique assembly directories preserve earlier outputs and avoid
+            // overwriting an app's files or a concurrent packaging operation.
+            const root = await mkdtemp(path.join(output, 'arcane-portable-'));
+            const files = [];
+            try {
+                await emit(onEvent, {type: 'native.payload.started', appId: appDescriptor.id, outputRoot: root});
+                await copyRelease({...request, releaseRoot: request.appReleaseRoot}, 'app', root, files, signal);
+                const dependencies = [];
+                for (const [index, dependency] of (request.dependencies ?? []).entries()) {
+                    const directory = `dependencies/${index}`;
+                    await copyRelease(dependency, directory, root, files, signal);
+                    dependencies.push({appId: dependency.appId, root: directory, release: dependency.release});
+                }
+                const sdk = await copyCoreRuntime(root, files, signal);
+                const selectedSdk = request.selectedSdk;
+                let appSdk;
+                if (selectedSdk && release.files.some(function selectedPackageFile(relative) {
+                    return relative.startsWith(`${selectedSdk.packageSource}/`);
+                })) {
+                    const destination = `app/${selectedSdk.packageSource}`;
+                    let metadata;
+                    if (release.files.includes(`${selectedSdk.packageSource}/package.json`)) {
+                        metadata = JSON.parse(await readFile(outputFile(root, `${destination}/package.json`), 'utf8'));
+                    } else {
+                        metadata = await copyCoreRuntime(root, files, signal, {
+                            sourceRoot: selectedSdk.packageRoot, sdkDestination: destination
+                        });
+                    }
+                    appSdk = {name: metadata.name, version: metadata.version, root: destination};
+                }
+                await writeOutput(root, 'package.json', '{"type":"module"}\n', files, signal);
+                await writeOutput(root, 'runtime/arcane-core.mjs', coreEntrySource(appDescriptor, sdk.version, selectedServices), files, signal);
+                await writeOutput(root, 'runtime/arcane-api.js', await createCoreClassicSource({eventOwnerModuleURL}), files, signal);
+                const manifest = {
+                    schemaVersion: 1,
+                    kind: 'arcane-portable-native',
+                    sdk: {name: sdk.name, version: sdk.version},
+                    ...(appSdk ? {appSdk} : {}),
+                    app: appDescriptor,
+                    target,
+                    webRoot: 'app',
+                    start: release.manifest?.app?.start ?? './index.html',
+                    core: {entry: 'runtime/arcane-core.mjs', transport: 'stdio', protocol: 'arcane/1', services: selectedServices},
+                    client: {source: 'runtime/arcane-api.js', injection: 'document-created', eventOwnerModuleURL},
+                    dependencies,
+                    minimumCoreVersion: request.minimumCoreVersion ?? null,
+                    files: [...files, MANIFEST]
+                };
+                await writeOutput(root, MANIFEST, JSON.stringify(manifest, null, 2) + '\n', files, signal);
+                throwIfAborted(signal);
+                await emit(onEvent, {type: 'native.payload.completed', appId: appDescriptor.id, outputRoot: root});
+                throwIfAborted(signal);
+                return {app: appDescriptor, target: {...target, rootDir: root}, manifest};
+            } catch (error) {
+                try { await rm(root, {recursive: true, force: true}); }
+                catch (cleanupError) {
+                    throw new AggregateError([error, cleanupError], `Portable assembly failed; its incomplete output remains at ${root}.`);
+                }
+                throw error;
+            }
+        },
+        async verify({artifact, targetRequest, signal, onEvent} = {}) {
+            throwIfAborted(signal);
+            portableTarget(targetRequest);
+            const root = artifact?.target?.rootDir;
+            if (!is.string(root) || !root) throw new ArcaneError(ERROR_CODES.usage, 'Select a portable artifact root.');
+            const manifest = JSON.parse(await readFile(path.join(root, MANIFEST), 'utf8'));
+            for (const relative of manifest.files) {
+                throwIfAborted(signal);
+                const info = await stat(outputFile(root, relative));
+                if (!info.isFile()) throw new ArcaneError(ERROR_CODES.operationFailed, `Portable file is unavailable: ${relative}.`);
+            }
+            const result = {target: 'portable', outputRoot: root, manifest, executable: false};
+            await emit(onEvent, {type: 'native.verified', target: 'portable', outputRoot: root});
+            return result;
+        },
+        async run() {
+            throw new ArcaneError(ERROR_CODES.nativeRunUnsupported,
+                'Portable is a Core/app payload, not a native executable. Select an implemented platform host to launch it.');
+        }
+    };
+}
+
+export const arcaneNativeBuilderProvider = createPortableNativeProvider();
+export default arcaneNativeBuilderProvider;

package/src/native-plan.mjs

@@ -91,10 +91,13 @@ function selectedTargetRequest(value){
     if(value.format!==definition.format){
         fail(`Target ${value.target} requires format ${definition.format}.`,ERROR_CODES.targetUnavailable);
     }
-    if(value.signing!==definition.signingMode){
+    const nestedSigning=isObject(value.signing);
+    const signing=nestedSigning?value.signing.mode:value.signing;
+    const signingProfileId=(nestedSigning?value.signing.profileId:value.signingProfileId)??null;
+    if(signing!==definition.signingMode){
         fail(`Target ${value.target} requires signing mode ${definition.signingMode}.`,ERROR_CODES.targetUnavailable);
     }
-    if((value.signingProfileId??null)!==definition.signingProfileId){
+    if(signingProfileId!==definition.signingProfileId){
         fail(`Target ${value.target} has a different signing profile.`,ERROR_CODES.targetUnavailable);
     }
     return {
@@ -102,8 +105,8 @@ function selectedTargetRequest(value){
         platform:value.platform,
         architecture:value.architecture,
         format:value.format,
-        signing:value.signing,
-        signingProfileId:value.signingProfileId??null
+        signing,
+        signingProfileId
     };
 }
 
@@ -177,6 +180,7 @@ export async function createNativeBuildPlan({
     appReleaseRoot,
     release,
     appDescriptor,
+    selectedSdk,
     dependencyReleases,
     minimumCoreVersion,
     protectedRoots=[],
@@ -211,6 +215,7 @@ export async function createNativeBuildPlan({
         toolchainRoot:selectedToolchainRoot,
         toolchain:{...toolchain},
         appDescriptor:descriptor,
+        ...(selectedSdk===undefined?{}:{selectedSdk}),
         application,
         dependencies,
         minimumCoreVersion:minimumCoreVersion??null,
@@ -244,6 +249,7 @@ export async function executeNativeBuildPlan(plan,{
         toolchainRoot:plan.toolchainRoot,
         toolchain:plan.toolchain,
         appDescriptor:plan.appDescriptor,
+        ...(plan.selectedSdk===undefined?{}:{selectedSdk:plan.selectedSdk}),
         appReleaseRoot:plan.application.root,
         release:plan.application.release,
         readReleaseFile:plan.application.readFile,

package/src/native-provider-loader.mjs

@@ -1,7 +1,7 @@
 import Is from 'strong-type';
 import {lstat,realpath} from 'node:fs/promises';
 import path from 'node:path';
-import {pathToFileURL} from 'node:url';
+import {fileURLToPath,pathToFileURL} from 'node:url';
 import {ArcaneError,ERROR_CODES,throwIfAborted} from './errors.mjs';
 import {validateNativeBuilder} from './native-plan.mjs';
 
@@ -106,7 +106,11 @@ async function resolveProviderLocation({
             providerPath:canonicalProvider
         });
     }
-    return {canonicalRoot,providerPath:canonicalProvider};
+    return {
+        canonicalRoot,
+        providerPath:canonicalProvider,
+        providerSource:'arcane-checkout'
+    };
 }
 
 export async function loadArcaneNativeProvider(options={}){
@@ -129,7 +133,13 @@ export async function loadArcaneNativeProvider(options={}){
         target,
         message:`Loading the Arcane ${String(target)} provider.`
     });
-    const location=await resolveProviderLocation({arcaneRoot,target,inspect,canonicalize});
+    const location=arcaneRoot===undefined&&target==='portable'
+        ?{
+            canonicalRoot:path.resolve(fileURLToPath(new URL('../',import.meta.url))),
+            providerPath:fileURLToPath(new URL('./native/portable-provider.mjs',import.meta.url)),
+            providerSource:'sdk-package'
+        }
+        :await resolveProviderLocation({arcaneRoot,target,inspect,canonicalize});
     throwIfAborted(signal);
     let namespace;
     try{
@@ -147,9 +157,10 @@ export async function loadArcaneNativeProvider(options={}){
     );
     throwIfAborted(signal);
     const pairing={
-        arcaneRoot:location.canonicalRoot,
+        arcaneRoot:location.providerSource==='arcane-checkout'?location.canonicalRoot:null,
         toolchainRoot:location.canonicalRoot,
         providerPath:location.providerPath,
+        providerSource:location.providerSource,
         nativeBuilder
     };
     await onEvent?.({