arcane-os 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.3.4
+
+- Allowed external and integrated physical SDK workspaces to omit the optional
+  `security` runtime route while preserving the canonical functional route
+  order, `dependencies` and `sdk` projections, external license routing, and
+  compatibility with workspaces that still include `security`.
+- Preserved a newer microphone retry's press, status, and operation identity
+  when an earlier pending capture request settles, while retaining the original
+  operation correlation for successful transcription.
+
+## 0.3.3
+
+- Corrected installed-workspace import-map refresh to preserve rich browser
+  document inspection records while passing only navigable document paths to
+  the public generator, including `.html` and `.htm` pages without modifying
+  HTML fragments.
+- Restored one semantic `arcane.lock.json` contract across scaffold, init, and
+  installed runtime materialization, replacing stale versions with the exact
+  installed package version and npm-alias roots without byte or security
+  metadata.
+- Added selected installed-package coverage for stale-lock replacement and the
+  public multi-document import-map command through the packed npm artifact.
+
 ## 0.3.2
 
 - Preserved complete application, document, model, message, event, process,

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.3.2` SDK contract. Applications pin one exact npm
+This checkout defines the `0.3.4` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -126,7 +126,7 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.3.2 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.3.4 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run check
@@ -137,7 +137,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.3.2
+npm install --save-dev --save-exact arcane-os@0.3.4
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -153,7 +153,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.3.2` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.3.4` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -174,7 +174,7 @@ node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.3.2.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.3.4.tgz
 npm run check
 npm ci
 ```
@@ -184,7 +184,7 @@ same location. The lockfile retains the selected package dependency while
 Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.3.2` registry package and
+the local declaration with the exact `arcane-os@0.3.4` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -322,7 +322,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.3.2` exposes one browser target and five explicitly paired
+Version `0.3.4` exposes one browser target and five explicitly paired
 native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/runtime/arcane/components/speech.html

@@ -1235,11 +1235,14 @@
         }
 
         const generation = ++recordingGeneration;
-        transcriptionOperationId = nextSpeechOperationId('transcription');
+        const operationId = nextSpeechOperationId('transcription');
+        transcriptionOperationId = operationId;
         recordingRequested = true;
         localStatus = {
             message: 'Recording. Release to transcribe.',
-            tone: ''
+            tone: '',
+            owner: 'recording',
+            generation
         };
         renderControls();
         renderStatus();
@@ -1248,6 +1251,9 @@
         try {
             stream = await navigator.mediaDevices.getUserMedia({ audio: true });
         } catch (error) {
+            if (generation !== recordingGeneration || destroyed) {
+                return false;
+            }
             recordingRequested = false;
             resetRecordPress();
             if (
@@ -1268,7 +1274,7 @@
                     {
                         bubbles: true,
                         composed: true,
-                        operationId: transcriptionOperationId,
+                        operationId,
                         publicDetail: {
                             ...publicSpeechErrorFields(
                                 error,
@@ -1278,7 +1284,9 @@
                         }
                     }
                 );
-                transcriptionOperationId = null;
+                if (transcriptionOperationId === operationId) {
+                    transcriptionOperationId = null;
+                }
             } else {
                 reportTranscriptionError(error);
             }
@@ -1287,15 +1295,25 @@
             return false;
         }
 
+        const currentGeneration = generation === recordingGeneration;
         if (
             !recordingRequested
-            || generation !== recordingGeneration
+            || !currentGeneration
             || sttRole.state !== 'ready'
             || sttRole.busy
             || destroyed
         ) {
             stopMediaStream(stream);
-            resetRecordPress();
+            if (currentGeneration) {
+                recordingRequested = false;
+                resetRecordPress();
+                clearRecordingStatus(generation);
+                if (transcriptionOperationId === operationId) {
+                    transcriptionOperationId = null;
+                }
+                renderControls();
+                renderStatus();
+            }
             return false;
         }
 
