arcane-os 0.1.0-dev.5

package/runtime/arcane/modules/BrowserTestSuite.js

@@ -0,0 +1,326 @@
+const DEFAULT_MAX_TESTS=64;
+const HARD_MAX_TESTS=256;
+const DEFAULT_TIMEOUT_MS=5000;
+const HARD_TIMEOUT_MS=60000;
+const MAX_MESSAGE_CHARACTERS=1000;
+const CONTROL_CHARACTERS=/[\u0000-\u001f\u007f]/;
+const TEST_ID_PATTERN=/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const RESULT_STATUSES=new Set(['fail','pass','skip']);
+
+function isPlainRecord(value){
+    return Boolean(value)
+        &&typeof value==='object'
+        &&!Array.isArray(value)
+        &&Object.getPrototypeOf(value)===Object.prototype;
+}
+
+function coded(error,code){
+    if(!error.code) error.code=code;
+    return error;
+}
+
+function fail(message,code,ErrorType=TypeError){
+    throw coded(new ErrorType(message),code);
+}
+
+function knownKeys(value,allowed,label,code='BROWSER_TEST_INVALID_OPTIONS'){
+    const unknown=Object.keys(value).find(key=>!allowed.has(key));
+    if(unknown) fail(`${label} contains an unsupported field: ${unknown}.`,code);
+}
+
+function boundedInteger(value,label,{minimum,maximum}){
+    if(!Number.isSafeInteger(value)||value<minimum||value>maximum){
+        fail(`${label} must be an integer from ${minimum} through ${maximum}.`,'BROWSER_TEST_INVALID_LIMIT',RangeError);
+    }
+    return value;
+}
+
+function descriptorText(value,label,maximum){
+    if(typeof value!=='string') fail(`${label} must be a string.`,'BROWSER_TEST_INVALID_DESCRIPTOR');
+    const normalized=value.trim();
+    if(!normalized) fail(`${label} cannot be empty.`,'BROWSER_TEST_INVALID_DESCRIPTOR');
+    if(normalized.length>maximum) fail(`${label} exceeds ${maximum} characters.`,'BROWSER_TEST_INVALID_DESCRIPTOR',RangeError);
+    if(CONTROL_CHARACTERS.test(normalized)) fail(`${label} cannot contain control characters.`,'BROWSER_TEST_INVALID_DESCRIPTOR');
+    if(normalized!==normalized.normalize('NFC')) fail(`${label} must use Unicode NFC normalization.`,'BROWSER_TEST_INVALID_DESCRIPTOR');
+    return normalized;
+}
+
+function resultMessage(value,fallback){
+    if(value===undefined||value===null||value==='') return fallback;
+    const message=String(value)
+        .replace(/[\u0000-\u001f\u007f]+/g,' ')
+        .trim();
+    return (message||fallback).slice(0,MAX_MESSAGE_CHARACTERS);
+}
+
+function normalizeTests(value,{maxTests,timeoutMs}){
+    if(!Array.isArray(value)) fail('tests must be an array.','BROWSER_TEST_INVALID_OPTIONS');
+    if(value.length>maxTests) fail(`Test suite exceeds the ${maxTests}-test limit.`,'BROWSER_TEST_LIMIT',RangeError);
+    const seen=new Set();
+    return Object.freeze(value.map((item,index)=>{
+        if(!isPlainRecord(item)) fail(`Test descriptor ${index+1} must be a plain object.`,'BROWSER_TEST_INVALID_DESCRIPTOR');
+        knownKeys(item,new Set(['id','name','run','timeoutMs']),`Test descriptor ${index+1}`,'BROWSER_TEST_INVALID_DESCRIPTOR');
+        const id=descriptorText(item.id,`Test descriptor ${index+1} id`,128);
+        if(!TEST_ID_PATTERN.test(id)) fail(`Test descriptor ${index+1} has an invalid id.`,'BROWSER_TEST_INVALID_DESCRIPTOR');
+        const key=id.toLowerCase();
+        if(seen.has(key)) fail(`Test descriptors contain a case-colliding id: ${id}.`,'BROWSER_TEST_CASE_COLLISION');
+        seen.add(key);
+        if(typeof item.run!=='function') fail(`Test descriptor ${index+1} run must be a function.`,'BROWSER_TEST_INVALID_DESCRIPTOR');
+        return Object.freeze({
+            id,
+            name:descriptorText(item.name,`Test descriptor ${index+1} name`,256),
+            run:item.run,
+            timeoutMs:boundedInteger(item.timeoutMs??timeoutMs,`Test descriptor ${index+1} timeoutMs`,{minimum:10,maximum:timeoutMs}),
+        });
+    }));
+}
+
+function defaultNow(){
+    return globalThis.performance?.now?.()??Date.now();
+}
+
+function normalizeOptions(input){
+    if(!isPlainRecord(input)) fail('Browser test suite options must be a plain object.','BROWSER_TEST_INVALID_OPTIONS');
+    knownKeys(input,new Set(['maxTests','now','tests','timeoutMs']),'Browser test suite options');
+    const maxTests=boundedInteger(input.maxTests??DEFAULT_MAX_TESTS,'maxTests',{minimum:1,maximum:HARD_MAX_TESTS});
+    const timeoutMs=boundedInteger(input.timeoutMs??DEFAULT_TIMEOUT_MS,'timeoutMs',{minimum:10,maximum:HARD_TIMEOUT_MS});
+    const now=input.now??defaultNow;
+    if(typeof now!=='function') fail('now must be a function.','BROWSER_TEST_INVALID_OPTIONS');
+    return Object.freeze({
+        maxTests,
+        now,
+        tests:normalizeTests(input.tests??[],{maxTests,timeoutMs}),
+        timeoutMs,
+    });
+}
+
+function normalizeRunOptions(input){
+    if(!isPlainRecord(input)) fail('Test run options must be a plain object.','BROWSER_TEST_INVALID_OPTIONS');
+    knownKeys(input,new Set(['context','signal']),'Test run options');
+    const signal=input.signal??null;
+    if(signal!==null&&(
+        typeof signal!=='object'
+        ||typeof signal.aborted!=='boolean'
+        ||typeof signal.addEventListener!=='function'
+        ||typeof signal.removeEventListener!=='function'
+    )) fail('signal must be an AbortSignal.','BROWSER_TEST_INVALID_OPTIONS');
+    return Object.freeze({context:input.context,signal});
+}
+
+function detailEvent(type,detail){
+    if(typeof globalThis.CustomEvent==='function') return new CustomEvent(type,{detail});
+    const event=new Event(type);
+    Object.defineProperty(event,'detail',{enumerable:true,value:detail});
+    return event;
+}
+
+function elapsed(now,start){
+    const end=Number(now());
+    if(!Number.isFinite(end)) fail('now() must return a finite number.','BROWSER_TEST_INVALID_CLOCK');
+    return Math.round(Math.max(0,end-start)*1000)/1000;
+}
+
+function startTime(now){
+    const value=Number(now());
+    if(!Number.isFinite(value)) fail('now() must return a finite number.','BROWSER_TEST_INVALID_CLOCK');
+    return value;
+}
+
+function skipError(message){
+    const error=coded(new Error(resultMessage(message,'Skipped by the check.')),'BROWSER_TEST_SKIP');
+    error.name='BrowserTestSkip';
+    return error;
+}
+
+function assertionError(message){
+    const error=coded(new Error(resultMessage(message,'The browser check failed.')),'BROWSER_TEST_ASSERTION');
+    error.name='BrowserTestAssertionError';
+    return error;
+}
+
+function abortError(){
+    const error=coded(new Error('The browser test run was aborted.'),'BROWSER_TEST_ABORTED');
+    error.name='AbortError';
+    return error;
+}
+
+function timeoutError(milliseconds){
+    const error=coded(new Error(`The check exceeded ${milliseconds} milliseconds.`),'BROWSER_TEST_TIMEOUT');
+    error.name='BrowserTestTimeoutError';
+    return error;
+}
+
+function runWithTimeout(callback,{signal,timeoutMs}){
+    if(signal?.aborted) return Promise.reject(abortError());
+    const controller=new AbortController();
+    return new Promise((resolve,reject)=>{
+        let settled=false;
+        const finish=(handler,value)=>{
+            if(settled) return;
+            settled=true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort',onAbort);
+            handler(value);
+        };
+        const onAbort=()=>{
+            controller.abort();
+            finish(reject,abortError());
+        };
+        const timer=setTimeout(()=>{
+            controller.abort();
+            finish(reject,timeoutError(timeoutMs));
+        },timeoutMs);
+        signal?.addEventListener('abort',onAbort,{once:true});
+        Promise.resolve()
+            .then(()=>callback(controller.signal))
+            .then(value=>finish(resolve,value),error=>finish(reject,error));
+    });
+}
+
+function normalizedOutcome(value){
+    if(value===undefined||value===true){
+        return Object.freeze({status:'pass',message:'Passed.'});
+    }
+    if(value===false){
+        return Object.freeze({status:'fail',message:'The check returned false.',code:'BROWSER_TEST_ASSERTION'});
+    }
+    if(!isPlainRecord(value)){
+        return Object.freeze({status:'fail',message:'The check returned an invalid result.',code:'BROWSER_TEST_INVALID_RESULT'});
+    }
+    const unknown=Object.keys(value).find(key=>!new Set(['message','status']).has(key));
+    if(unknown||!RESULT_STATUSES.has(value.status)){
+        return Object.freeze({status:'fail',message:'The check returned an invalid result.',code:'BROWSER_TEST_INVALID_RESULT'});
+    }
+    const fallback=value.status==='pass'?'Passed.':value.status==='skip'?'Skipped.':'Failed.';
+    return Object.freeze({status:value.status,message:resultMessage(value.message,fallback)});
+}
+
+function outcomeFromError(error){
+    if(error?.code==='BROWSER_TEST_SKIP'){
+        return Object.freeze({status:'skip',message:resultMessage(error.message,'Skipped.'),code:error.code});
+    }
+    if(error?.code==='BROWSER_TEST_ABORTED'){
+        return Object.freeze({status:'skip',message:resultMessage(error.message,'The run was aborted.'),code:error.code});
+    }
+    return Object.freeze({
+        status:'fail',
+        message:resultMessage(error?.message,'The check failed.'),
+        code:typeof error?.code==='string'?error.code.slice(0,64):'BROWSER_TEST_ERROR',
+        errorName:resultMessage(error?.name,'Error').slice(0,128),
+    });
+}
+
+function resultRecord(test,outcome,durationMs){
+    return Object.freeze({
+        id:test.id,
+        name:test.name,
+        status:outcome.status,
+        message:outcome.message,
+        ...(outcome.code?{code:outcome.code}:{}),
+        ...(outcome.errorName?{errorName:outcome.errorName}:{}),
+        durationMs,
+    });
+}
+
+function skippedResult(test,message,code='BROWSER_TEST_ABORTED'){
+    return resultRecord(test,{status:'skip',message,code},0);
+}
+
+/**
+ * Runs a fixed inventory of parent-supplied browser checks sequentially.
+ *
+ * Test callbacks are trusted executable code supplied by the parent. This
+ * module never accepts source text, evaluates code, persists results, or
+ * selects application policy. Per-test abort signals and timeout races bound
+ * cooperative asynchronous orchestration; callbacks must still avoid blocking
+ * the page and stop work they started after their abort signal fires.
+ */
+export default class BrowserTestSuite extends EventTarget{
+    #now;
+    #running=false;
+    #tests;
+
+    constructor(options={}){
+        super();
+        const normalized=normalizeOptions(options);
+        this.#now=normalized.now;
+        this.#tests=normalized.tests;
+    }
+
+    get running(){return this.#running;}
+
+    list(){
+        return Object.freeze(this.#tests.map(test=>Object.freeze({
+            id:test.id,
+            name:test.name,
+            timeoutMs:test.timeoutMs,
+        })));
+    }
+
+    #emit(type,detail){
+        this.dispatchEvent(detailEvent(type,Object.freeze(detail)));
+    }
+
+    async run(options={}){
+        if(this.#running) fail('A browser test run is already active.','BROWSER_TEST_BUSY',Error);
+        const settings=normalizeRunOptions(options);
+        const suiteStart=startTime(this.#now);
+        const results=[];
+        let aborted=Boolean(settings.signal?.aborted);
+        this.#running=true;
+        this.#emit('browser-test-suite-start',{tests:this.list(),total:this.#tests.length});
+        try{
+            for(let index=0;index<this.#tests.length;index++){
+                const descriptor=this.#tests[index];
+                if(aborted||settings.signal?.aborted){
+                    aborted=true;
+                    const result=skippedResult(descriptor,'Skipped because the browser test run was aborted.');
+                    results.push(result);
+                    this.#emit('browser-test-result',{index,result,total:this.#tests.length});
+                    continue;
+                }
+                this.#emit('browser-test-start',{
+                    index,
+                    test:Object.freeze({id:descriptor.id,name:descriptor.name,timeoutMs:descriptor.timeoutMs}),
+                    total:this.#tests.length,
+                });
+                const testStart=startTime(this.#now);
+                let outcome;
+                try{
+                    const value=await runWithTimeout(signal=>descriptor.run(Object.freeze({
+                        assert(condition,message){if(!condition) throw assertionError(message);},
+                        context:settings.context,
+                        signal,
+                        skip(message){throw skipError(message);},
+                    })),{signal:settings.signal,timeoutMs:descriptor.timeoutMs});
+                    outcome=normalizedOutcome(value);
+                }catch(error){
+                    outcome=outcomeFromError(error);
+                    if(error?.code==='BROWSER_TEST_ABORTED') aborted=true;
+                }
+                const result=resultRecord(descriptor,outcome,elapsed(this.#now,testStart));
+                results.push(result);
+                this.#emit('browser-test-result',{index,result,total:this.#tests.length});
+            }
+        }finally{
+            this.#running=false;
+        }
+        const totals=Object.freeze({
+            total:results.length,
+            pass:results.filter(result=>result.status==='pass').length,
+            fail:results.filter(result=>result.status==='fail').length,
+            skip:results.filter(result=>result.status==='skip').length,
+        });
+        const status=aborted?'aborted':totals.fail?'fail':totals.pass?'pass':'skip';
+        const summary=Object.freeze({
+            status,
+            totals,
+            durationMs:elapsed(this.#now,suiteStart),
+            results:Object.freeze(results),
+        });
+        this.#emit('browser-test-suite-complete',summary);
+        return summary;
+    }
+}
+
+export {assertionError,skipError};

package/runtime/arcane/modules/CalculatorEngine.js

@@ -0,0 +1,20 @@
+import Calculation from '../entities/Calculation.js';
+
+const FUNCTIONS=Object.freeze({sqrt:Math.sqrt,abs:Math.abs,sin:Math.sin,cos:Math.cos,tan:Math.tan,log:Math.log10,ln:Math.log});
+const CONSTANTS=Object.freeze({pi:Math.PI,e:Math.E});
+
+function tokenize(input){const source=String(input??'').trim();if(!source||source.length>512)throw new TypeError('Expression must contain 1-512 characters.');const tokens=[];let index=0;while(index<source.length){const rest=source.slice(index);const whitespace=rest.match(/^\s+/);if(whitespace){index+=whitespace[0].length;continue}const numeric=rest.match(/^(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?/i);if(numeric){tokens.push({type:'number',value:Number(numeric[0])});index+=numeric[0].length;continue}const identifier=rest.match(/^[a-z]+/i);if(identifier){tokens.push({type:'name',value:identifier[0].toLowerCase()});index+=identifier[0].length;continue}const symbol=source[index];if('+-*/%^()'.includes(symbol)){tokens.push({type:symbol,value:symbol});index++;continue}throw new SyntaxError(`Unexpected character at position ${index+1}.`)}tokens.push({type:'end'});return tokens;}
+
+export function evaluateExpression(input){const tokens=tokenize(input);let cursor=0;const peek=()=>tokens[cursor];const take=type=>{if(peek().type!==type)throw new SyntaxError(`Expected ${type}.`);return tokens[cursor++]};
+    function primary(){const token=peek();if(token.type==='number'){cursor++;return token.value}if(token.type==='name'){cursor++;if(Object.hasOwn(CONSTANTS,token.value))return CONSTANTS[token.value];const fn=FUNCTIONS[token.value];if(!fn)throw new SyntaxError(`Unknown function: ${token.value}.`);take('(');const value=expression();take(')');return fn(value)}if(token.type==='('){cursor++;const value=expression();take(')');return value}throw new SyntaxError('Expected a number, constant, function, or parenthesized expression.')}
+    function unary(){if(peek().type==='+'){cursor++;return unary()}if(peek().type==='-'){cursor++;return -unary()}return primary()}
+    function power(){let value=unary();if(peek().type==='^'){cursor++;value=Math.pow(value,power())}return value}
+    function product(){let value=power();while(['*','/','%'].includes(peek().type)){const operator=tokens[cursor++].type,right=power();if((operator==='/'||operator==='%')&&right===0)throw new RangeError('Division by zero is undefined.');value=operator==='*'?value*right:operator==='/'?value/right:value%right}return value}
+    function expression(){let value=product();while(['+','-'].includes(peek().type)){const operator=tokens[cursor++].type,right=product();value=operator==='+'?value+right:value-right}return value}
+    const result=expression();if(peek().type!=='end')throw new SyntaxError('Unexpected content after the expression.');if(!Number.isFinite(result))throw new RangeError('The calculation did not produce a finite result.');return result;
+}
+
+export default class CalculatorEngine extends EventTarget{
+    calculate(expression){try{const calculation=new Calculation({expression,result:evaluateExpression(expression)});this.dispatchEvent(event('calculator-result',calculation));return calculation}catch(error){this.dispatchEvent(event('calculator-error',{expression:String(expression??''),error}));throw error}}
+}
+function event(type,detail){return new CustomEvent(type,{detail});}

package/runtime/arcane/modules/CaseEvidenceIndexer.js

@@ -0,0 +1,134 @@
+import {createHash} from 'node:crypto';
+import {readdir,readFile,writeFile,mkdir} from 'node:fs/promises';
+import path from 'node:path';
+
+const sha256=bytes=>createHash('sha256').update(bytes).digest('hex');
+const natural=(a,b)=>a.localeCompare(b,undefined,{numeric:true,sensitivity:'base'});
+const stem=value=>value.replace(/\.[^.]+$/,'');
+const safeName=value=>value.replace(/[<>:"/\\|?*\x00-\x1f]/g,' ').replace(/\s+/g,' ').trim();
+
+function parseStructuredRecordName(name,{
+  pattern=/^(?<date>\d{2}-\d{2}-\d{2})\s+\[(?<source>[^\]]+)\]\s+-\s+(?<title>.+?)(?<extension>\.[^.]+)$/
+}={}){
+  const match=String(name||'').match(pattern);
+  if(!match?.groups) return null;
+  const [year,month,day]=match.groups.date.split('-').map(Number);
+  const isoDate=`20${String(year).padStart(2,'0')}-${String(month).padStart(2,'0')}-${String(day).padStart(2,'0')}`;
+  const parsedDate=new Date(`${isoDate}T00:00:00Z`);
+  const dateValid=parsedDate.getUTCFullYear()===2000+year&&parsedDate.getUTCMonth()+1===month&&parsedDate.getUTCDate()===day;
+  return {
+    dateToken:match.groups.date,
+    isoDate:dateValid?isoDate:null,
+    source:safeName(match.groups.source),
+    title:safeName(match.groups.title),
+    extension:match.groups.extension.toLowerCase()
+  };
+}
+
+function nearestPageMarker(text,index,pattern=/^#{1,6}\s+(?:Page|PDF Page)\s+(\d+)\b/gim){
+  const matches=[...text.slice(0,index).matchAll(pattern)];
+  return matches.length?Number(matches.at(-1)[1]):null;
+}
+
+function normalizeEvidenceLabel(value=''){
+  return String(value)
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g,'')
+    .replace(/[\u2018\u2019']/g,'')
+    .replace(/[^a-z0-9.]+/gi,' ')
+    .trim()
+    .toLowerCase();
+}
+
+function evidenceLabelTargets(title=''){
+  const value=String(title||'').trim();
+  const targets=new Set([normalizeEvidenceLabel(value)].filter(Boolean));
+  const label=value.match(/\b(Exhibit|Attachment)\s+([A-Za-z0-9]+(?:\.[A-Za-z0-9]+)?)/i);
+  const qualified=/\b(?:Petitioner|Respondent)(?:['\u2019]s)?\s+(?:Exhibit|Attachment)\b/i.test(value);
+  if(label&&!qualified&&(/^[A-Za-z]{1,3}(?:\.\d+)?$/.test(label[2])||/^\d+$/.test(label[2]))){
+    targets.add(normalizeEvidenceLabel(`${label[1]} ${label[2]}`));
+  }
+  return [...targets];
+}
+
+function renderedPageBlocks(markdown=''){
+  const text=String(markdown||'');
+  const markerPattern=/_rendered_pages[\\/][^\r\n]*?[\\/]page-(\d+)\.png\b/gi;
+  const markers=[...text.matchAll(markerPattern)]
+    .map(match=>({page:Number(match[1]),marker:match[0],index:match.index}))
+    .filter(item=>Number.isSafeInteger(item.page)&&item.page>0);
+  return markers.map((item,index)=>({
+    ...item,
+    end:markers[index+1]?.index??text.length,
+    text:text.slice(item.index,markers[index+1]?.index??text.length)
+  }));
+}
+
+function standaloneEvidenceLabel(line='',targets=[]){
+  let value=normalizeEvidenceLabel(line);
+  value=value.replace(/^\d{2}(?:fl|dv)\d{6}\s+/,'').replace(/^\d{1,3}\s+/,'');
+  return targets.some(target=>value===target||new RegExp(`^${target.replace(/[.*+?^${}()|[\]\\]/g,'\\$&')}\\s+(?:page\\s+)?\\d{1,3}$`,'i').test(value));
+}
+
+function resolveEvidenceSourcePage(markdown='',boundaryIndex=0,title=''){
+  const pages=renderedPageBlocks(markdown);
+  const containing=pages.find(page=>boundaryIndex>=page.index&&boundaryIndex<page.end);
+  if(containing){
+    return {sourcePage:containing.page,sourcePageStatus:'resolved',sourcePageMethod:'containing-rendered-page',sourcePageMarker:containing.marker,sourcePageCandidates:[containing.page]};
+  }
+  const targets=evidenceLabelTargets(title);
+  const candidates=pages.filter(page=>page.text.split(/\r?\n/).some(line=>standaloneEvidenceLabel(line,targets)));
+  const candidatePages=[...new Set(candidates.map(item=>item.page))].sort((left,right)=>left-right);
+  if(candidatePages.length===1){
+    const page=pages.find(item=>item.page===candidatePages[0]);
+    return {sourcePage:page.page,sourcePageStatus:'resolved',sourcePageMethod:'unique-standalone-label',sourcePageMarker:page.marker,sourcePageCandidates:candidatePages};
+  }
+  return {
+    sourcePage:null,
+    sourcePageStatus:candidatePages.length?'ambiguous':'unresolved',
+    sourcePageMethod:candidatePages.length?'multiple-standalone-labels':null,
+    sourcePageMarker:null,
+    sourcePageCandidates:candidatePages
+  };
+}
+
+async function indexPairedRecord({
+  rawRoot,markdownRoot,evidenceOutputRoot,rawExtension='.pdf',
+  evidenceBoundary=/^#{2,6}\s+((?:Exhibit|Attachment)\b[^\r\n]*)/gim,
+  signalRules=[],recordIdPrefix='F',evidenceIdPrefix='E',buildEvidenceMarkdown
+}){
+  if(!rawRoot||!markdownRoot||!evidenceOutputRoot) throw new TypeError('Raw, Markdown, and evidence output roots are required.');
+  await mkdir(evidenceOutputRoot,{recursive:true});
+  const rawNames=(await readdir(rawRoot)).filter(name=>name.toLowerCase().endsWith(rawExtension.toLowerCase())).sort(natural);
+  const markdownNames=(await readdir(markdownRoot)).filter(name=>/\.md$/i.test(name)).sort(natural);
+  const markdownByStem=new Map(markdownNames.map(name=>[stem(name).toLowerCase(),name]));
+  const records=[]; const evidence=[];
+  for(let index=0;index<rawNames.length;index++){
+    const rawName=rawNames[index]; const rawBytes=await readFile(path.join(rawRoot,rawName));
+    const hash=sha256(rawBytes); const markdownName=markdownByStem.get(stem(rawName).toLowerCase())||null;
+    const recordEvidence=[]; let signals=[];
+    if(markdownName){
+      const markdown=await readFile(path.join(markdownRoot,markdownName),'utf8');
+      signals=signalRules.filter(rule=>rule.pattern.test(markdown)).map(rule=>rule.id);
+      evidenceBoundary.lastIndex=0;
+      const boundaries=[...markdown.matchAll(evidenceBoundary)];
+      for(let n=0;n<boundaries.length;n++){
+        const match=boundaries[n]; const body=markdown.slice(match.index,boundaries[n+1]?.index??markdown.length).trim();
+        if(body.length<20) continue;
+        const id=`${evidenceIdPrefix}${String(evidence.length+1).padStart(4,'0')}`;
+        const title=safeName(match[1]); const pageResolution=resolveEvidenceSourcePage(markdown,match.index,title);
+        // Keep generated evidence paths stable and short. Descriptive source and
+        // exhibit labels remain in the record and Markdown instead of the path.
+        const fileName=`${id}.md`;
+        const item={id,title,parentRaw:rawName,markdown:markdownName,...pageResolution,file:`Evidence/MD/${fileName}`,parentSha256:hash,body};
+        const output=buildEvidenceMarkdown?buildEvidenceMarkdown(item):`# ${title}\n\n- Evidence ID: ${id}\n- Parent source: ${rawName}\n- Related Markdown: ${markdownName}\n- Source page: ${item.sourcePage??'not resolved from Markdown'}\n- Source page status: ${item.sourcePageStatus}\n- Source page method: ${item.sourcePageMethod??'none'}\n- Source page marker: ${item.sourcePageMarker??'none'}\n- Source page candidates: ${item.sourcePageCandidates.join(', ')||'none'}\n- Parent SHA-256: ${hash}\n\n${body}\n`;
+        await writeFile(path.join(evidenceOutputRoot,fileName),output,'utf8'); evidence.push(item); recordEvidence.push(id);
+      }
+    }
+    records.push({id:`${recordIdPrefix}${String(index+1).padStart(4,'0')}`,name:rawName,markdown:markdownName,status:markdownName?'paired':'missing-markdown',sha256:hash,size:rawBytes.length,signals,evidence:recordEvidence,reviewStatus:'not-reviewed'});
+  }
+  const rawStems=new Set(rawNames.map(name=>stem(name).toLowerCase()));
+  return {records,evidence,markdownNames,orphanMarkdown:markdownNames.filter(name=>!rawStems.has(stem(name).toLowerCase()))};
+}
+
+export {indexPairedRecord,nearestPageMarker,parseStructuredRecordName,renderedPageBlocks,resolveEvidenceSourcePage,safeName,sha256,stem};

package/runtime/arcane/modules/ChartLibrary.js

@@ -0,0 +1,35 @@
+let libraryPromise=null;
+
+function loadChartLibrary(){
+    if(window.uPlot){
+        return Promise.resolve(window.uPlot);
+    }
+
+    if(libraryPromise){
+        return libraryPromise;
+    }
+
+    libraryPromise=new Promise(
+        function loadChartLibraryPromise(resolve,reject){
+            const script=document.createElement('script');
+
+            script.src=new URL('./uPlot.iife.min.js',import.meta.url).href;
+            script.addEventListener(
+                'load',
+                ()=>window.uPlot
+                    ?resolve(window.uPlot)
+                    :reject(new Error('uPlot did not initialize'))
+            );
+            script.addEventListener(
+                'error',
+                ()=>reject(new Error('Unable to load the chart library'))
+            );
+
+            document.head.append(script);
+        }
+    );
+
+    return libraryPromise;
+}
+
+export default loadChartLibrary;

package/runtime/arcane/modules/ChatRecords.js

@@ -0,0 +1,13 @@
+function hasUserEntry(chat=[]){
+    const messages=Array.isArray(chat)
+        ?chat
+        :chat?.messages||[];
+
+    return messages.some(
+        message=>message?.role==='user'
+    );
+}
+
+export {
+    hasUserEntry
+};

package/runtime/arcane/modules/CommunicationAppController.js

@@ -0,0 +1,43 @@
+import ArcaneCommunicationBridge from './ArcaneCommunicationBridge.js';
+import CommunicationHub from './CommunicationHub.js?v=2';
+import CommunicationPreferences from './CommunicationPreferences.js';
+import {loadAndApplyTheme} from './ThemeManager.js';
+import {inspectMessageRecords,unavailableMessageInspection} from './MessageAdvisory.js?v=3';
+
+function defaults(services){return Object.fromEntries(services.map(item=>[item.id,{enabled:Boolean(item.defaultEnabled),endpoint:item.defaultEndpoint||'http://127.0.0.1:8020',accountLabel:'',status:item.defaultStatus||'Disconnected'}]));}
+function ready(element,event){return element.ready?Promise.resolve(element):new Promise(resolve=>element.addEventListener(event,()=>resolve(element),{once:true}));}
+
+export default class CommunicationAppController{
+    constructor({appId,services,channels,labels={},inspectMessage=null,prepareMessageInspection=null,onAdvisoryAction=null}){this.appId=appId;this.services=services;this.channels=channels;this.labels=labels;this.inspectMessage=typeof inspectMessage==='function'?inspectMessage:null;this.prepareMessageInspection=typeof prepareMessageInspection==='function'?prepareMessageInspection:null;this.onAdvisoryAction=typeof onAdvisoryAction==='function'?onAdvisoryAction:null;this.selectionVersion=0;this.preferences=new CommunicationPreferences(appId);this.values={};this.hub=null;this.active=null;this.elements={inbox:document.querySelector('#inbox'),conversation:document.querySelector('#conversation'),settings:document.querySelector('#integrationSettings'),panel:document.querySelector('#settingsPanel'),status:document.querySelector('#appStatus')};}
+    async start(){
+        loadAndApplyTheme().catch(()=>{});await Promise.all([ready(this.elements.inbox,'unified-inbox-ready'),ready(this.elements.conversation,'conversation-view-ready'),ready(this.elements.settings,'integration-settings-ready')]);
+        this.values=await this.preferences.load(defaults(this.services));this.bind();this.configure();await this.refresh();
+    }
+    bind(){
+        document.querySelector('#openSettings').addEventListener('click',()=>this.openSettings());
+        this.elements.settings.addEventListener('integration-settings-close',()=>this.closeSettings());
+        this.elements.settings.addEventListener('integration-settings-save',event=>this.saveSettings(event.detail.values));
+        this.elements.settings.addEventListener('integration-action',event=>this.action(event.detail.service));
+        this.elements.inbox.addEventListener('inbox-refresh',()=>this.refresh());
+        this.elements.inbox.addEventListener('thread-select',event=>this.select(event.detail.thread));
+        this.elements.conversation.addEventListener('communication-send',event=>this.send(event.detail));
+        this.elements.conversation.addEventListener('communication-advisory-action',event=>this.onAdvisoryAction?.(event.detail));
+        this.elements.panel.addEventListener('click',event=>{if(event.target===this.elements.panel)this.closeSettings()});
+        document.addEventListener('keydown',event=>{if(event.key==='Escape'&&!this.elements.panel.hidden)this.closeSettings()});
+    }
+    configure(){
+        const providers=this.services.map(item=>({id:item.id,label:item.label}));
+        this.elements.inbox.configure({channels:this.channels,providers,threads:[]});
+        this.elements.settings.configure({title:this.labels.settingsTitle||'Connected services',description:this.labels.settingsDescription||'Choose which services appear in this application.',services:this.services,values:this.values});
+        this.rebuildHub();
+    }
+    rebuildHub(){const enabled=this.services.filter(item=>this.values[item.id]?.enabled&&item.unified!==false);const providers=enabled.map(item=>typeof item.providerFactory==='function'?item.providerFactory({service:item,value:this.values[item.id]}):new ArcaneCommunicationBridge({id:item.id,label:item.label,channels:item.channels,endpoint:this.values[item.id].endpoint||item.defaultEndpoint}));this.hub=new CommunicationHub({providers,enabledProviderIds:enabled.map(item=>item.id)});}
+    setStatus(message,tone='muted'){this.elements.status.textContent=String(message||'');this.elements.status.dataset.tone=tone;}
+    async refresh(){this.elements.inbox.setLoading(true);this.setStatus('Refreshing…');try{const {threads,errors}=await this.hub.refresh();this.elements.inbox.setThreads(threads);if(errors.length)this.setStatus(`${threads.length} conversations · ${errors.length} service${errors.length===1?'':'s'} need attention`,'warning');else this.setStatus(`${threads.length} conversation${threads.length===1?'':'s'}`,'success');}catch(error){this.setStatus(error.message,'error');}finally{this.elements.inbox.setLoading(false)}}
+    async select(thread){const selection=++this.selectionVersion;this.active=thread;this.elements.inbox.setActive(thread.id);this.elements.conversation.setStatus('Loading…');try{const messages=await this.hub.messages(thread);let inspection;try{inspection=await inspectMessageRecords(messages,(message,context)=>this.inspectMessage?.(message,thread,context),{prepare:this.prepareMessageInspection?records=>this.prepareMessageInspection(records,thread):null});}catch{inspection=unavailableMessageInspection(messages);}if(selection!==this.selectionVersion)return;const {advisories,failures}=inspection;this.elements.conversation.setConversation(thread,messages,{advisories});const warnings=advisories.size-failures;this.elements.conversation.setStatus(failures?`${failures} message safety check${failures===1?' is':'s are'} unavailable. Review manually before replying.`:warnings?`${warnings} message${warnings===1?' has':'s have'} a safety warning. Review before replying.`:'');}catch(error){if(selection!==this.selectionVersion)return;this.elements.conversation.setConversation(thread,[]);this.elements.conversation.setStatus(error.message);}}
+    async send({thread,body}){this.elements.conversation.setBusy(true);this.elements.conversation.setStatus('Sending…');try{await this.hub.send({providerId:thread.providerId,threadId:thread.id,channel:thread.channel,body});this.elements.conversation.clearComposer();await this.select(thread);const service=this.services.find(item=>item.id===thread.providerId);this.elements.conversation.setStatus(service?.simulated?'Simulated locally. Nothing left this device.':'Sent.');}catch(error){this.elements.conversation.setStatus(error.message);}finally{this.elements.conversation.setBusy(false)}}
+    openSettings(){this.elements.settings.configure({title:this.labels.settingsTitle,description:this.labels.settingsDescription,services:this.services,values:this.values});this.elements.panel.hidden=false;document.body.classList.add('modal-open');}
+    closeSettings(){this.elements.panel.hidden=true;document.body.classList.remove('modal-open');}
+    async saveSettings(values){try{this.values=await this.preferences.save(values);this.rebuildHub();this.elements.settings.setStatus('Services saved.');this.closeSettings();await this.refresh();}catch(error){this.elements.settings.setStatus(error.message)}}
+    action(service){if(service.externalUrl){const opened=globalThis.open(service.externalUrl,'_blank','noopener,noreferrer');if(!opened)this.elements.settings.setStatus(`Open ${service.externalUrl} to continue.`);return}this.elements.settings.setStatus(`${service.label} connects through the Arcane communications bridge.`)}
+}

package/runtime/arcane/modules/CommunicationHub.js

@@ -0,0 +1,16 @@
+import CommunicationMessage from '../entities/CommunicationMessage.js';
+import CommunicationThread from '../entities/CommunicationThread.js';
+import CommunicationProviderRegistry from './CommunicationProviderRegistry.js?v=2';
+
+export default class CommunicationHub extends EventTarget{
+    constructor({providers=[],enabledProviderIds=[]}={}){super();this.registry=providers instanceof CommunicationProviderRegistry?providers:new CommunicationProviderRegistry(providers);this.enabled=new Set(enabledProviderIds);this.threads=[];}
+    setEnabled(ids=[]){this.enabled=new Set(Array.from(ids,String));return this;}
+    enabledProviders(){return this.registry.list().filter(provider=>this.enabled.has(provider.id));}
+    async refresh(){
+        const results=await Promise.allSettled(this.enabledProviders().map(async provider=>(await provider.listThreads()).map(value=>value instanceof CommunicationThread?value:new CommunicationThread({...value,providerId:provider.id}))));
+        const errors=[];const threads=[];for(const result of results){if(result.status==='fulfilled') threads.push(...result.value);else errors.push(result.reason);}
+        this.threads=threads.sort((a,b)=>b.updatedAt.localeCompare(a.updatedAt));this.dispatchEvent(new CustomEvent('communications-refresh',{detail:{threads:[...this.threads],errors}}));return {threads:[...this.threads],errors};
+    }
+    async messages(thread){const record=thread instanceof CommunicationThread?thread:new CommunicationThread(thread);const values=await this.registry.get(record.providerId).getMessages(record.id);return values.map(value=>value instanceof CommunicationMessage?value:new CommunicationMessage({...value,threadId:record.id,providerId:record.providerId,channel:record.channel})).sort((a,b)=>a.timestamp.localeCompare(b.timestamp));}
+    async send({providerId,threadId,channel,body,subject='',recipients=[]}={}){if(!String(body||'').trim()) throw new TypeError('A message body is required.');return this.registry.get(providerId).send({threadId,channel,body:String(body),subject:String(subject),recipients:Array.from(recipients||[])});}
+}

package/runtime/arcane/modules/CommunicationPreferences.js

@@ -0,0 +1,13 @@
+import {resolveApplicationLocalStorageKey} from './AppDataScope.js';
+
+function adapter(){
+    const native=globalThis.Arcane?.preferences;
+    if(native?.get&&native?.set) return native;
+    return {async get(key){const value=globalThis.localStorage?.getItem(resolveApplicationLocalStorageKey(key));return {found:value!=null,value:value==null?null:JSON.parse(value)}},async set(key,value){globalThis.localStorage?.setItem(resolveApplicationLocalStorageKey(key),JSON.stringify(value));return {key,value}}};
+}
+
+export default class CommunicationPreferences{
+    constructor(namespace='communications'){this.key=`arcane.communications.${String(namespace)}`;this.adapter=adapter();}
+    async load(defaults={}){const result=await this.adapter.get(this.key);return result?.found&&result.value&&typeof result.value==='object'?{...defaults,...result.value}:{...defaults};}
+    async save(values={}){const safe=Object.fromEntries(Object.entries(values).map(([id,value])=>[id,{enabled:Boolean(value?.enabled),endpoint:String(value?.endpoint||''),accountLabel:String(value?.accountLabel||''),status:String(value?.status||'Disconnected')} ]));await this.adapter.set(this.key,safe);return safe;}
+}

package/runtime/arcane/modules/CommunicationProviderRegistry.js

@@ -0,0 +1,16 @@
+const PROVIDER_ID=/^[a-z0-9][a-z0-9._-]{1,63}$/;
+
+export default class CommunicationProviderRegistry{
+    constructor(providers=[]){this.providers=new Map();for(const provider of providers) this.register(provider);}
+    register(provider){
+        const id=String(provider?.id||'').trim().toLowerCase();
+        if(!PROVIDER_ID.test(id)) throw new TypeError('Communication provider id is invalid.');
+        for(const method of ['listThreads','getMessages','send']) if(typeof provider[method]!=='function') throw new TypeError(`Provider ${id} must implement ${method}().`);
+        if(this.providers.has(id)) throw new RangeError(`Communication provider already registered: ${id}`);
+        this.providers.set(id,{...provider,id,label:String(provider.label||id),channels:Object.freeze(Array.from(provider.channels||['other'])),listThreads:provider.listThreads.bind(provider),getMessages:provider.getMessages.bind(provider),send:provider.send.bind(provider)});
+        return this.get(id);
+    }
+    get(id){const provider=this.providers.get(String(id||'').toLowerCase());if(!provider) throw new RangeError(`Unknown communication provider: ${id}`);return provider;}
+    has(id){return this.providers.has(String(id||'').toLowerCase());}
+    list(){return Array.from(this.providers.values());}
+}