arcane-os 0.5.16 → 0.5.18

package/runtime/arcane/modules/PreparedSpeech.js

@@ -0,0 +1,485 @@
+import Is from 'strong-type';
+import {arcaneLogging} from 'arcane-os/logging';
+
+const is=new Is(false);
+const owners=new WeakMap();
+const storageQueues=new WeakMap();
+
+function deferred(){
+    let resolve;
+    let reject;
+    const promise=new Promise(function captureSettlement(accept,decline){
+        resolve=accept;
+        reject=decline;
+    });
+    // The preparation owns failures even before a caller requests a segment.
+    promise.catch(function observeDeferredFailure(){});
+    return {promise,resolve,reject};
+}
+
+function abortError(){
+    const error=new Error('Speech preparation was cancelled.');
+    error.name='AbortError';
+    error.code='ARCANE_AI_REQUEST_ABORTED';
+    return error;
+}
+
+function copyJSON(value,ancestors=new Set()){
+    if(value===null||is.string(value)||is.boolean(value))return value;
+    if(is.finite(value))return value;
+    if(!value||!is.object(value)||ancestors.has(value)){
+        throw new TypeError('Speech preparation metadata must contain JSON-compatible values.');
+    }
+    const prototype=Object.getPrototypeOf(value);
+    if(!is.array(value)&&prototype!==Object.prototype&&prototype!==null){
+        throw new TypeError('Speech preparation metadata must contain JSON-compatible values.');
+    }
+    ancestors.add(value);
+    const result=is.array(value)?[]:{};
+    const keys=is.array(value)
+        ?Array.from({length:value.length},function arrayIndex(unused,index){return String(index);})
+        :Object.keys(value);
+    for(const key of keys){
+        Object.defineProperty(result,key,{
+            value:copyJSON(value[key],ancestors),
+            enumerable:true,
+            configurable:true,
+            writable:true
+        });
+    }
+    ancestors.delete(value);
+    return result;
+}
+
+function sameJSON(first,second){
+    if(Object.is(first,second))return true;
+    if(!first||!second||!is.object(first)||!is.object(second))return false;
+    if(is.array(first)!==is.array(second))return false;
+    const keys=Object.keys(first);
+    if(keys.length!==Object.keys(second).length)return false;
+    for(const key of keys){
+        if(!Object.hasOwn(second,key)||!sameJSON(first[key],second[key]))return false;
+    }
+    return true;
+}
+
+function sameInput(first,second){
+    return sameJSON(first.parts,second.parts)
+        &&sameJSON(first.originalParts,second.originalParts)
+        &&sameJSON(first.selection,second.selection)
+        &&sameJSON(first.segmentation,second.segmentation)
+        &&sameJSON(first.identity,second.identity);
+}
+
+function normalizeStorage(storage){
+    if(storage===null||storage===undefined)return null;
+    const {db,table,key}=storage;
+    if(!db||!is.string(table)||!table||!is.string(key)||!key){
+        throw new TypeError('Speech storage requires an existing database, table, and key.');
+    }
+    for(const method of ['get','set','readFile','writeFile']){
+        if(!is.function(db[method])){
+            throw new TypeError(`Speech storage requires db.${method}().`);
+        }
+    }
+    return {db,table,key,fileName:`${encodeURIComponent(key)}.json`};
+}
+
+function sameStorage(first,second){
+    return first===second||Boolean(first&&second
+        &&first.db===second.db&&first.table===second.table&&first.key===second.key);
+}
+
+function serializeStorage(storage,execute){
+    let tables=storageQueues.get(storage.db);
+    if(!tables){
+        tables=new Map();
+        storageQueues.set(storage.db,tables);
+    }
+    let keys=tables.get(storage.table);
+    if(!keys){
+        keys=new Map();
+        tables.set(storage.table,keys);
+    }
+    const previous=keys.get(storage.key)||Promise.resolve();
+    const operation=previous.then(execute,execute);
+    keys.set(storage.key,operation);
+    function releaseStorageQueue(){
+        if(keys.get(storage.key)===operation)keys.delete(storage.key);
+    }
+    operation.then(releaseStorageQueue,releaseStorageQueue);
+    return operation;
+}
+
+async function readManifest(storage){
+    const stored=await storage.db.get(storage.table,storage.fileName,true);
+    if(stored===null||stored===undefined)return {version:1,entries:[]};
+    const manifest=copyJSON(stored);
+    if(manifest.version!==1||!is.array(manifest.entries)){
+        throw new TypeError('Stored speech preparation metadata is unreadable.');
+    }
+    return manifest;
+}
+
+function createRecord(input){
+    return {
+        id:globalThis.crypto.randomUUID(),
+        ...copyJSON(input),
+        segments:input.parts.map(function emptyAudioRecord(){
+            return {audioFile:null,contentType:null};
+        })
+    };
+}
+
+function publish(interest,error=null){
+    const job=interest.job;
+    let completed=0;
+    for(const segment of job.segments){
+        if(segment.state==='ready'||segment.state==='error')completed+=1;
+    }
+    try{
+        interest.onState?.({
+            state:interest.state,
+            completed,
+            total:job.segments.length,
+            segments:job.segments,
+            error
+        });
+    }catch(observerError){
+        arcaneLogging.error('Speech preparation state observer failed.',observerError);
+    }
+}
+
+function publishJob(job,error=null){
+    for(const interest of Array.from(job.interests)){
+        if(!interest.active)continue;
+        interest.state=job.state;
+        publish(interest,error);
+    }
+}
+
+function settleSegment(job,index,error){
+    const slot=job.slots[index];
+    if(slot.settled)return;
+    slot.settled=true;
+    const segment=job.segments[index];
+    if(arguments.length===3){
+        segment.state='error';
+        segment.error=error;
+        slot.ready.reject(error);
+        if(error?.name!=='AbortError'){
+            arcaneLogging.error('Speech preparation segment failed.',{index,error});
+        }
+    }else{
+        const saved=job.record.segments[index];
+        segment.state='ready';
+        segment.audioFile=saved.audioFile;
+        segment.contentType=saved.contentType;
+        slot.ready.resolve();
+    }
+    publishJob(job);
+}
+
+async function saveAudio(job,index,blob){
+    const contentType=blob.type;
+    if(!job.storage){
+        job.record.segments[index]={audioFile:null,contentType};
+        return;
+    }
+    const storage=job.storage;
+    const audioFile=`${job.record.id}.${index}.audio`;
+    await serializeStorage(storage,async function writePreparedAudio(){
+        if(job.controller.signal.aborted)throw abortError();
+        const manifest=await readManifest(storage);
+        let entry=manifest.entries.find(function findPreparedEntry(candidate){
+            return candidate.id===job.record.id;
+        });
+        if(!entry){
+            entry=copyJSON(job.record);
+            manifest.entries.push(entry);
+        }
+        if(job.controller.signal.aborted)throw abortError();
+        // DB writes cannot be aborted; finish this started write and its metadata
+        // together so a cancelled interest still leaves successful audio reusable.
+        await storage.db.writeFile(storage.table,audioFile,blob,false);
+        entry.segments[index]={audioFile,contentType};
+        await storage.db.set(storage.table,storage.fileName,manifest);
+        job.record.segments[index]={audioFile,contentType};
+        // Durable audio is reopened on demand rather than retained in memory.
+        job.slots[index].blob=null;
+    });
+}
+
+async function prepareSegment(job,index,request){
+    const slot=job.slots[index];
+    try{
+        const blob=slot.blob||await request;
+        if(!(blob instanceof Blob)){
+            throw new TypeError('Speech synthesis must return a Blob.');
+        }
+        slot.blob=blob;
+        if(job.controller.signal.aborted)throw abortError();
+        await saveAudio(job,index,blob);
+        settleSegment(job,index);
+    }catch(error){
+        settleSegment(job,index,error);
+    }
+}
+
+async function loadRecord(job){
+    if(job.previous){
+        await job.previous.finished.promise;
+        for(let index=0;index<job.slots.length;index+=1){
+            job.slots[index].blob=job.previous.slots[index].blob;
+        }
+        if(!job.storage&&job.previous.record){
+            job.record=copyJSON(job.previous.record);
+        }
+        job.previous=null;
+    }
+    if(job.controller.signal.aborted)throw abortError();
+    if(job.storage){
+        const storage=job.storage;
+        job.record=await serializeStorage(storage,async function findStoredPreparation(){
+            const manifest=await readManifest(storage);
+            const existing=manifest.entries.find(function findMatchingPreparation(entry){
+                return sameInput(entry,job.input);
+            });
+            if(existing){
+                if(!is.array(existing.segments)||existing.segments.length!==job.slots.length){
+                    throw new TypeError('Stored speech preparation segments are unreadable.');
+                }
+                return copyJSON(existing);
+            }
+            const record=createRecord(job.input);
+            manifest.entries.push(record);
+            if(job.controller.signal.aborted)throw abortError();
+            await storage.db.set(storage.table,storage.fileName,manifest);
+            return record;
+        });
+    }else if(!job.record){
+        job.record=createRecord(job.input);
+    }
+    for(let index=0;index<job.slots.length;index+=1){
+        if(job.controller.signal.aborted)throw abortError();
+        const audio=job.record.segments[index];
+        if(!job.storage){
+            if(job.slots[index].blob){
+                job.record.segments[index]={
+                    audioFile:null,
+                    contentType:job.slots[index].blob.type
+                };
+                settleSegment(job,index);
+            }
+            continue;
+        }
+        if(!audio?.audioFile)continue;
+        try{
+            if(!is.string(audio.contentType)){
+                throw new TypeError('Stored speech audio content type is unreadable.');
+            }
+            await job.storage.db.readFile(job.storage.table,audio.audioFile);
+            job.slots[index].blob=null;
+            settleSegment(job,index);
+        }catch(error){
+            if(error?.name==='NotFoundError'){
+                job.record.segments[index]={audioFile:null,contentType:null};
+            }else{
+                settleSegment(job,index,error);
+            }
+        }
+    }
+}
+
+async function admitPreparation(job){
+    await loadRecord(job);
+    if(job.controller.signal.aborted)throw abortError();
+    job.state='preparing';
+    publishJob(job);
+    const pending=[];
+    // Calls enter the existing provider queue in order, before awaiting results.
+    for(let index=0;index<job.slots.length;index+=1){
+        const slot=job.slots[index];
+        if(slot.settled)continue;
+        if(job.controller.signal.aborted){
+            settleSegment(job,index,abortError());
+            continue;
+        }
+        job.segments[index].state='preparing';
+        let request;
+        if(!slot.blob){
+            try{
+                request=job.synthesize(copyJSON(job.input.parts[index]),job.controller.signal);
+            }catch(error){
+                request=Promise.reject(error);
+            }
+        }
+        pending.push(prepareSegment(job,index,request));
+    }
+    publishJob(job);
+    return pending;
+}
+
+function finishPreparation(job,error){
+    if(arguments.length===2){
+        for(let index=0;index<job.slots.length;index+=1){
+            if(!job.slots[index].settled)settleSegment(job,index,error);
+        }
+    }
+    const errors=[];
+    for(const segment of job.segments){
+        if(segment.state==='error')errors.push(segment.error);
+    }
+    if(arguments.length===2&&errors.length===0)errors.push(error);
+    job.done=true;
+    job.failed=errors.length>0;
+    if(job.failed){
+        const failure=errors.length===1?errors[0]:new AggregateError(
+            errors,
+            'Some speech segments could not be prepared.'
+        );
+        job.state=job.controller.signal.aborted?'cancelled':'error';
+        publishJob(job,failure);
+        job.ready.reject(failure);
+    }else{
+        job.state='ready';
+        publishJob(job);
+        job.ready.resolve(copyJSON(job.record));
+    }
+    job.finished.resolve();
+}
+
+function createJob(ownerState,input,storage,synthesize,previous){
+    const job={
+        input,storage,synthesize,previous,
+        controller:new AbortController(),
+        interests:new Set(),
+        state:'queued',
+        done:false,
+        failed:false,
+        record:null,
+        ready:deferred(),
+        finished:deferred(),
+        slots:input.parts.map(function createSegmentSlot(){
+            return {ready:deferred(),blob:null,settled:false};
+        }),
+        segments:input.parts.map(function createPublicSegment(part,index){
+            return {...part,index,state:'queued',audioFile:null,contentType:null,error:null};
+        })
+    };
+    const admission=ownerState.admission.then(function admitOrderedPreparation(){
+        return admitPreparation(job);
+    });
+    ownerState.admission=admission.then(
+        function preparationAdmitted(){},
+        function preparationAdmissionFailed(){}
+    );
+    admission.then(async function settleAdmittedPreparation(pending){
+        await Promise.allSettled(pending);
+        finishPreparation(job);
+    },function failPreparationAdmission(error){
+        finishPreparation(job,error);
+    }).catch(function reportPreparationSettlementFailure(error){
+        finishPreparation(job,error);
+    });
+    return job;
+}
+
+function createHandle(job,signal,onState){
+    const ready=deferred();
+    const cancelled=deferred();
+    const interest={job,onState,active:true,state:job.state};
+    function removeSignal(){signal?.removeEventListener('abort',cancel);}
+    function cancel(){
+        if(!interest.active)return false;
+        interest.active=false;
+        interest.state='cancelled';
+        removeSignal();
+        job.interests.delete(interest);
+        const error=abortError();
+        ready.reject(error);
+        cancelled.reject(error);
+        publish(interest,error);
+        if(!job.done&&job.interests.size===0)job.controller.abort();
+        return true;
+    }
+    const handle={
+        segments:job.segments,
+        get state(){return interest.state;},
+        ready:ready.promise,
+        async getAudio(index){
+            if(!interest.active)throw abortError();
+            if(!is.safeInteger(index)||index<0||index>=job.slots.length){
+                throw new RangeError('Speech segment index is outside this preparation.');
+            }
+            await Promise.race([job.slots[index].ready.promise,cancelled.promise]);
+            if(!interest.active)throw abortError();
+            if(!job.storage)return job.slots[index].blob;
+            const audio=job.record.segments[index];
+            const file=await job.storage.db.readFile(job.storage.table,audio.audioFile);
+            if(!interest.active)throw abortError();
+            return file.type===audio.contentType?file:new Blob([file],{type:audio.contentType});
+        },
+        cancel
+    };
+    job.interests.add(interest);
+    job.ready.promise.then(function preparationReady(record){
+        if(interest.active)ready.resolve(copyJSON(record));
+        removeSignal();
+        job.interests.delete(interest);
+    },function preparationFailed(error){
+        if(interest.active)ready.reject(error);
+        removeSignal();
+        job.interests.delete(interest);
+    });
+    signal?.addEventListener('abort',cancel,{once:true});
+    if(signal?.aborted)cancel();
+    else publish(interest);
+    return handle;
+}
+
+/** Prepare complete ordered speech without constructing or controlling playback. */
+function prepareSpeech({
+    owner,
+    parts,
+    originalParts=parts,
+    selection=null,
+    segmentation=null,
+    storage=null,
+    identity=null,
+    signal=null,
+    onState=null,
+    synthesize
+}={}){
+    if((!owner||!is.object(owner))&&!is.function(owner)){
+        throw new TypeError('Speech preparation requires its owning AI instance.');
+    }
+    if(!is.array(parts)||!is.function(synthesize)
+        ||(onState!==null&&!is.function(onState))){
+        throw new TypeError('Speech preparation requires ordered parts and synthesis/state callbacks.');
+    }
+    const input=copyJSON({parts,originalParts,selection,segmentation,identity});
+    const destination=normalizeStorage(storage);
+    let ownerState=owners.get(owner);
+    if(!ownerState){
+        ownerState={admission:Promise.resolve(),jobs:new Set()};
+        owners.set(owner,ownerState);
+    }
+    let previous=null;
+    for(const candidate of ownerState.jobs){
+        if(sameStorage(candidate.storage,destination)&&sameInput(candidate.input,input)){
+            previous=candidate;
+            break;
+        }
+    }
+    if(previous&&!previous.failed&&!previous.controller.signal.aborted
+        &&(!previous.done||!destination)){
+        return createHandle(previous,signal,onState);
+    }
+    const job=createJob(ownerState,input,destination,synthesize,previous);
+    if(previous)ownerState.jobs.delete(previous);
+    ownerState.jobs.add(job);
+    return createHandle(job,signal,onState);
+}
+
+export {prepareSpeech};