@@ -1311,6 +1329,7 @@
             const processor = audioContext.createScriptProcessor(4096, 1, 1);
             session = {
                 generation,
+                operationId,
                 recorder,
                 stream,
                 audioContext,
@@ -1349,7 +1368,6 @@
             recorder.start();
             return true;
         } catch (error) {
-            recordingRequested = false;
             if (session) {
                 session.cancelled = true;
                 releaseCaptureSession(session);
@@ -1359,8 +1377,11 @@
             } else {
                 stopMediaStream(stream);
             }
-            resetRecordPress();
-            reportTranscriptionError(error);
+            if (generation === recordingGeneration) {
+                recordingRequested = false;
+                resetRecordPress();
+                reportTranscriptionError(error);
+            }
             return false;
         }
     }
@@ -1377,32 +1398,67 @@
         }
     }
 
+    function clearRecordingStatus(generation) {
+        if (
+            localStatus?.owner === 'recording'
+            && localStatus.generation === generation
+        ) {
+            localStatus = null;
+        }
+    }
+
     function stop() {
+        const pendingCaptureStart = recordingRequested && !captureSession;
+        const generation = recordingGeneration;
+        const operationId = transcriptionOperationId;
         recordingRequested = false;
         clearSilenceTimer();
-        if (captureSession?.recorder.state !== 'inactive') {
+        if (pendingCaptureStart) {
+            // getUserMedia cannot be cancelled synchronously. Retire this
+            // generation so its eventual settlement cannot touch a retry.
+            recordingGeneration += 1;
+            resetRecordPress();
+            clearRecordingStatus(generation);
+            if (transcriptionOperationId === operationId) {
+                transcriptionOperationId = null;
+            }
+            renderControls();
+            renderStatus();
+            return true;
+        }
+        if (captureSession && captureSession.recorder.state !== 'inactive') {
             captureSession.recorder.stop();
         }
         return true;
     }
 
     async function finalizeCapture(session) {
+        const currentGeneration = session.generation === recordingGeneration;
+        const currentOperation = transcriptionOperationId === session.operationId;
         releaseCaptureSession(session);
         if (captureSession === session) {
             captureSession = null;
         }
-        recordingRequested = false;
-        resetRecordPress();
+        if (currentGeneration) {
+            recordingRequested = false;
+            resetRecordPress();
+        }
 
         if (
             session.cancelled
-            || session.generation !== recordingGeneration
+            || !currentGeneration
             || sttRole.state !== 'ready'
             || sttRole.busy
             || destroyed
         ) {
-            renderControls();
-            renderStatus();
+            if (currentGeneration) {
+                clearRecordingStatus(session.generation);
+                if (currentOperation) {
+                    transcriptionOperationId = null;
+                }
+                renderControls();
+                renderStatus();
+            }
             return false;
         }
 
@@ -1415,12 +1471,13 @@
             'audio.webm',
             { type: 'audio/webm' }
         );
-        return transcribeAudio(audioFile);
+        return transcribeAudio(audioFile, session.operationId);
     }
 
