arcane-os 0.1.2 → 0.2.1

package/src/scaffold.mjs

@@ -7,12 +7,11 @@ import {materializeWorkspaceRuntime} from './workspace-runtime.mjs';
 import {generateImportMap} from './import-map.mjs';
 import {withWorkspaceOperationLock} from './workspace-operation-lock.mjs';
 import {SDK_NAME,SDK_VERSION,workspaceTemplate} from './templates/workspace-template.mjs';
-import {inspectWorkspaceProfile} from './workspace.mjs';
+import {inspectWorkspaceProfile,resolveSdkPackageDeclaration} from './workspace.mjs';
 import {parseSemver} from './packager/core.mjs';
 
 const APP_ID_PATTERN=/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const DISPLAY_CONTROL_PATTERN=/[\x00-\x1f\x7f]/;
-const LOCAL_TARBALL_PATTERN=/^file:.+\.tgz$/iu;
 
 function fail(message,code='ARCANE_WORKSPACE_INVALID'){
     const error=new Error(message);
@@ -152,31 +151,35 @@ async function assertNoLinkedAncestors(workspaceRoot,relative){
     }
 }
 
-function isSupportedSdkDeclaration(value){
-    return value===SDK_VERSION||(typeof value==='string'&&LOCAL_TARBALL_PATTERN.test(value)
-        &&!DISPLAY_CONTROL_PATTERN.test(value));
-}
-
-async function prepareExistingPackage(workspaceRoot,files){
+async function readExistingPackage(workspaceRoot){
     const packagePath=path.join(workspaceRoot,'package.json');
     let source;
     try{source=await readFile(packagePath,'utf8');}
     catch(error){
-        if(error?.code==='ENOENT')return Object.freeze({exists:false,updated:false});
+        if(error?.code==='ENOENT'){
+            return Object.freeze({exists:false,packagePath,source:null,document:null});
+        }
         throw error;
     }
     let existing;
     try{existing=JSON.parse(source);}
     catch(error){fail(`Existing package.json is not valid JSON: ${error.message}.`);}
     if(!existing||typeof existing!=='object'||Array.isArray(existing))fail('Existing package.json must be a JSON object.');
+    return Object.freeze({exists:true,packagePath,source,document:existing});
+}
+
+function defaultSdkDeclaration(){
+    return resolveSdkPackageDeclaration({devDependencies:{[SDK_NAME]:SDK_VERSION}});
+}
+
+async function prepareExistingPackage(workspaceRoot,files,existingPackage,sdkDeclaration){
+    const packageState=existingPackage??await readExistingPackage(workspaceRoot);
+    if(!packageState.exists)return Object.freeze({exists:false,updated:false});
+    const {packagePath,source,document:existing}=packageState;
     const generated=JSON.parse(files.get('package.json'));
     const conflicts=[];
     if(existing.private!==undefined&&existing.private!==true)conflicts.push('private must be true');
     if(existing.type!==undefined&&existing.type!=='module')conflicts.push('type must be "module"');
-    const declared=existing.devDependencies?.[SDK_NAME]??existing.dependencies?.[SDK_NAME];
-    if(declared!==undefined&&!isSupportedSdkDeclaration(declared)){
-        conflicts.push(`${SDK_NAME} must be ${SDK_VERSION} or a local file: tarball`);
-    }
     const appSelectionScripts=new Set(['build','run']);
     for(const [name,command] of Object.entries(generated.scripts)){
         if(appSelectionScripts.has(name))continue;
@@ -192,12 +195,15 @@ async function prepareExistingPackage(workspaceRoot,files){
         private:true,
         type:'module',
         scripts:{...generated.scripts,...(existing.scripts||{})},
-        devDependencies:{...(existing.devDependencies||{}),[SDK_NAME]:declared??SDK_VERSION},
+        devDependencies:{
+            ...(existing.devDependencies||{}),
+            [sdkDeclaration.dependencyName]:sdkDeclaration.specifier
+        },
         engines:{...generated.engines,...(existing.engines||{})}
     };
-    if(existing.dependencies?.[SDK_NAME]!==undefined){
+    if(existing.dependencies?.[sdkDeclaration.dependencyName]!==undefined){
         merged.dependencies={...existing.dependencies};
-        delete merged.dependencies[SDK_NAME];
+        delete merged.dependencies[sdkDeclaration.dependencyName];
         if(Object.keys(merged.dependencies).length===0)delete merged.dependencies;
     }
     if(JSON.stringify(existing)===JSON.stringify(merged)){
@@ -422,6 +428,20 @@ export async function initWorkspace({
     const sdkBrowserRuntimeReceipt=workspaceMode==='external'
         ?await verifySdkBrowserRuntime({signal,onEvent})
         :null;
+    const existingPackage=workspaceMode==='external'
+        ?await readExistingPackage(resolvedRoot)
+        :null;
+    const sdkDeclaration=workspaceMode==='external'
+        ?profile?.config.sdkPackageSource!==undefined
+            ?resolveSdkPackageDeclaration(existingPackage.document??{}, {
+                allowMissing:true,
+                packageSource:profile.config.sdkPackageSource
+            })
+            :(existingPackage.exists
+                    ?resolveSdkPackageDeclaration(existingPackage.document,{allowMissing:true})
+                    :null)
+                ??defaultSdkDeclaration()
+        :null;
     const template=workspaceMode==='integrated'
         ?workspaceTemplate({
             appId,
@@ -437,12 +457,20 @@ export async function initWorkspace({
             displayName,
             runtimeRelease:runtimeReceipt,
             sdkBrowserRuntimeRelease:sdkBrowserRuntimeReceipt,
+            sdkDependencyName:sdkDeclaration.dependencyName,
+            sdkDependencySpecifier:sdkDeclaration.specifier,
+            sdkPackageSource:sdkDeclaration.packageSource,
             target,
             appIcon:await scaffoldIcon(target)
         });
     const packagePlan=workspaceMode==='integrated'
         ?Object.freeze({exists:true,updated:false})
-        :await prepareExistingPackage(resolvedRoot,template.files);
+        :await prepareExistingPackage(
+            resolvedRoot,
+            template.files,
+            existingPackage,
+            sdkDeclaration
+        );
     if(workspaceMode==='external'){
         await assertExistingLockAdmission(resolvedRoot,template.files);
     }

package/src/sdk-browser-runtime.mjs

@@ -1,6 +1,6 @@
 import {createHash} from 'node:crypto';
 import {constants as FS_CONSTANTS} from 'node:fs';
-import {lstat,open,readdir,realpath} from 'node:fs/promises';
+import {lstat,open,readFile,readdir,realpath} from 'node:fs/promises';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {SDK_VERSION} from './constants.mjs';
@@ -8,96 +8,49 @@ import {SDK_VERSION} from './constants.mjs';
 const MANIFEST_NAME='ARCANE_SDK_BROWSER_RELEASE.json';
 const BUILDER='arcane-sdk-browser-runtime-v1';
 const PROTOCOL='arcane-sdk-browser-runtime/1';
-export const SDK_BROWSER_RUNTIME_MANIFEST_SHA256=
-    '88395493b411fd5461fbb2bb065ae2b745f6d1672f796583fd248ec97f71f4f7';
-export const SDK_BROWSER_RUNTIME_CONTENT_SHA256=
-    '5e03f45a732db51cb5a2b2193cc79ecda34501d07a9b2e82e794e5fa37d55d00';
 const REPOSITORY='https://github.com/TheWizardNexus/arcane-os-sdk.git';
 const SHA256_PATTERN=/^[a-f0-9]{64}$/u;
 const READ_ONLY_NO_FOLLOW=FS_CONSTANTS.O_RDONLY|(FS_CONSTANTS.O_NOFOLLOW??0);
 const MAX_VERIFIED_FILE_BYTES=64*1024*1024;
 const packageRoot=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..');
 const defaultRoot=path.join(packageRoot,'browser-runtime');
+const canonicalManifestBytes=await readFile(path.join(defaultRoot,MANIFEST_NAME));
+const canonicalRelease=JSON.parse(canonicalManifestBytes.toString('utf8'));
+if(
+    canonicalRelease?.schemaVersion!==1
+    ||canonicalRelease.builder!==BUILDER
+    ||canonicalRelease.sdkVersion!==SDK_VERSION
+    ||!SHA256_PATTERN.test(canonicalRelease.contentSha256)
+){
+    throw new Error('The canonical SDK browser runtime receipt is invalid.');
+}
+export const SDK_BROWSER_RUNTIME_MANIFEST_SHA256=
+    createHash('sha256').update(canonicalManifestBytes).digest('hex');
+export const SDK_BROWSER_RUNTIME_CONTENT_SHA256=canonicalRelease.contentSha256;
 const issuedReceipts=new WeakSet();
-const expectedAiComponents=Object.freeze({
-    schemaVersion:1,
-    kind:'arcane-ai-browser-wasm-components',
-    protocol:'arcane-ai-browser-wasm/1',
-    packageExport:'arcane-os/ai/browser-wasm',
-    browserEntry:'ai/browser-wasm.mjs',
-    runtimePolicy:{
-        modelAuthorities:'caller-supplied-exact-bytes-and-sha256',
-        modelWeightsPacked:false,
-        remoteModelHelpers:false,
-        compatibilityRuntime:false,
-        toolCalls:'structural-only-never-executed'
-    },
-    components:[
-        {
-            name:'@wllama/wllama',
-            version:'3.6.0',
-            licenseSpdx:'MIT',
-            sourceRepository:'https://github.com/ngxson/wllama.git',
-            sourceRevision:'f16050d8d51a00602c6a2a6b8ac9c09f490eea7f',
-            npm:{
-                resolved:'https://registry.npmjs.org/@wllama/wllama/-/wllama-3.6.0.tgz',
-                integrity:'sha512-NN3ZBXqaaUwGXTQubkNvsCaLPjN2XVa0bVS40OYCE8zquYmRc2W3oHYEgwvuSWWDB8aUqTLyMioySCXNkcnD1w==',
-                tarballBytes:5671369,
-                tarballSha256:'137c35ceccb4911a9b0ce9b427889f75991654ec6a6d1dd8fabd879b14b07a1b'
-            },
-            files:[
-                {
-                    role:'runtime-module',
-                    path:'ai/wllama/index.mjs',
-                    sourcePath:'node_modules/@wllama/wllama/esm/index.js',
-                    bytes:373519,
-                    sha256:'4637e42d636010493a9b274fbbe70bfd8120365da726b1d9e589d85ca84a00d6'
-                },
-                {
-                    role:'runtime-wasm',
-                    path:'ai/wllama/wllama.wasm',
-                    sourcePath:'node_modules/@wllama/wllama/esm/wasm/wllama.wasm',
-                    bytes:8524865,
-                    sha256:'95c6ff9ef2a03ff2c63bc91db132f0126a0bd0456b272cd8ae2e0f592fb059f6'
-                },
-                {
-                    role:'license',
-                    path:'ai/wllama/LICENCE',
-                    sourcePath:'node_modules/@wllama/wllama/LICENCE',
-                    bytes:1071,
-                    sha256:'5866e3bd7e3cbd3f7c8bea6efd8a1e7fa7cc8de68c30f428aff7c6584a0fb720'
-                }
-            ]
-        },
-        {
-            name:'llama.cpp',
-            version:'b10454',
-            licenseSpdx:'MIT',
-            sourceRepository:'https://github.com/ggerganov/llama.cpp.git',
-            sourceRevision:'4df29be4f4c3673f428170fda944a5b19f743bb8',
-            embeddedBy:'@wllama/wllama@3.6.0',
-            files:[
-                {
-                    role:'license',
-                    path:'ai/wllama/llama.cpp-LICENSE',
-                    sourceUrl:'https://raw.githubusercontent.com/ggerganov/llama.cpp/4df29be4f4c3673f428170fda944a5b19f743bb8/LICENSE',
-                    bytes:1078,
-                    sha256:'94f29bbed6a22c35b992c5c6ebf0e7c92f13b836b90f36f461c9cf2f0f1d010d'
-                }
-            ]
-        }
-    ]
-});
+const canonicalAiComponentsBytes=await readFile(
+    path.join(defaultRoot,'ai','ARCANE_AI_BROWSER_WASM_COMPONENTS.json')
+);
+const expectedAiComponents=Object.freeze(
+    JSON.parse(canonicalAiComponentsBytes.toString('utf8'))
+);
 
 const expectedFiles=Object.freeze([
     ['ai/ARCANE_AI_BROWSER_WASM_COMPONENTS.json','browser-runtime/ai/ARCANE_AI_BROWSER_WASM_COMPONENTS.json','sdk-source-identity'],
+    ['ai/browser-kokoro-worker.mjs','browser-runtime/ai/browser-kokoro-worker.mjs','sdk-source-identity'],
+    ['ai/browser-speech-artifacts.mjs','browser-runtime/ai/browser-speech-artifacts.mjs','sdk-source-identity'],
+    ['ai/browser-speech-providers.mjs','browser-runtime/ai/browser-speech-providers.mjs','sdk-source-identity'],
+    ['ai/browser-speech.mjs','browser-runtime/ai/browser-speech.mjs','sdk-source-identity'],
     ['ai/browser-wasm-llm-provider.mjs','browser-runtime/ai/browser-wasm-llm-provider.mjs','sdk-source-identity'],
     ['ai/browser-wasm.mjs','browser-runtime/ai/browser-wasm.mjs','sdk-source-identity'],
+    ['ai/browser-whisper-worker.mjs','browser-runtime/ai/browser-whisper-worker.mjs','sdk-source-identity'],
     ['ai/browser-wllama-runtime.mjs','browser-runtime/ai/browser-wllama-runtime.mjs','sdk-source-identity'],
     ['ai/internal/sha256.mjs','browser-runtime/ai/internal/sha256.mjs','sdk-source-identity'],
     ['ai/model-controller.mjs','browser-runtime/ai/model-controller.mjs','sdk-source-identity'],
+    ['ai/speech-worker-client.mjs','browser-runtime/ai/speech-worker-client.mjs','sdk-source-identity'],
+    ['ai/speech-worker-runtime.mjs','browser-runtime/ai/speech-worker-runtime.mjs','sdk-source-identity'],
     ['ai/wllama/LICENCE','node_modules/@wllama/wllama/LICENCE','vendor-package-identity'],
-    ['ai/wllama/index.mjs','node_modules/@wllama/wllama/esm/index.js','vendor-package-identity'],
+    ['ai/wllama/index.mjs','browser-runtime/ai/wllama/index.mjs','deterministic-derived-vendor'],
     ['ai/wllama/llama.cpp-LICENSE','browser-runtime/ai/wllama/llama.cpp-LICENSE','vendor-source-identity'],
     ['ai/wllama/wllama.wasm','node_modules/@wllama/wllama/esm/wasm/wllama.wasm','vendor-package-identity'],
     ['dependencies/event-pubsub/index.js','node_modules/event-pubsub/index.js','vendor-package-identity'],

package/src/templates/workspace-template.mjs

@@ -4,6 +4,9 @@ import {
     SDK_BROWSER_RUNTIME_MANIFEST_SHA256
 } from '../sdk-browser-runtime.mjs';
 
+const NPM_PACKAGE_NAME_PATTERN=/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u;
+const LOCAL_TARBALL_PATTERN=/^file:.+\.tgz$/iu;
+
 function json(value){
     return `${JSON.stringify(value,null,2)}\n`;
 }
@@ -28,12 +31,28 @@ export function workspaceTemplate({
     displayName,
     runtimeRelease,
     sdkBrowserRuntimeRelease,
+    sdkDependencyName=SDK_NAME,
+    sdkDependencySpecifier=SDK_VERSION,
+    sdkPackageSource=`node_modules/${sdkDependencyName}`,
     appOnly=false,
     namedImports=true,
     minimumCoreVersion='0.8.12',
     target='browser',
     appIcon
 }){
+    const canonicalSpecifier=sdkDependencyName===SDK_NAME
+        &&(sdkDependencySpecifier===SDK_VERSION
+            ||(typeof sdkDependencySpecifier==='string'
+                &&LOCAL_TARBALL_PATTERN.test(sdkDependencySpecifier)
+                &&!/[\x00-\x1f\x7f]/.test(sdkDependencySpecifier)));
+    const aliasSpecifier=sdkDependencyName!==SDK_NAME
+        &&sdkDependencySpecifier===`npm:${SDK_NAME}@${SDK_VERSION}`;
+    if(typeof sdkDependencyName!=='string'||sdkDependencyName.length>214
+        ||!NPM_PACKAGE_NAME_PATTERN.test(sdkDependencyName)
+        ||sdkPackageSource!==`node_modules/${sdkDependencyName}`
+        ||(!canonicalSpecifier&&!aliasSpecifier)){
+        throw new Error('Invalid scaffold SDK installation authority.');
+    }
     const supportedTargets=['browser','portable','windows-x64','linux-x64','linux-arm64','android-arm64'];
     if(!supportedTargets.includes(target)){
         throw new Error(`Unsupported scaffold target: ${String(target)}.`);
@@ -47,7 +66,7 @@ export function workspaceTemplate({
     const name=displayName||`Arcane ${titleCase(appId)}`;
     const packageName=`arcane-${appId}`;
     const runtimeContentSha256=runtimeRelease?.contentSha256;
-    const upstreamCommit=runtimeRelease?.source?.commit;
+    const upstreamCommit=runtimeRelease?.source?.legacyProjection?.commit;
     const browserManifestSha256=sdkBrowserRuntimeRelease?.manifestSha256;
     const browserContentSha256=sdkBrowserRuntimeRelease?.contentSha256;
     const browserSource=sdkBrowserRuntimeRelease?.source;
@@ -153,15 +172,15 @@ appropriate.
     files.set('AGENTS.md',`# ${name} development instructions
 
 - Use plain JavaScript, HTML, and CSS; do not introduce TypeScript or TSX.
-- Keep reusable mechanisms in Arcane OS and app-specific behavior under \`apps/${appId}/\`.
+- Keep reusable portable mechanisms in the Arcane SDK and app-specific behavior under \`apps/${appId}/\`.
 - Keep \`arcane/css/theme.css\` before app styles and import \`arcane/ThemeBootstrap\` before app code runs.
 - Use \`rgb(...)\` or \`rgba(...)\` for new CSS colors.
 - Build one named app and one explicit target at a time. Native targets may be unavailable until their adapters are installed.
-- Run \`npm run check\` before committing.
+- Run tests and checks only when the user explicitly selects verification or a distribution artifact requires it.
 `);
     files.set('README.md',`# ${name}
 
-This repository contains the Arcane OS application \`${appId}\`. Its source stays outside the Arcane OS repository and uses the \`${SDK_NAME}\` toolchain.
+This repository contains the portable Arcane application \`${appId}\`. It embeds immutable SDK runtime bytes for distribution and has no runtime dependency on an Arcane OS source checkout.
 
 ## Start
 
@@ -222,7 +241,7 @@ Every browser release also carries Arcane OS licensing material under \`licenses
             }:{})
         },
         devDependencies:{
-            [SDK_NAME]:SDK_VERSION
+            [sdkDependencyName]:sdkDependencySpecifier
         },
         engines:{node:'>=22.23.2'}
     }));
@@ -239,7 +258,7 @@ Every browser release also carries Arcane OS licensing material under \`licenses
                     exclude:[]
                 },
                 {
-                    source:'node_modules/arcane-os',
+                    source:sdkPackageSource,
                     destination:'licenses/arcane-os',
                     include:['LICENSE','COMMERCIAL-LICENSE.md','NOTICE'],
                     exclude:[]
@@ -251,12 +270,12 @@ Every browser release also carries Arcane OS licensing material under \`licenses
         schemaVersion:1,
         sdk:{name:SDK_NAME,version:SDK_VERSION},
         runtime:{
-            manifest:'node_modules/arcane-os/runtime/ARCANE_RUNTIME_RELEASE.json',
+            manifest:`${sdkPackageSource}/runtime/ARCANE_RUNTIME_RELEASE.json`,
             contentSha256:runtimeContentSha256,
             upstreamCommit
         },
         sdkBrowserRuntime:{
-            manifest:'node_modules/arcane-os/browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json',
+            manifest:`${sdkPackageSource}/browser-runtime/ARCANE_SDK_BROWSER_RELEASE.json`,
             manifestSha256:browserManifestSha256,
             contentSha256:browserContentSha256,
             builder:sdkBrowserRuntimeRelease?.builder,

package/src/toolchain.mjs

@@ -380,11 +380,19 @@ async function preparedWorkspace(options){
         onEvent:options.onEvent
     });
     const external=workspace.workspaceMode==='external';
+    if(external&&(!workspace.sdkInstallation
+        ||typeof workspace.sdkInstallation.runtimeRoot!=='string'
+        ||typeof workspace.sdkInstallation.browserRuntimeRoot!=='string')){
+        throw new ArcaneError(
+            ERROR_CODES.workspaceInvalid,
+            'Validated external workspace is missing its bound SDK installation authority.'
+        );
+    }
     const runtimeRoot=external
-        ?path.join(workspace.workspaceRoot,'node_modules','arcane-os','runtime')
+        ?workspace.sdkInstallation.runtimeRoot
         :workspace.workspaceRoot;
     const browserRuntimeRoot=external
-        ?path.join(workspace.workspaceRoot,'node_modules','arcane-os','browser-runtime')
+        ?workspace.sdkInstallation.browserRuntimeRoot
         :null;
     const runtimeReceipt=external&&!options.deferRuntimeVerification
         ?await verifyRuntime({
@@ -791,6 +799,9 @@ export async function developApplication(options={}){
         mode:'source',
         workspaceRuntimeReceipt:prepared.workspaceRuntimeReceipt,
         workspaceMode:prepared.workspaceMode,
+        ...(options.sdkRuntimeSourceRoot===undefined?{}:{
+            sdkRuntimeSourceRoot:options.sdkRuntimeSourceRoot
+        }),
         host:options.host,
         port:options.port,
         signal:options.signal,

package/src/workspace-runtime.mjs

@@ -543,7 +543,7 @@ export async function verifyWorkspaceRuntime({
         sdkVersion:runtimeReceipt.sdkVersion,
         sources:Object.freeze({
             arcane:Object.freeze({
-                authority:'arcane-os-upstream',
+                authority:'arcane-os-sdk',
                 location:runtimeReceipt.canonicalLocation,
                 manifestSha256:runtimeReceipt.manifestSha256,
                 contentSha256:runtimeReceipt.contentSha256,