arcane-os 0.3.0 → 0.3.1

package/src/workspace-runtime.mjs

@@ -25,7 +25,18 @@ const READ_ONLY_NO_FOLLOW=FS_CONSTANTS.O_RDONLY|(FS_CONSTANTS.O_NOFOLLOW??0);
 const CREATE_NEW_NO_FOLLOW=FS_CONSTANTS.O_CREAT|FS_CONSTANTS.O_EXCL
     |FS_CONSTANTS.O_WRONLY|(FS_CONSTANTS.O_NOFOLLOW??0);
 const MAX_VERIFIED_WORKSPACE_RUNTIME_FILE_BYTES=64*1024*1024;
+const MAX_WORKSPACE_RUNTIME_RECEIPT_BYTES=4*1024*1024;
 const STAGING_PREFIX='.arcane-runtime-stage-';
+const BACKUP_PREFIX='.arcane-runtime-backup-';
+const MATERIALIZATION_RECEIPT_DIRECTORY='.arcane';
+const MATERIALIZATION_RECEIPT_NAME='installed-sdk-runtime.json';
+const RECEIPT_STAGING_PREFIX='.installed-sdk-runtime-stage-';
+const RECEIPT_BACKUP_PREFIX='.installed-sdk-runtime-backup-';
+const MATERIALIZATION_RECEIPT_KIND='arcane-installed-sdk-runtime-projection';
+const MATERIALIZATION_RECEIPT_PATH=
+    `${MATERIALIZATION_RECEIPT_DIRECTORY}/${MATERIALIZATION_RECEIPT_NAME}`;
+const SHA256_PATTERN=/^[a-f0-9]{64}$/u;
+const UUID_PATTERN=/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u;
 const issuedReceipts=new WeakSet();
 
 function fail(message,code='ARCANE_WORKSPACE_RUNTIME_INTEGRITY_FAILED'){
@@ -51,6 +62,33 @@ function compareText(left,right){
     return a<b?-1:a>b?1:0;
 }
 
+function isRecord(value){
+    return value!==null&&typeof value==='object'&&!Array.isArray(value);
+}
+
+function exactKeys(value,keys){
+    return isRecord(value)
+        &&Object.keys(value).sort(compareText).join('\0')===[...keys].sort(compareText).join('\0');
+}
+
+function canonicalJson(value){
+    return `${JSON.stringify(value,null,2)}\n`;
+}
+
+function deepFreeze(value){
+    if(!value||typeof value!=='object'||Object.isFrozen(value))return value;
+    for(const child of Object.values(value))deepFreeze(child);
+    return Object.freeze(value);
+}
+
+function inventoryContentSha256(files){
+    return createHash('sha256').update(JSON.stringify(files.map(file=>({
+        path:file.path,
+        bytes:file.bytes,
+        sha256:file.sha256
+    })))).digest('hex');
+}
+
 function safeRelativePath(value){
     if(typeof value!=='string'||!value||value.includes('\\')||value.includes('\0')
         ||path.posix.isAbsolute(value)||path.posix.normalize(value)!==value
@@ -164,6 +202,220 @@ function locationIdentityMatches(info,identity){
     return String(info.dev)===identity.device&&String(info.ino)===identity.inode;
 }
 
+function locationIdentity(identity){
+    return Object.freeze({device:identity.device,inode:identity.inode});
+}
+
+function assertPersistentIdentity(value,label,{locationOnly=false}={}){
+    const keys=locationOnly
+        ?['device','inode']
+        :['device','inode','bytes','modifiedNanoseconds','changedNanoseconds','links'];
+    if(!exactKeys(value,keys)
+        ||!keys.filter(key=>key!=='bytes')
+            .every(key=>typeof value[key]==='string'&&/^[0-9]+$/u.test(value[key]))
+        ||(!locationOnly&&(!Number.isSafeInteger(value.bytes)||value.bytes<0))){
+        fail(`Installed SDK runtime receipt ${label} is invalid.`,
+            'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+    }
+}
+
+function assertPersistentSourceReceipt(value,label,{browser=false}={}){
+    const keys=[
+        'canonicalLocation','rootIdentity','manifestPath','manifestSha256',
+        'manifestIdentity','sdkVersion','contentSha256','fileCount','totalBytes'
+    ];
+    if(browser)keys.push('builder');
+    if(!exactKeys(value,keys)
+        ||typeof value.canonicalLocation!=='string'||!path.isAbsolute(value.canonicalLocation)
+        ||typeof value.manifestPath!=='string'||!path.isAbsolute(value.manifestPath)
+        ||!SHA256_PATTERN.test(value.manifestSha256)
+        ||typeof value.sdkVersion!=='string'||!value.sdkVersion
+        ||!SHA256_PATTERN.test(value.contentSha256)
+        ||!Number.isSafeInteger(value.fileCount)||value.fileCount<1
+        ||!Number.isSafeInteger(value.totalBytes)||value.totalBytes<1
+        ||(browser&&(typeof value.builder!=='string'||!value.builder))){
+        fail(`Installed SDK runtime receipt ${label} is invalid.`,
+            'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+    }
+    assertPersistentIdentity(value.rootIdentity,`${label} root identity`);
+    assertPersistentIdentity(value.manifestIdentity,`${label} manifest identity`);
+}
+
+function validatePersistentMaterializationReceipt(document){
+    if(!exactKeys(document,[
+        'schemaVersion','kind','generation','workspace','receiptPath',
+        'installedPackage','runtimeReceipt','sdkBrowserRuntimeReceipt','projection'
+    ])||document.schemaVersion!==1||document.kind!==MATERIALIZATION_RECEIPT_KIND
+        ||!UUID_PATTERN.test(document.generation)
+        ||document.receiptPath!==MATERIALIZATION_RECEIPT_PATH){
+        fail('Installed SDK runtime receipt envelope is invalid.',
+            'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+    }
+    if(!exactKeys(document.workspace,['canonicalLocation','identity'])
+        ||typeof document.workspace.canonicalLocation!=='string'
+        ||!path.isAbsolute(document.workspace.canonicalLocation)){
+        fail('Installed SDK runtime receipt workspace is invalid.',
+            'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+    }
+    assertPersistentIdentity(document.workspace.identity,'workspace identity',{locationOnly:true});
+    const installed=document.installedPackage;
+    if(!exactKeys(installed,[
+        'dependencyName','dependencyGroup','specifier','packageSource','canonicalLocation',
+        'rootIdentity','packageName','packageVersion'
+    ])||![
+        installed.dependencyName,installed.dependencyGroup,installed.specifier,
+        installed.packageSource,installed.canonicalLocation,installed.packageName,
+        installed.packageVersion
+    ].every(value=>typeof value==='string'&&value)
+        ||!path.isAbsolute(installed.canonicalLocation)){
+        fail('Installed SDK runtime receipt package identity is invalid.',
+            'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+    }
+    safeRelativePath(installed.packageSource);
+    assertPersistentIdentity(installed.rootIdentity,'installed package root identity');
+    assertPersistentSourceReceipt(document.runtimeReceipt,'runtime source receipt');
+    assertPersistentSourceReceipt(
+        document.sdkBrowserRuntimeReceipt,
+        'browser runtime source receipt',
+        {browser:true}
+    );
+    if(document.runtimeReceipt.sdkVersion!==installed.packageVersion
+        ||document.sdkBrowserRuntimeReceipt.sdkVersion!==installed.packageVersion
+        ||path.resolve(installed.canonicalLocation,'runtime')
+            !==path.resolve(document.runtimeReceipt.canonicalLocation)
+        ||path.resolve(installed.canonicalLocation,'browser-runtime')
+            !==path.resolve(document.sdkBrowserRuntimeReceipt.canonicalLocation)){
+        fail('Installed SDK runtime receipt source binding is inconsistent.',
+            'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+    }
+    const projection=document.projection;
+    if(!exactKeys(projection,[
+        'relativePath','fileCount','totalBytes','contentSha256','files'
+    ])||projection.relativePath!=='arcane'||!Array.isArray(projection.files)
+        ||!Number.isSafeInteger(projection.fileCount)||projection.fileCount<1
+        ||!Number.isSafeInteger(projection.totalBytes)||projection.totalBytes<1
+        ||!SHA256_PATTERN.test(projection.contentSha256)
+        ||projection.fileCount!==projection.files.length){
+        fail('Installed SDK runtime receipt projection is invalid.',
+            'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+    }
+    const seen=new Set();
+    let totalBytes=0;
+    let previous='';
+    for(const [index,file] of projection.files.entries()){
+        if(!exactKeys(file,['path','sourcePath','authority','bytes','sha256'])
+            ||!['arcane-runtime','sdk-browser-runtime'].includes(file.authority)
+            ||!Number.isSafeInteger(file.bytes)||file.bytes<0
+            ||!SHA256_PATTERN.test(file.sha256)){
+            fail(`Installed SDK runtime receipt projection file ${String(index)} is invalid.`,
+                'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+        }
+        const projectedPath=safeRelativePath(file.path);
+        safeRelativePath(file.sourcePath);
+        const key=portableKey(projectedPath);
+        if(seen.has(key)||(index>0&&compareText(previous,projectedPath)>=0)){
+            fail('Installed SDK runtime receipt projection inventory is not unique and sorted.',
+                'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+        }
+        seen.add(key);
+        previous=projectedPath;
+        totalBytes+=file.bytes;
+        if(!Number.isSafeInteger(totalBytes)){
+            fail('Installed SDK runtime receipt projection byte total is invalid.',
+                'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+        }
+    }
+    if(totalBytes!==projection.totalBytes
+        ||inventoryContentSha256(projection.files)!==projection.contentSha256){
+        fail('Installed SDK runtime receipt projection inventory digest is invalid.',
+            'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+    }
+    return document;
+}
+
+function persistentSourceReceipt(receipt,{browser=false}={}){
+    const result={
+        canonicalLocation:receipt.canonicalLocation,
+        rootIdentity:receipt.rootIdentity,
+        manifestPath:receipt.manifestPath,
+        manifestSha256:receipt.manifestSha256,
+        manifestIdentity:receipt.manifestIdentity,
+        sdkVersion:receipt.sdkVersion,
+        contentSha256:receipt.contentSha256,
+        fileCount:receipt.fileCount,
+        totalBytes:receipt.totalBytes
+    };
+    if(browser)result.builder=receipt.builder;
+    return result;
+}
+
+async function createPersistentMaterializationReceipt({
+    generation,
+    workspace,
+    installedSdkAuthority,
+    runtimeReceipt,
+    sdkBrowserRuntimeReceipt,
+    expectedFiles
+}){
+    const {declaration,installation}=installedSdkAuthority??{};
+    if(!declaration||!installation){
+        fail('Installed SDK authority is required for a persistent workspace projection receipt.');
+    }
+    const packageInfo=await lstat(installation.canonicalPackageRoot,{bigint:true});
+    if(packageInfo.isSymbolicLink()||!packageInfo.isDirectory()){
+        fail('Installed SDK package root must remain a real directory.');
+    }
+    const canonicalPackageRoot=await realpath(installation.canonicalPackageRoot);
+    if(canonicalPackageRoot!==installation.canonicalPackageRoot){
+        fail('Installed SDK package root changed while materialization was active.');
+    }
+    if(runtimeReceipt.sdkVersion!==installation.packageVersion
+        ||sdkBrowserRuntimeReceipt.sdkVersion!==installation.packageVersion){
+        fail('Installed SDK package and source receipt versions do not match.');
+    }
+    const files=expectedFiles.map(file=>({
+        path:file.path,
+        sourcePath:file.sourcePath,
+        authority:file.authority,
+        bytes:file.bytes,
+        sha256:file.sha256
+    }));
+    const document={
+        schemaVersion:1,
+        kind:MATERIALIZATION_RECEIPT_KIND,
+        generation,
+        workspace:{
+            canonicalLocation:workspace.canonicalRoot,
+            identity:locationIdentity(workspace.identity)
+        },
+        receiptPath:MATERIALIZATION_RECEIPT_PATH,
+        installedPackage:{
+            dependencyName:declaration.dependencyName,
+            dependencyGroup:declaration.dependencyGroup,
+            specifier:declaration.specifier,
+            packageSource:declaration.packageSource,
+            canonicalLocation:canonicalPackageRoot,
+            rootIdentity:fileIdentity(packageInfo),
+            packageName:installation.packageName,
+            packageVersion:installation.packageVersion
+        },
+        runtimeReceipt:persistentSourceReceipt(runtimeReceipt),
+        sdkBrowserRuntimeReceipt:persistentSourceReceipt(
+            sdkBrowserRuntimeReceipt,
+            {browser:true}
+        ),
+        projection:{
+            relativePath:'arcane',
+            fileCount:files.length,
+            totalBytes:files.reduce((total,file)=>total+file.bytes,0),
+            contentSha256:inventoryContentSha256(files),
+            files
+        }
+    };
+    validatePersistentMaterializationReceipt(document);
+    return deepFreeze(document);
+}
+
 async function workspaceLocation(workspaceRoot){
     const requestedRoot=path.resolve(workspaceRoot);
     let info;
@@ -420,13 +672,108 @@ async function writeNewFile(filePath,bytes){
     }
 }
 
-async function cleanupStaging(stagingRoot,workspace,stagingIdentity){
-    const stagingParent=path.dirname(stagingRoot);
-    const stagingName=path.basename(stagingRoot);
-    if(stagingParent!==workspace.canonicalRoot||!stagingName.startsWith(STAGING_PREFIX)){
+async function readPersistentMaterializationReceipt(receiptPath,{signal}={}){
+    throwIfAborted(signal);
+    let handle;
+    try{
+        handle=await open(receiptPath,READ_ONLY_NO_FOLLOW);
+    }catch(error){
+        if(error?.code==='ELOOP'){
+            fail('Installed SDK runtime receipt must not be a symbolic link.',
+                'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+        }
+        throw error;
+    }
+    try{
+        const before=await handle.stat({bigint:true});
+        if(!before.isFile()||before.size>BigInt(MAX_WORKSPACE_RUNTIME_RECEIPT_BYTES)){
+            fail('Installed SDK runtime receipt is not a bounded regular file.',
+                'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+        }
+        const bytes=await handle.readFile();
+        throwIfAborted(signal);
+        const after=await handle.stat({bigint:true});
+        if(!sameIdentity(before,after)){
+            fail('Installed SDK runtime receipt changed while it was being read.',
+                'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+        }
+        let document;
+        try{document=JSON.parse(bytes.toString('utf8'));}
+        catch(error){
+            fail(`Installed SDK runtime receipt is not valid JSON: ${error.message}`,
+                'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+        }
+        validatePersistentMaterializationReceipt(document);
+        if(!bytes.equals(Buffer.from(canonicalJson(document)))){
+            fail('Installed SDK runtime receipt bytes are not canonical.',
+                'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+        }
+        const named=await lstat(receiptPath,{bigint:true});
+        if(named.isSymbolicLink()||!named.isFile()||!sameIdentity(named,after)){
+            fail('Installed SDK runtime receipt path changed while it was being read.',
+                'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+        }
+        return Object.freeze({
+            document:deepFreeze(document),
+            identity:fileIdentity(after)
+        });
+    }finally{
+        await handle.close();
+    }
+}
+
+async function assertOwnedFileLocation(filePath,identity,label){
+    const info=await lstat(filePath,{bigint:true});
+    if(info.isSymbolicLink()||!info.isFile()||!locationIdentityMatches(info,identity)){
+        fail(`${label} changed while workspace runtime materialization was active.`);
+    }
+}
+
+async function removeOwnedFile(filePath,identity,label){
+    await assertOwnedFileLocation(filePath,identity,label);
+    await rm(filePath,{force:true});
+    try{
+        await lstat(filePath,{bigint:true});
+        fail(`${label} remained after cleanup.`);
+    }catch(error){
+        if(error?.code!=='ENOENT')throw error;
+    }
+}
+
+async function materializationMetadataLocation(workspace){
+    const metadataRoot=path.join(workspace.canonicalRoot,MATERIALIZATION_RECEIPT_DIRECTORY);
+    let info;
+    try{info=await lstat(metadataRoot,{bigint:true});}
+    catch(error){
+        if(error?.code!=='ENOENT')throw error;
+        await mkdir(metadataRoot,{mode:0o700});
+        info=await lstat(metadataRoot,{bigint:true});
+    }
+    if(info.isSymbolicLink()||!info.isDirectory()){
+        fail('Workspace materialization metadata root must be a real directory.');
+    }
+    const canonical=await realpath(metadataRoot);
+    if(canonical!==metadataRoot){
+        fail('Workspace materialization metadata root must not resolve through another path.');
+    }
+    return Object.freeze({root:metadataRoot,identity:fileIdentity(info)});
+}
+
+async function optionalPathIdentity(target){
+    try{return fileIdentity(await lstat(target,{bigint:true}));}
+    catch(error){
+        if(error?.code==='ENOENT')return null;
+        throw error;
+    }
+}
+
+async function cleanupOwnedTree(ownedRoot,workspace,ownedIdentity,{prefix,label}){
+    const ownedParent=path.dirname(ownedRoot);
+    const ownedName=path.basename(ownedRoot);
+    if(ownedParent!==workspace.canonicalRoot||!ownedName.startsWith(prefix)){
         fail(
-            `Refusing to clean an unowned workspace runtime staging path: ${stagingRoot} `
-            +`(parent ${stagingParent}; expected ${workspace.canonicalRoot}).`
+            `Refusing to clean an unowned workspace runtime ${label} path: ${ownedRoot} `
+            +`(parent ${ownedParent}; expected ${workspace.canonicalRoot}).`
         );
     }
     await assertRealDirectoryLocation(
@@ -434,24 +781,24 @@ async function cleanupStaging(stagingRoot,workspace,stagingIdentity){
         workspace.identity,
         'Workspace root'
     );
-    let stagingInfo;
-    try{stagingInfo=await lstat(stagingRoot,{bigint:true});}
+    let ownedInfo;
+    try{ownedInfo=await lstat(ownedRoot,{bigint:true});}
     catch(error){
         if(error?.code==='ENOENT')return;
         throw error;
     }
-    if(stagingInfo.isSymbolicLink()||!stagingInfo.isDirectory()
-        ||!locationIdentityMatches(stagingInfo,stagingIdentity)){
-        fail('Refusing to clean a workspace runtime staging path whose identity changed.');
+    if(ownedInfo.isSymbolicLink()||!ownedInfo.isDirectory()
+        ||!locationIdentityMatches(ownedInfo,ownedIdentity)){
+        fail(`Refusing to clean a workspace runtime ${label} path whose identity changed.`);
     }
     await assertRealDirectoryLocation(
-        stagingRoot,
-        stagingIdentity,
-        'Workspace runtime staging directory'
+        ownedRoot,
+        ownedIdentity,
+        `Workspace runtime ${label} directory`
     );
-    try{await inspectTree(stagingRoot);}
+    try{await inspectTree(ownedRoot);}
     catch(error){
-        fail(`Refusing to clean an unauthenticated workspace runtime staging tree: ${error.message}`);
+        fail(`Refusing to clean an unauthenticated workspace runtime ${label} tree: ${error.message}`);
     }
     await assertRealDirectoryLocation(
         workspace.canonicalRoot,
@@ -459,14 +806,14 @@ async function cleanupStaging(stagingRoot,workspace,stagingIdentity){
         'Workspace root'
     );
     await assertRealDirectoryLocation(
-        stagingRoot,
-        stagingIdentity,
-        'Workspace runtime staging directory'
+        ownedRoot,
+        ownedIdentity,
+        `Workspace runtime ${label} directory`
     );
-    await rm(stagingRoot,{recursive:true,force:true});
+    await rm(ownedRoot,{recursive:true,force:true});
     try{
-        await lstat(stagingRoot,{bigint:true});
-        fail('Workspace runtime staging path remained after cleanup.');
+        await lstat(ownedRoot,{bigint:true});
+        fail(`Workspace runtime ${label} path remained after cleanup.`);
     }catch(error){
         if(error?.code!=='ENOENT')throw error;
     }
@@ -477,6 +824,13 @@ async function cleanupStaging(stagingRoot,workspace,stagingIdentity){
     );
 }
 
+async function cleanupStaging(stagingRoot,workspace,stagingIdentity){
+    return cleanupOwnedTree(stagingRoot,workspace,stagingIdentity,{
+        prefix:STAGING_PREFIX,
+        label:'staging'
+    });
+}
+
 export async function verifyWorkspaceRuntime({
     workspaceRoot,
     runtimeRoot=path.join(getSdkRoot(),'runtime'),
@@ -578,12 +932,428 @@ export async function verifyWorkspaceRuntime({
     return receipt;
 }
 
+function attachMaterialization(receipt,{
+    status,
+    persistentReceipt,
+    receiptPath,
+    cleanupWarnings=[]
+}){
+    const result=Object.freeze({
+        ...receipt,
+        materialization:Object.freeze({
+            status,
+            generation:persistentReceipt.generation,
+            receiptPath,
+            persistentReceipt,
+            cleanupWarnings:Object.freeze([...cleanupWarnings])
+        })
+    });
+    issuedReceipts.add(result);
+    return result;
+}
+
+async function inspectInstalledMaterialization({
+    workspace,
+    destinationRoot,
+    receiptPath,
+    desiredReceipt,
+    signal
+}){
+    const destinationIdentity=await optionalPathIdentity(destinationRoot);
+    const receiptIdentity=await optionalPathIdentity(receiptPath);
+    if(!destinationIdentity&&!receiptIdentity)return Object.freeze({kind:'absent'});
+    if(!destinationIdentity){
+        fail('Installed SDK runtime receipt exists without its workspace projection.',
+            'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+    }
+    const destinationInfo=await lstat(destinationRoot,{bigint:true});
+    if(destinationInfo.isSymbolicLink()||!destinationInfo.isDirectory()){
+        fail('Existing workspace arcane runtime path must be a real directory.');
+    }
+    const canonicalDestination=await realpath(destinationRoot);
+    if(canonicalDestination!==destinationRoot){
+        fail('Existing workspace arcane runtime path must not resolve through another path.');
+    }
+    if(!receiptIdentity){
+        await inspectTree(destinationRoot,{signal});
+        return Object.freeze({
+            kind:'legacy',
+            destinationIdentity:fileIdentity(destinationInfo)
+        });
+    }
+    const recorded=await readPersistentMaterializationReceipt(receiptPath,{signal});
+    if(recorded.document.workspace.canonicalLocation!==workspace.canonicalRoot
+        ||recorded.document.workspace.identity.device!==workspace.identity.device
+        ||recorded.document.workspace.identity.inode!==workspace.identity.inode){
+        fail('Installed SDK runtime receipt belongs to a different workspace.',
+            'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+    }
+    if(canonicalJson(recorded.document)===canonicalJson(desiredReceipt)){
+        return Object.freeze({
+            kind:'current',
+            document:recorded.document,
+            destinationIdentity:fileIdentity(destinationInfo),
+            receiptIdentity:recorded.identity
+        });
+    }
+    await verifyProjectedTree(
+        destinationRoot,
+        recorded.document.projection.files,
+        {signal}
+    );
+    return Object.freeze({
+        kind:'stale',
+        document:recorded.document,
+        destinationIdentity:fileIdentity(destinationInfo),
+        receiptIdentity:recorded.identity
+    });
+}
+
+async function rollbackInstalledReplacement(state){
+    const errors=[];
+    const attempt=async operation=>{
+        try{await operation();}
+        catch(error){errors.push(error);}
+    };
+    if(state.newReceiptMoved){
+        await attempt(()=>rename(state.receiptPath,state.receiptStagingPath));
+    }
+    if(state.newRootMoved){
+        await attempt(()=>rename(state.destinationRoot,state.stagingRoot));
+    }
+    if(state.oldReceiptMoved){
+        await attempt(()=>rename(state.receiptBackupPath,state.receiptPath));
+    }
+    if(state.oldRootMoved){
+        await attempt(()=>rename(state.backupRoot,state.destinationRoot));
+    }
+    if(errors.length){
+        throw new AggregateError(
+            errors,
+            'Installed SDK runtime replacement failed and its prior projection could not be fully restored.'
+        );
+    }
+    state.newReceiptMoved=false;
+    state.newRootMoved=false;
+    state.oldReceiptMoved=false;
+    state.oldRootMoved=false;
+}
+
+async function materializeInstalledWorkspaceRuntime({
+    workspaceRoot,
+    runtimeRoot,
+    runtimeReceipt,
+    browserRuntimeRoot,
+    sdkBrowserRuntimeReceipt,
+    installedSdkAuthority,
+    signal,
+    onEvent
+}){
+    const expectedFiles=projectRuntimeFiles(runtimeReceipt,sdkBrowserRuntimeReceipt);
+    const workspace=await workspaceLocation(workspaceRoot);
+    const metadata=await materializationMetadataLocation(workspace);
+    const destinationRoot=path.join(workspace.canonicalRoot,'arcane');
+    const receiptPath=path.join(metadata.root,MATERIALIZATION_RECEIPT_NAME);
+    const generation=randomUUID();
+    let desiredReceipt=await createPersistentMaterializationReceipt({
+        generation,
+        workspace,
+        installedSdkAuthority,
+        runtimeReceipt,
+        sdkBrowserRuntimeReceipt,
+        expectedFiles
+    });
+    let existingReceipt=null;
+    try{
+        existingReceipt=(await readPersistentMaterializationReceipt(receiptPath,{signal})).document;
+        desiredReceipt=await createPersistentMaterializationReceipt({
+            generation:existingReceipt.generation,
+            workspace,
+            installedSdkAuthority,
+            runtimeReceipt,
+            sdkBrowserRuntimeReceipt,
+            expectedFiles
+        });
+    }catch(error){
+        if(error?.code!=='ENOENT')throw error;
+    }
+    const existing=await inspectInstalledMaterialization({
+        workspace,
+        destinationRoot,
+        receiptPath,
+        desiredReceipt,
+        signal
+    });
+    if(existing.kind==='current'){
+        const verified=await verifyWorkspaceRuntime({
+            workspaceRoot,
+            runtimeRoot,
+            runtimeReceipt,
+            browserRuntimeRoot,
+            sdkBrowserRuntimeReceipt,
+            signal,
+            onEvent
+        });
+        const result=attachMaterialization(verified,{
+            status:'reused',
+            persistentReceipt:existing.document,
+            receiptPath
+        });
+        await emit(onEvent,{
+            type:'workspace.runtime.materialize.reused',
+            status:'reused',
+            generation:existing.document.generation,
+            receiptPath
+        });
+        return result;
+    }
+
+    desiredReceipt=await createPersistentMaterializationReceipt({
+        generation,
+        workspace,
+        installedSdkAuthority,
+        runtimeReceipt,
+        sdkBrowserRuntimeReceipt,
+        expectedFiles
+    });
+    const operationSuffix=`${String(process.pid)}-${generation}`;
+    const stagingRoot=path.join(workspace.canonicalRoot,`${STAGING_PREFIX}${operationSuffix}`);
+    const backupRoot=path.join(workspace.canonicalRoot,`${BACKUP_PREFIX}${operationSuffix}`);
+    const receiptStagingPath=path.join(
+        metadata.root,
+        `${RECEIPT_STAGING_PREFIX}${operationSuffix}.json`
+    );
+    const receiptBackupPath=path.join(
+        metadata.root,
+        `${RECEIPT_BACKUP_PREFIX}${operationSuffix}.json`
+    );
+    await mkdir(stagingRoot,{mode:0o700});
+    const stagingInfo=await lstat(stagingRoot,{bigint:true});
+    if(stagingInfo.isSymbolicLink()||!stagingInfo.isDirectory()){
+        fail('Workspace runtime staging path must be a real directory.');
+    }
+    const stagingIdentity=fileIdentity(stagingInfo);
+    const transaction={
+        destinationRoot,
+        stagingRoot,
+        backupRoot,
+        receiptPath,
+        receiptStagingPath,
+        receiptBackupPath,
+        newReceiptMoved:false,
+        newRootMoved:false,
+        oldReceiptMoved:false,
+        oldRootMoved:false
+    };
+    let stagingCleaned=false;
+    let receiptStagingIdentity;
+    let uncertainCommit=false;
+    try{
+        const totalBytes=expectedFiles.reduce((total,file)=>total+file.bytes,0);
+        const bufferedEvents=[{
+            type:'workspace.runtime.materialize.started',
+            status:existing.kind==='absent'?'created':'refreshed',
+            generation,
+            fileCount:expectedFiles.length,
+            totalBytes
+        }];
+        let writtenBytes=0;
+        for(const [index,file] of expectedFiles.entries()){
+            throwIfAborted(signal);
+            const bytes=file.authority==='sdk-browser-runtime'
+                ?await readVerifiedSdkBrowserRuntimeFile(sdkBrowserRuntimeReceipt,{
+                    browserRuntimeRoot,
+                    relativePath:file.sourcePath,
+                    signal
+                })
+                :await readVerifiedRuntimeFile(runtimeReceipt,{
+                    runtimeRoot,
+                    relativePath:file.sourcePath,
+                    signal
+                });
+            const destination=resolveContained(stagingRoot,file.path);
+            await mkdir(path.dirname(destination),{recursive:true,mode:0o755});
+            await writeNewFile(destination,bytes);
+            writtenBytes+=bytes.length;
+            bufferedEvents.push({
+                type:'workspace.runtime.materialize.progress',
+                current:index+1,
+                total:expectedFiles.length,
+                writtenBytes,
+                totalBytes,
+                path:file.path
+            });
+        }
+        await verifyProjectedTree(stagingRoot,expectedFiles,{signal});
+        await writeNewFile(receiptStagingPath,Buffer.from(canonicalJson(desiredReceipt)));
+        const receiptStagingInfo=await lstat(receiptStagingPath,{bigint:true});
+        if(receiptStagingInfo.isSymbolicLink()||!receiptStagingInfo.isFile()){
+            fail('Workspace runtime staged receipt must be a real file.');
+        }
+        receiptStagingIdentity=fileIdentity(receiptStagingInfo);
+        await readPersistentMaterializationReceipt(receiptStagingPath,{signal});
+
+        for(const event of bufferedEvents)await emit(onEvent,event);
+        throwIfAborted(signal);
+        await assertRealDirectoryLocation(
+            workspace.canonicalRoot,
+            workspace.identity,
+            'Workspace root'
+        );
+        await assertRealDirectoryLocation(
+            metadata.root,
+            metadata.identity,
+            'Workspace materialization metadata root'
+        );
+        await assertRealDirectoryLocation(
+            stagingRoot,
+            stagingIdentity,
+            'Workspace runtime staging directory'
+        );
+        await assertOwnedFileLocation(
+            receiptStagingPath,
+            receiptStagingIdentity,
+            'Workspace runtime staged receipt'
+        );
+        await verifyProjectedTree(stagingRoot,expectedFiles,{signal});
+        if(existing.destinationIdentity){
+            await assertRealDirectoryLocation(
+                destinationRoot,
+                existing.destinationIdentity,
+                'Existing workspace runtime projection'
+            );
+        }
+        if(existing.receiptIdentity){
+            await assertOwnedFileLocation(
+                receiptPath,
+                existing.receiptIdentity,
+                'Existing workspace runtime receipt'
+            );
+        }
+        throwIfAborted(signal);
+
+        try{
+            if(existing.destinationIdentity){
+                await rename(destinationRoot,backupRoot);
+                transaction.oldRootMoved=true;
+            }
+            if(existing.receiptIdentity){
+                await rename(receiptPath,receiptBackupPath);
+                transaction.oldReceiptMoved=true;
+            }
+            await rename(stagingRoot,destinationRoot);
+            transaction.newRootMoved=true;
+            await rename(receiptStagingPath,receiptPath);
+            transaction.newReceiptMoved=true;
+        }catch(commitError){
+            try{await rollbackInstalledReplacement(transaction);}
+            catch(rollbackError){
+                uncertainCommit=true;
+                throw new AggregateError(
+                    [commitError,rollbackError],
+                    'Installed SDK runtime replacement and rollback both failed.',
+                    {cause:commitError}
+                );
+            }
+            throw commitError;
+        }
+
+        let committedPersistent;
+        let verified;
+        try{
+            committedPersistent=(await readPersistentMaterializationReceipt(receiptPath)).document;
+            if(canonicalJson(committedPersistent)!==canonicalJson(desiredReceipt)){
+                fail('Committed installed SDK runtime receipt does not match the staged generation.',
+                    'ARCANE_WORKSPACE_RUNTIME_RECEIPT_INVALID');
+            }
+            verified=await verifyWorkspaceRuntime({
+                workspaceRoot,
+                runtimeRoot,
+                runtimeReceipt,
+                browserRuntimeRoot,
+                sdkBrowserRuntimeReceipt
+            });
+        }catch(verificationError){
+            try{await rollbackInstalledReplacement(transaction);}
+            catch(rollbackError){
+                uncertainCommit=true;
+                throw new AggregateError(
+                    [verificationError,rollbackError],
+                    'Installed SDK runtime verification and rollback both failed.',
+                    {cause:verificationError}
+                );
+            }
+            throw verificationError;
+        }
+
+        const cleanupWarnings=[];
+        if(existing.destinationIdentity){
+            try{
+                await cleanupOwnedTree(backupRoot,workspace,existing.destinationIdentity,{
+                    prefix:BACKUP_PREFIX,
+                    label:'backup'
+                });
+                transaction.oldRootMoved=false;
+            }catch(error){cleanupWarnings.push(String(error?.message??error));}
+        }
+        if(existing.receiptIdentity){
+            try{
+                await removeOwnedFile(
+                    receiptBackupPath,
+                    existing.receiptIdentity,
+                    'Workspace runtime receipt backup'
+                );
+                transaction.oldReceiptMoved=false;
+            }catch(error){cleanupWarnings.push(String(error?.message??error));}
+        }
+        transaction.newRootMoved=false;
+        transaction.newReceiptMoved=false;
+        stagingCleaned=true;
+        const status=existing.kind==='absent'?'created':'refreshed';
+        const result=attachMaterialization(verified,{
+            status,
+            persistentReceipt:committedPersistent,
+            receiptPath,
+            cleanupWarnings
+        });
+        await emit(onEvent,{
+            type:'workspace.runtime.materialize.completed',
+            status,
+            generation,
+            receiptPath,
+            contentSha256:result.contentSha256,
+            sourceContentSha256:result.sourceContentSha256,
+            sourceBrowserContentSha256:result.sourceBrowserContentSha256,
+            fileCount:result.fileCount,
+            totalBytes:result.totalBytes,
+            cleanupWarnings:Object.freeze([...cleanupWarnings])
+        });
+        return result;
+    }finally{
+        if(!uncertainCommit&&!stagingCleaned){
+            await cleanupStaging(stagingRoot,workspace,stagingIdentity);
+            if(receiptStagingIdentity){
+                try{
+                    await removeOwnedFile(
+                        receiptStagingPath,
+                        receiptStagingIdentity,
+                        'Workspace runtime staged receipt'
+                    );
+                }catch(error){
+                    if(error?.code!=='ENOENT')throw error;
+                }
+            }
+        }
+    }
+}
+
 export async function materializeWorkspaceRuntime({
     workspaceRoot,
     runtimeRoot=path.join(getSdkRoot(),'runtime'),
     runtimeReceipt,
     browserRuntimeRoot=getSdkBrowserRuntimeRoot(),
     sdkBrowserRuntimeReceipt,
+    installedSdkAuthority,
     signal,
     onEvent
 }={}){
@@ -593,6 +1363,18 @@ export async function materializeWorkspaceRuntime({
         browserRuntimeRoot,
         signal
     });
+    if(installedSdkAuthority){
+        return materializeInstalledWorkspaceRuntime({
+            workspaceRoot,
+            runtimeRoot,
+            runtimeReceipt,
+            browserRuntimeRoot,
+            sdkBrowserRuntimeReceipt,
+            installedSdkAuthority,
+            signal,
+            onEvent
+        });
+    }
     const expectedFiles=projectRuntimeFiles(runtimeReceipt,sdkBrowserRuntimeReceipt);
     const workspace=await workspaceLocation(workspaceRoot);
     const destinationRoot=path.join(workspace.canonicalRoot,'arcane');