-    async function transcribeAudio(audioFile) {
+    async function transcribeAudio(audioFile, operationId = null) {
         const generation = ++transcriptionGeneration;
-        transcriptionOperationId = transcriptionOperationId
+        transcriptionOperationId = operationId
+            || transcriptionOperationId
             || nextSpeechOperationId('transcription');
         const controller = new AbortController();
         transcriptionAbortController?.abort();

package/schemas/arcane-lock.schema.json

@@ -14,7 +14,10 @@
       "required": ["name", "version"],
       "properties": {
         "name": {"const": "arcane-os"},
-        "version": {"const": "0.3.2"}
+        "version": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?$"
+        }
       }
     },
     "runtime": {

package/src/cli/main.mjs

@@ -47,6 +47,7 @@ const REPORTABLE_COMMANDS=new Set([
     'native-doctor','native-prepare','new','package','repo','run','targets','test',
     'update-check','upgrade','verify','verify-bundle','version'
 ]);
+const MAX_NODE_TIMER_DELAY_MS=2_147_483_647;
 
 export const HELP_TEXT=`Arcane OS application SDK ${SDK_VERSION}
 
@@ -76,7 +77,7 @@ Usage:
   ${CLI_NAME} mail key status <profile>
   ${CLI_NAME} mail key delete <profile>
   ${CLI_NAME} mail send --profile <profile> --from <address> --report-key <id> --report-stdin [--request-timeout <ms>]
-  ${CLI_NAME} mail serve --profile <profile> --from <address> --app <id> --origin <origin> --allow-to <addresses> [--app-key-stdin] [--host 127.0.0.1] [--port 8025] [--request-timeout <ms>]
+  ${CLI_NAME} mail serve --profile <profile> --from <address> --app <id> --origin <origin> [--allow-to <addresses>] [--app-key-stdin] [--host 127.0.0.1] [--port 8025] [--request-timeout <ms>]
 
 Development:
   --sdk-runtime-source <sdk-root>  Dev-only live SDK checkout; omitted preserves the workspace runtime mode.
@@ -174,16 +175,17 @@ function readPort(value,defaultValue){
     return port;
 }
 
-function readRequestTimeout(value,defaultValue){
-    if(value===undefined){
-        return defaultValue;
-    }
+function readRequestTimeout(value){
+    if(value===undefined)return undefined;
     if(!/^\d+$/u.test(value)){
         usage(`Invalid request timeout: ${value}.`);
     }
     const timeout=Number(value);
-    if(!Number.isSafeInteger(timeout)||timeout<1_000||timeout>600_000){
-        usage('Mail request timeout must be an integer between 1000 and 600000 milliseconds.');
+    if(!Number.isSafeInteger(timeout)||timeout<1||timeout>MAX_NODE_TIMER_DELAY_MS){
+        usage(
+            `Mail request timeout must be an integer from 1 through ${MAX_NODE_TIMER_DELAY_MS} `
+            +'milliseconds, the Node timer range.'
+        );
     }
     return timeout;
 }
@@ -649,8 +651,7 @@ function operationOptions(command,parsed,cwd){
                 profile:values.profile,
                 from:values.from,
                 app:values.app,
-                origin:values.origin,
-                'allow-to':values['allow-to'],
+                origin:values.origin
             })){
                 if(!value)usage(`mail serve requires --${name} <value>.`);
             }
@@ -664,7 +665,7 @@ function operationOptions(command,parsed,cwd){
                 appKeyStdin:flags.has('app-key-stdin'),
                 host:values.host??'127.0.0.1',
                 port:readPort(values.port,8025),
-                requestTimeout:readRequestTimeout(values['request-timeout'],30_000),
+                requestTimeout:readRequestTimeout(values['request-timeout']),
             };
         }
         if(area==='send'){
@@ -693,7 +694,7 @@ function operationOptions(command,parsed,cwd){
                 from:values.from,
                 reportKey:values['report-key'],
                 reportStdin:true,
-                requestTimeout:readRequestTimeout(values['request-timeout'],30_000),
+                requestTimeout:readRequestTimeout(values['request-timeout']),
             };
         }
         usage('mail requires key set|status|delete <profile>, send, or serve.');

package/src/dev-server.mjs

@@ -31,6 +31,11 @@ const SDK_RUNTIME_SOURCE_PROTOCOL='arcane-sdk-runtime-source/1';
 const SDK_RUNTIME_SOURCE_ARCANE_ROOTS=new Set([
     'components','css','entities','img','modules','security'
 ]);
+const SDK_INSTALLED_ARCANE_ROOTS=new Set([
+    ...SDK_RUNTIME_SOURCE_ARCANE_ROOTS,
+    'dependencies',
+    'sdk'
+]);
 const SDK_RUNTIME_SOURCE_PRIVATE_SEGMENTS=new Set([
     'node_modules','.git','.hg','.svn','cvs'
 ]);
@@ -126,7 +131,7 @@ async function canonicalRealDirectory(requested,label){
     return canonical;
 }
 
-function sdkRuntimeSourcePathAllowed(relative,{arcaneRoot=false}={}){
+function sdkRuntimeSourcePathAllowed(relative,{arcaneRoots=null}={}){
     if(relative.length===0)return false;
     const normalized=relative.map(function normalizeRuntimeSourceSegment(segment){
         return segment.normalize('NFC').toLowerCase();
@@ -135,11 +140,15 @@ function sdkRuntimeSourcePathAllowed(relative,{arcaneRoot=false}={}){
         return segment.startsWith('.')||SDK_RUNTIME_SOURCE_PRIVATE_SEGMENTS.has(segment)
             ||SDK_RUNTIME_SOURCE_PRIVATE_MANIFESTS.has(segment);
     }))return false;
-    return !arcaneRoot||SDK_RUNTIME_SOURCE_ARCANE_ROOTS.has(normalized[0]);
+    return arcaneRoots===null||arcaneRoots.has(normalized[0]);
 }
 
 function sdkArcaneSourcePathAllowed(relative){
-    return sdkRuntimeSourcePathAllowed(relative,{arcaneRoot:true});
+    return sdkRuntimeSourcePathAllowed(relative,{arcaneRoots:SDK_RUNTIME_SOURCE_ARCANE_ROOTS});
+}
+
+function sdkInstalledArcanePathAllowed(relative){
+    return sdkRuntimeSourcePathAllowed(relative,{arcaneRoots:SDK_INSTALLED_ARCANE_ROOTS});
 }
 
 function sdkDependencySourcePathAllowed(relative){
@@ -418,7 +427,7 @@ async function sourceRoutes(workspaceRoot,appId,{
             {
                 prefix:['arcane'],
                 root:runtimeRoot,
-                allow:sdkArcaneSourcePathAllowed
+                allow:sdkInstalledArcanePathAllowed
             }
         ]
     };

package/src/installed-sdk-runtime.mjs

@@ -1,7 +1,8 @@
-import {readFile,realpath,stat} from 'node:fs/promises';
+import {lstat,readFile,realpath,stat,writeFile} from 'node:fs/promises';
 import path from 'node:path';
 import {materializeWorkspaceRuntimeContent} from './workspace-runtime.mjs';
 import {withWorkspaceOperationLock} from './workspace-operation-lock.mjs';
+import {createWorkspaceLockDocument} from './templates/workspace-template.mjs';
 import {
     resolveInstalledSdkInstallation,
     resolveSdkPackageDeclaration
@@ -55,6 +56,18 @@ async function installedSdkAuthority(canonicalRoot,{sdkPackageSource}={}){
     return {declaration,installation};
 }
 
+async function writeWorkspaceLock(lockPath,lock){
+    try{
+        const info=await lstat(lockPath);
+        if(info.isSymbolicLink()||!info.isFile()){
+            fail(`Workspace SDK lock must be a real file: ${lockPath}.`);
+        }
+    }catch(error){
+        if(error?.code!=='ENOENT')throw error;
+    }
+    await writeFile(lockPath,`${JSON.stringify(lock,null,2)}\n`,'utf8');
+}
+
 export async function materializeInstalledSdkRuntime({
     workspaceRoot,
     sdkPackageSource,
@@ -79,12 +92,21 @@ export async function materializeInstalledSdkRuntime({
             signal,
             onEvent
         });
+        const lockPath=path.join(canonicalRoot,'arcane.lock.json');
+        const lock=createWorkspaceLockDocument({
+            dependencyName:authority.installation.dependencyName,
+            packageName:authority.installation.packageName,
+            packageVersion:authority.installation.packageVersion,
+            packageSource:authority.installation.packageSource
+        });
+        await writeWorkspaceLock(lockPath,lock);
         return {
             schemaVersion:1,
             kind:'arcane-installed-sdk-runtime-materialization',
             status:'materialized',
             installation:authority.installation,
-            workspaceRuntime
+            workspaceRuntime,
+            workspaceLock:{path:lockPath,document:lock}
         };
     });
 }

package/src/mail-server.mjs

@@ -19,6 +19,7 @@ const PREFLIGHT_HEADERS=new Set([
 ]);
 const PERMANENT_RATE_CODES=new Set(['daily_quota_exceeded','monthly_quota_exceeded']);
 const RETRYABLE_PROVIDER_STATUSES=new Set([408,425,429,500,502,503,504]);
+const MAX_NODE_TIMER_DELAY_MS=2_147_483_647;
 
 class MailGatewayFault extends Error {
     constructor(code,{details=null,retryable=false,retryAfterMs=0,statusCode=400,uncertain=false}={}){
@@ -61,9 +62,15 @@ function positiveInteger(value,fallback,{label,allowZero=false}={}){
     return resolved;
 }
 
-function optionalPositiveInteger(value,label){
+function optionalTimerDelay(value,label){
     if(value===undefined||value===null) return null;
-    return positiveInteger(value,null,{label});
+    if(!Number.isSafeInteger(value)||value<1||value>MAX_NODE_TIMER_DELAY_MS){
+        throw configurationError(
+            `${label} must be an integer from 1 through ${MAX_NODE_TIMER_DELAY_MS} `
+            +'milliseconds, the Node timer range.'
+        );
+    }
+    return value;
 }
 
 function normalizeRetryAfter(value){
@@ -248,7 +255,7 @@ function normalizeConfiguration(options={}){
         apiKey:validateApiKey(options.apiKey),
         appKeyDigest:callerAuthentication.appKeyDigest,
         appId:validateAppId(options.appId),
-        bodyTimeoutMs:optionalPositiveInteger(options.bodyTimeoutMs,'bodyTimeoutMs'),
+        bodyTimeoutMs:optionalTimerDelay(options.bodyTimeoutMs,'bodyTimeoutMs'),
         errorRecipients,
         fetchImpl,
         from:validateFrom(options.from),
@@ -256,7 +263,7 @@ function normalizeConfiguration(options={}){
         callerAuthentication:callerAuthentication.callerAuthentication,
         onEvent:options.onEvent,
         port:portNumber(options.port,8025),
-        providerTimeoutMs:optionalPositiveInteger(options.providerTimeoutMs,'providerTimeoutMs'),
+        providerTimeoutMs:optionalTimerDelay(options.providerTimeoutMs,'providerTimeoutMs'),
         requestIdFactory:options.requestIdFactory??randomUUID,
         retryableDelayMs:positiveInteger(
             options.retryableDelayMs,
@@ -968,7 +975,7 @@ function normalizeDirectSendOptions(options){
         errorRecipients:[],
         fetchImpl,
         from:validateFrom(options.from),
-        providerTimeoutMs:optionalPositiveInteger(options.providerTimeoutMs,'providerTimeoutMs'),
+        providerTimeoutMs:optionalTimerDelay(options.providerTimeoutMs,'providerTimeoutMs'),
         requestIdFactory:options.requestIdFactory??randomUUID,
         retryableDelayMs:positiveInteger(
             options.retryableDelayMs,

package/src/mail.mjs

@@ -40,13 +40,16 @@ function dependency(options,name,fallback){
 }
 
 function recipientList(value,label){
+    if(value===undefined||value===null||value===''||(Array.isArray(value)&&value.length===0)){
+        return [];
+    }
     const entries=Array.isArray(value)
         ? value
         : typeof value==='string'
             ? value.split(',')
             : null;
-    if(!entries||entries.length===0||entries.length>50){
-        usage(`${label} must contain one to 50 comma-separated email addresses.`);
+    if(!entries||entries.length===0){
+        usage(`${label} must contain at least one email address when supplied.`);
     }
     const result=entries.map(function normalizeMailRecipient(entry){
         if(typeof entry!=='string'||!entry.trim()){
@@ -111,21 +114,24 @@ async function deleteCredential(options){
     return remove(credentialOptions(options));
 }
 
-function safeSendFailure(result){
-    return {
-        provider:'resend',
-        status:result.status,
-        classification:result.classification,
-        requestId:result.requestId,
-        providerStatus:result.providerStatus,
-        recipientCount:result.recipientCount,
-        retryable:result.retryable===true,
-        uncertain:result.uncertain===true,
-        ...(typeof result.code==='string'?{code:result.code}:{}),
-        ...(Number.isSafeInteger(result.retryAfterMs)&&result.retryAfterMs>0
-            ?{retryAfterMs:result.retryAfterMs}
-            :{})
-    };
+function withoutMailCredentials(value,seen=new WeakMap()){
+    if(!value||typeof value!=='object')return value;
+    if(seen.has(value))return seen.get(value);
+    const copy=Array.isArray(value)?[]:{};
+    seen.set(value,copy);
+    for(const [key,entry] of Object.entries(value)){
+        if(key==='apiKey'||key==='appKey')continue;
+        copy[key]=withoutMailCredentials(entry,seen);
+    }
+    return copy;
+}
+
+function completeSendFailure(result){
+    if(!result||typeof result!=='object'||Array.isArray(result)){
+        return {provider:'resend',result:withoutMailCredentials(result)};
+    }
+    // Complete provider detail remains visible; only credential fields are omitted.
+    return withoutMailCredentials(result);
 }
 
 async function sendMail(options){
@@ -164,9 +170,9 @@ async function sendMail(options){
             signal:options.signal
         });
         if(result?.classification==='accepted'&&result.status==='accepted'){
-            return result;
+            return withoutMailCredentials(result);
         }
-        const details=safeSendFailure(result||{});
+        const details=completeSendFailure(result);
         throw new ArcaneError(
             ERROR_CODES.operationFailed,
             `Resend did not authoritatively accept the mail request (${details.classification||'unknown'}).`,

package/src/packager/core.mjs

@@ -499,16 +499,23 @@ async function collectPackageRecords(context,{signal}={}){
     return records;
 }
 
-async function browserDocuments(records){
+async function browserDocuments(records,entry){
+    let entryDocument=null;
     const documents=[];
     for(const record of records){
-        if(path.posix.extname(record.destination).toLocaleLowerCase('en-US')!=='.html')continue;
+        const extension=path.posix.extname(record.destination).toLocaleLowerCase('en-US');
+        if(extension!=='.html'&&extension!=='.htm')continue;
         const inspected=inspectImportMapHtml(await readFile(record.source,'utf8'),{
             documentPath:record.destination
         });
-        documents.push({path:record.destination,...copyJson(inspected)});
+        const document={path:record.destination,...copyJson(inspected)};
+        if(record.destination===entry){
+            entryDocument=document;
+        }else if(inspected.bases.length>0){
+            documents.push(document);
+        }
     }
-    return documents;
+    return entryDocument===null?documents:[entryDocument,...documents];
 }
 
 async function optionalDescriptor(context){
@@ -540,7 +547,7 @@ async function inspectContext(context,{signal}={}){
         }),
         ...(context.config.adapter===undefined?{}:{adapter:context.config.adapter}),
         descriptor:await optionalDescriptor(context),
-        browserDocuments:await browserDocuments(records),
+        browserDocuments:await browserDocuments(records,context.config.entry),
         files:records.map(record=>record.destination),
         output:path.relative(context.workspaceRoot,context.outputRoot).split(path.sep).join('/')
     };

package/src/scaffold.mjs

@@ -430,6 +430,25 @@ export async function initWorkspace({
             sdkDeclaration
         );
     const writtenFiles=await writeMissingFiles(resolvedRoot,template.files,{signal,onEvent});
+    if(workspaceMode==='external'&&writtenFiles.skippedFiles.includes('arcane.lock.json')){
+        throwIfAborted(signal);
+        await assertNoLinkedAncestors(resolvedRoot,'arcane.lock.json');
+        const lockPath=path.join(resolvedRoot,'arcane.lock.json');
+        const lockInfo=await lstat(lockPath);
+        if(lockInfo.isSymbolicLink()||!lockInfo.isFile()){
+            fail('Existing arcane.lock.json must be a real file.');
+        }
+        await writeFile(
+            lockPath,
+            template.files.get('arcane.lock.json'),
+            'utf8'
+        );
+        writtenFiles.skippedFiles=writtenFiles.skippedFiles.filter(
+            relative=>relative!=='arcane.lock.json'
+        );
+        writtenFiles.replacedFiles=['arcane.lock.json'];
+        await emit(onEvent,{type:'scaffold.file.replaced',path:'arcane.lock.json'});
+    }
     const packageUpdated=await applyPackageMerge(resolvedRoot,packagePlan,{signal,onEvent});
     const workspaceRuntime=workspaceMode==='external'
         ?await materializeWorkspaceRuntimeContent({

package/src/templates/workspace-template.mjs

@@ -1,4 +1,10 @@
-import {SDK_NAME,SDK_VERSION} from '../constants.mjs';
+import {
+    ARCANE_PROTOCOL,
+    CLI_EVENT_PROTOCOL,
+    SDK_NAME,
+    SDK_VERSION,
+    TARGET_ADAPTER_PROTOCOL
+} from '../constants.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;
@@ -22,6 +28,32 @@ function titleCase(appId){
         .join(' ');
 }
 
+export function createWorkspaceLockDocument({
+    dependencyName=SDK_NAME,
+    packageName=SDK_NAME,
+    packageVersion=SDK_VERSION,
+    packageSource=`node_modules/${dependencyName}`
+}={}){
+    if(packageName!==SDK_NAME||typeof packageVersion!=='string'
+        ||!/^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/u.test(packageVersion)
+        ||typeof dependencyName!=='string'||dependencyName.length>214
+        ||!NPM_PACKAGE_NAME_PATTERN.test(dependencyName)
+        ||packageSource!==`node_modules/${dependencyName}`){
+        throw new Error('Invalid workspace SDK lock authority.');
+    }
+    return {
+        schemaVersion:1,
+        sdk:{name:packageName,version:packageVersion},
+        runtime:{root:`${packageSource}/runtime`},
+        sdkBrowserRuntime:{root:`${packageSource}/browser-runtime`},
+        protocols:{
+            arcane:ARCANE_PROTOCOL,
+            cliEvents:CLI_EVENT_PROTOCOL,
+            targetAdapter:TARGET_ADAPTER_PROTOCOL
+        }
+    };
+}
+
 export function workspaceTemplate({
     appId,
     displayName,
@@ -212,6 +244,10 @@ Every browser release also carries Arcane OS licensing material under \`licenses
             ]
         }
     }));
+    files.set('arcane.lock.json',json(createWorkspaceLockDocument({
+        dependencyName:sdkDependencyName,
+        packageSource:sdkPackageSource
+    })));
     files.set(`apps/${appId}/arcane-app.json`,json({
         schemaVersion:2,
         id:appId,

package/src/toolchain.mjs

@@ -314,7 +314,9 @@ async function refreshPreparedImportMap(prepared,{signal,onEvent,workspaceOperat
         appId:prepared.appId,
         appRoot:prepared.appRoot,
         entry:manifest.entry,
-        documents:inspected.browserDocuments,
+        documents:inspected.browserDocuments.map(function selectBrowserDocumentPath(document){
+            return document.path;
+        }),
         workspaceOperationLease,
         signal,
         onEvent

package/src/workspace.mjs

@@ -94,6 +94,18 @@ function dependencyNameForSdkPackageSource(source){
     }
 }
 
+function routeIncludeMatches(actual,wanted,optionalSecurity){
+    if(!Array.isArray(actual)||!Array.isArray(wanted))return false;
+    if(actual.length===wanted.length
+        &&actual.every(function sameIncludedPath(value,index){return value===wanted[index];})){
+        return true;
+    }
+    return optionalSecurity
+        &&wanted.at(-1)==='security'
+        &&actual.length===wanted.length-1
+        &&actual.every(function sameFunctionalPath(value,index){return value===wanted[index];});
+}
+
 export function resolveSdkPackageDeclaration(rootPackage,{
     allowMissing=false,
     packageSource
@@ -179,19 +191,30 @@ function classifyRootConfig(config){
             include:['index.js','licence','package.json']
         }
     ];
-    const matches=expected=>routes.length===expected.length&&routes.every((route,index)=>{
-        const wanted=expected[index];
-        return isObject(route)&&Object.keys(route).every(key=>['source','destination','include','exclude'].includes(key))
-            &&route.source===wanted.source&&route.destination===wanted.destination
-            &&JSON.stringify(route.include)===JSON.stringify(wanted.include)
-            &&Array.isArray(route.exclude)&&route.exclude.length===0;
-    });
+    const matches=(expected,{optionalArcaneSecurity=false}={})=>{
+        if(routes.length!==expected.length)return false;
+        return routes.every(function routeMatches(route,index){
+            const wanted=expected[index];
+            return isObject(route)
+                &&Object.keys(route).every(function knownRouteKey(key){
+                    return ['source','destination','include','exclude'].includes(key);
+                })
+                &&route.source===wanted.source&&route.destination===wanted.destination
+                &&routeIncludeMatches(
+                    route.include,
+                    wanted.include,
+                    optionalArcaneSecurity&&index===0
+                        &&wanted.source==='arcane'&&wanted.destination==='arcane'
+                )
+                &&Array.isArray(route.exclude)&&route.exclude.length===0;
+        });
+    };
     let workspaceMode;
     let browserRuntimeLayout;
-    if(matches(external)){
+    if(matches(external,{optionalArcaneSecurity:true})){
         workspaceMode='external';
         browserRuntimeLayout='physical-v1';
-    }else if(matches(integrated)){
+    }else if(matches(integrated,{optionalArcaneSecurity:true})){
         workspaceMode='integrated';
         browserRuntimeLayout='physical-v1';
     }else if(matches(integratedLegacy)){