package/runtime/arcane/modules/Questionnaire.js

@@ -1,3 +1,6 @@
+import Is from 'strong-type';
+const is=new Is(false);
+
 /**
  * Default delay of exactly seven 24-hour periods in milliseconds.
  *
@@ -23,7 +26,7 @@ export class Questionnaire{
      * @throws {RangeError} When the delay is not a positive finite number.
      */
     setNotificationTime(notificationTime){
-        if(!Number.isFinite(notificationTime)||notificationTime<=0){
+        if(!is.finite(notificationTime)||notificationTime<=0){
             throw new RangeError('notificationTime must be a positive finite number');
         }
 
@@ -48,11 +51,11 @@ export class Questionnaire{
             return false;
         }
 
-        if(!Number.isSafeInteger(firstBootUp)||firstBootUp<=0){
+        if(!is.safeInteger(firstBootUp)||firstBootUp<=0){
             return false;
         }
 
-        if(!Number.isFinite(now)||now<firstBootUp){
+        if(!is.finite(now)||now<firstBootUp){
             return false;
         }
 

package/runtime/arcane/modules/RecordLinkIndex.js

@@ -1,5 +1,8 @@
+import Is from 'strong-type';
+const is=new Is(false);
+
 function parseRecordLinks(value='',{pattern=/\b[A-Z]\d{4}\b/gi}={}){
-    const text=Array.isArray(value)?value.join(' '):String(value||'');
+    const text=is.array(value)?value.join(' '):String(value||'');
     return [...new Set([...text.matchAll(pattern)].map(match=>match[0].toUpperCase()))];
 }
 

package/runtime/arcane/modules/RecordPassageIndex.js

@@ -1,3 +1,6 @@
+import Is from 'strong-type';
+const is=new Is(false);
+
 const MONTH_NUMBER={
   january:1,february:2,march:3,april:4,may:5,june:6,
   july:7,august:8,september:9,october:10,november:11,december:12
@@ -7,7 +10,7 @@ const MONTH_TOKEN='January|February|March|April|May|June|July|August|September|O
 
 function normalizedInteger(value,{minimum=0,fallback=0}={}){
   const number=Number(value);
-  return Number.isInteger(number)&&number>=minimum?number:fallback;
+  return is.integer(number)&&number>=minimum?number:fallback;
 }
 
 function textLines(value=''){
@@ -86,9 +89,9 @@ function findRulePassages(text='',rules=[],{
   const findings=[];
   const seen=new Set();
 
-  for(const definition of Array.isArray(rules)?rules:[]){
+  for(const definition of is.array(rules)?rules:[]){
     if(!definition?.id) continue;
-    const patterns=Array.isArray(definition.patterns)?definition.patterns:[definition.pattern];
+    const patterns=is.array(definition.patterns)?definition.patterns:[definition.pattern];
     let ruleCount=0;
     for(const supplied of patterns.filter(Boolean)){
       const pattern=globalPattern(supplied);
@@ -111,9 +114,9 @@ function findRulePassages(text='',rules=[],{
           lineEnd:lineEnd+1,
           page:pageAtLine(markers,line),
           excerpt,
-          metadata:definition.metadata&&typeof definition.metadata==='object'?{...definition.metadata}:{}
+          metadata:definition.metadata&&is.object(definition.metadata)?{...definition.metadata}:{}
         };
-        if(typeof definition.accept==='function'&&!definition.accept(candidate,{match,source,lines,line})) continue;
+        if(is.function(definition.accept)&&!definition.accept(candidate,{match,source,lines,line})) continue;
         const key=passageKey(candidate);
         if(seen.has(key)) continue;
         seen.add(key);
@@ -127,7 +130,7 @@ function findRulePassages(text='',rules=[],{
 
 function validIsoDate(year,month=1,day=1){
   const y=Number(year); const m=Number(month); const d=Number(day);
-  if(!Number.isInteger(y)||y<1900||y>2100||!Number.isInteger(m)||m<1||m>12||!Number.isInteger(d)||d<1||d>31) return null;
+  if(!is.integer(y)||y<1900||y>2100||!is.integer(m)||m<1||m>12||!is.integer(d)||d<1||d>31) return null;
   const date=new Date(Date.UTC(y,m-1,d));
   if(date.getUTCFullYear()!==y||date.getUTCMonth()!==m-1||date.getUTCDate()!==d) return null;
   return `${String(y).padStart(4,'0')}-${String(m).padStart(2,'0')}-${String(d).padStart(2,'0')}`;

package/runtime/arcane/modules/RecordReviewStore.js

@@ -1,3 +1,6 @@
+import Is from 'strong-type';
+const is=new Is(false);
+
 import {createArcaneEventSource} from 'arcane-os/event-manager';
 import {resolveApplicationLocalStorageKey} from './AppDataScope.js';
 
@@ -43,17 +46,17 @@ function operationAbortedError(reason){
 }
 
 function isPlainRecord(value){
-    if(!value||typeof value!=='object'||Array.isArray(value)) return false;
+    if(!value||!is.object(value)||is.array(value)) return false;
     const prototype=Object.getPrototypeOf(value);
     return prototype===Object.prototype||prototype===null;
 }
 
 function isAbortSignal(value){
     return Boolean(value)
-        &&typeof value==='object'
-        &&typeof value.aborted==='boolean'
-        &&typeof value.addEventListener==='function'
-        &&typeof value.removeEventListener==='function';
+        &&is.object(value)
+        &&is.boolean(value.aborted)
+        &&is.function(value.addEventListener)
+        &&is.function(value.removeEventListener);
 }
 
 function normalizeOperationOptions(value={}){
@@ -110,15 +113,15 @@ function normalizeRecordId(value=''){
 }
 
 function normalizeReview(value={}){
-    const source=value&&typeof value==='object'?value:{};
+    const source=value&&is.object(value)?value:{};
     const attributes={};
-    if(source.attributes&&typeof source.attributes==='object'&&!Array.isArray(source.attributes)){
+    if(source.attributes&&is.object(source.attributes)&&!is.array(source.attributes)){
         for(const [key,value] of Object.entries(source.attributes)){
             const normalizedKey=String(key);
             setDataProperty(
                 attributes,
                 normalizedKey,
-                Array.isArray(value)
+                is.array(value)
                     ?value.map(function normalizeReviewAttributeItem(item){
                         return String(item);
                     })
@@ -184,7 +187,7 @@ function normalizedStoredRecords(value){
 }
 
 function validateAdapter(adapter){
-    if(!adapter||typeof adapter.get!=='function'||typeof adapter.set!=='function'){
+    if(!adapter||!is.function(adapter.get)||!is.function(adapter.set)){
         throw recordReviewStoreError(
             RECORD_REVIEW_STORE_ERROR_CODES.adapterInvalid,
             'record-review-storage-adapter-invalid',

package/runtime/arcane/modules/RiskSignalAnalyzer.js

@@ -1,3 +1,6 @@
+import Is from 'strong-type';
+const is=new Is(false);
+
 const DEFAULT_LEVELS=[
     {minimum:70,id:'critical'},
     {minimum:40,id:'high'},
@@ -15,7 +18,7 @@ export function analyzeRiskSignals(input,{signals=[],levels=DEFAULT_LEVELS}={}){
     let score=0;
 
     for(const signal of signals){
-        if(!signal||typeof signal.id!=='string'||!(signal.pattern instanceof RegExp))continue;
+        if(!signal||!is.string(signal.id)||!(signal.pattern instanceof RegExp))continue;
         signal.pattern.lastIndex=0;
         if(!signal.pattern.test(text))continue;
         const weight=Math.max(0,Number(signal.weight)||0);

package/runtime/arcane/modules/ScopedOPFSCache.js

@@ -1,10 +1,13 @@
+import Is from 'strong-type';
+const is=new Is(false);
+
 import {
     canonicalApplicationId,
     openApplicationDataDirectory
 } from './AppDataScope.js';
 
 function safeSegment(value,label){
-    if(typeof value!=='string'){
+    if(!is.string(value)){
         throw new TypeError(`${label} must be a string.`);
     }
     const normalized=value.trim();
@@ -49,7 +52,7 @@ export default class ScopedOPFSCache{
             ?null
             :canonicalApplicationId(applicationId);
         this.#namespace=safeSegment(namespace,'namespace');
-        if(!storage||typeof storage.getDirectory!=='function'){
+        if(!storage||!is.function(storage.getDirectory)){
             throw unavailable();
         }
         this.#storage=storage;
@@ -58,7 +61,7 @@ export default class ScopedOPFSCache{
     }
 
     static supported(storage=globalThis.navigator?.storage){
-        return Boolean(storage&&typeof storage.getDirectory==='function');
+        return Boolean(storage&&is.function(storage.getDirectory));
     }
 
     get namespace(){