@thebackstoryis/engineering-with-ai 0.3.2 → 0.3.4-beta.6

package/src/cli.mjs

@@ -1,3 +1,8 @@
+import {openaiCredentialStatus,configureOpenaiCredentials,checkOpenaiConnection,removeOpenaiCredentials,safeOpenaiCredentialError} from './openai-credentials.mjs';
+import {jevCredentialStatus,configureJevCredentials,checkJevConnection,removeJevCredentials} from './jev-credentials.mjs';
+import {readJevSettings,saveJevSettings,readJevMeasurements,readDecisionCredentials,safeJevError} from './jev.mjs';
+import {decideWithJev,prepareProjectContextWithJev,recommendPersonasWithJev,readCompanionWithJev} from './runtime/jev-operations.mjs';
+import {runJevExperiment} from '../scripts/jev-experiment.mjs';
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readFileSync, realpathSync } from 'node:fs';
@@ -530,6 +535,15 @@ Commands:
   ewai rollout assurance PROJECT_ID [--project PATH]
   ewai discover [--project PATH] [--answers FILE] [--stack PACK] [--force]
   ewai context register FOLDER [--project PATH] --yes [--label NAME] [--classification public|internal|confidential|restricted] [--cloud-processing allowed|denied|unknown]
+  ewai jev status|measurements [--project PATH] [--json]
+  ewai decisions status|measurements|decide|personas [--project PATH] [--json]
+  ewai decisions configure --mode off|shadow|active --provider auto|openai|jev --yes [--acknowledge-openai-processing] [--acknowledge-cloud-processing] [--revoke-openai-processing] [--revoke-cloud-processing]
+  ewai providers credentials openai status|configure|check|remove [--project PATH]
+  ewai jev credentials status|configure|check|remove [--project PATH]
+  ewai jev configure --mode off|shadow|active --yes [--acknowledge-cloud-processing] [--use-cases context,personas,skill,claim,failure,impact,tests]
+  ewai jev decide --input PROJECT_JSON [--project PATH]
+  ewai jev experiment [--limit 6] [--project PATH]
+  ewai jev personas --focus TEXT [--limit 4] [--project PATH]
   ewai context prepare PROFILE --slug SLUG [--task TASK] [--phase PHASE] [--focus TEXT] [--budget TOKENS] [--previous DIGEST] [--project PATH]
   ewai context benchmark [--samples COUNT]
   ewai design-system status|list|inspect|resolve|select [ID] [--project PATH]
@@ -909,32 +923,61 @@ export async function run(args) {
       print(json ? result : JSON.stringify(result, null, 2), json); return;
     }
 
-    if(command==='providers'&&subcommand==='credentials'){
-      const action=args[3];
-      if(args[2]!=='grok'||!['status','configure','check','remove'].includes(action))throw new Error('Choose providers credentials grok status, configure, check or remove.');
+    if(command==='providers'&&subcommand==='credentials'||command==='jev'&&subcommand==='credentials'){
+      const isJev=command==='jev',isOpenai=!isJev&&args[2]==='openai',action=args[isJev?2:3];
+      const statusCredential=isJev?jevCredentialStatus:isOpenai?openaiCredentialStatus:grokCredentialStatus,configureCredential=isJev?configureJevCredentials:isOpenai?configureOpenaiCredentials:configureGrokCredentials,checkConnection=isJev?checkJevConnection:isOpenai?checkOpenaiConnection:checkGrokConnection,removeCredential=isJev?removeJevCredentials:isOpenai?removeOpenaiCredentials:removeGrokCredentials;
+      if(!isJev&&!['grok','openai'].includes(args[2])||!['status','configure','check','remove'].includes(action))throw new Error('Choose providers credentials grok or openai, then status, configure, check or remove.');
       const allowedValues=['--project',...(action==='remove'?['--expected-revision']:[])],allowedFlags=['--json',...(action==='remove'?['--yes']:[])];
-      for(let i=4;i<args.length;i++){
+      for(let i=isJev?3:4;i<args.length;i++){
         if(allowedValues.includes(args[i])){if(!args[i+1]||args[i+1].startsWith('--'))throw new Error('A credential option requires a value.');i++;}
         else if(!allowedFlags.includes(args[i]))throw new Error('Unsupported credential option. Never put API keys in command arguments.');
       }
       const credentialOptions={projectRoot:selectedProject(args)};
       let result;
-      if(action==='status')result=grokCredentialStatus(credentialOptions);
-      if(action==='check')result=await checkGrokConnection(credentialOptions);
-      if(action==='remove')result=removeGrokCredentials({confirmed:has(args,'--yes'),expectedRevision:option(args,'--expected-revision',grokCredentialStatus(credentialOptions).revision)},credentialOptions);
+      if(action==='status')result=statusCredential(credentialOptions);
+      if(action==='check')result=await checkConnection(credentialOptions);
+      if(action==='remove')result=removeCredential({confirmed:has(args,'--yes'),expectedRevision:option(args,'--expected-revision',statusCredential(credentialOptions).revision)},credentialOptions);
       if(action==='configure'){
-        if(!process.stdin.isTTY||!process.stdout.isTTY)throw new Error('Grok setup requires an interactive terminal for hidden input. Use the local dashboard password form instead.');
-        const previous=grokCredentialStatus(credentialOptions),muted=new Writable({write(_chunk,_encoding,callback){callback();}});muted.isTTY=true;muted.columns=process.stdout.columns;
+        if(!process.stdin.isTTY||!process.stdout.isTTY)throw new Error('Credential setup requires an interactive terminal for hidden input. Use the local dashboard password form instead.');
+        const previous=statusCredential(credentialOptions),muted=new Writable({write(_chunk,_encoding,callback){callback();}});muted.isTTY=true;muted.columns=process.stdout.columns;
         const prompt=createInterface({input:process.stdin,output:muted,terminal:true,historySize:0});let apiKey;
         try{
-          process.stdout.write('This checks xAI authentication without generated output and saves the key for your account on this computer, outside the project, in an owner-only local file (not encrypted). XAI_API_KEY overrides the saved key. Cancel with Ctrl+C.\nxAI API key (hidden): ');
+          process.stdout.write(isOpenai?'This checks OpenAI metadata authentication without inference and saves an owner-only local key outside the project (not encrypted). OPENAI_API_KEY overrides it. This does not prove Decisions access; saving does not enable decisions. Cancel with Ctrl+C.\nOpenAI API key (hidden): ':isJev?'This checks TypeSafe authentication without inference and saves an owner-only local key outside the project (not encrypted). TYPESAFE_API_KEY overrides it. Saving does not enable Jev. Cancel with Ctrl+C.\nTypeSafe API key (hidden): ':'This checks xAI authentication without generated output and saves the key for your account on this computer, outside the project, in an owner-only local file (not encrypted). XAI_API_KEY overrides the saved key. Cancel with Ctrl+C.\nxAI API key (hidden): ');
           apiKey=await prompt.question('');process.stdout.write('\n');
-          result=await configureGrokCredentials({confirmed:true,expectedRevision:previous.revision,apiKey},credentialOptions);
+          result=await configureCredential({confirmed:true,expectedRevision:previous.revision,apiKey},credentialOptions);
         }finally{apiKey=undefined;prompt.close();}
       }
-      print(json?result:result.message??('Grok credential: '+result.source+'. Saved key: '+(result.saved?'available':'absent')+'.'),json);
+      print(json?result:result.message??((isJev?'Jev':isOpenai?'OpenAI':'Grok')+' credential: '+result.source+'. Saved key: '+(result.saved?'available':'absent')+'.'),json);
       if(result.status==='failed')process.exitCode=1;return;
     }
+
+    if(['jev','decisions'].includes(command)){
+      const actions=['status','configure','measurements','decide','experiment','personas'];
+      if(!actions.includes(subcommand))throw new Error('Choose Jev status, configure, measurements, decide, experiment or credentials.');
+      const valued=['--project',...(subcommand==='configure'?['--provider','--mode','--use-cases','--max-calls','--max-input-tokens','--timeout-ms','--minimum-confidence','--expected-revision']:[]),...(subcommand==='decide'?['--input']:[]),...(subcommand==='experiment'?['--limit']:[]),...(subcommand==='personas'?['--focus','--limit']:[])];
+      const flags=['--json',...(subcommand==='configure'?['--yes','--acknowledge-cloud-processing','--acknowledge-openai-processing','--revoke-cloud-processing','--revoke-openai-processing']:[])],seen=new Set();
+      for(let i=2;i<args.length;i++){const argument=args[i];if(seen.has(argument))throw new Error('Do not repeat Jev options.');seen.add(argument);if(valued.includes(argument)){if(!args[i+1]||args[i+1].startsWith('--'))throw new Error('A Jev option requires a value.');i++;}else if(!flags.includes(argument))throw new Error('Unsupported Jev option. Never put API keys in command arguments.');}
+      const root=selectedProject(args),current=readJevSettings(root);let value;
+      if(subcommand==='status')value={settings:current,...readDecisionCredentials(root),measurements:readJevMeasurements(root)};
+      if(subcommand==='measurements')value=readJevMeasurements(root);
+      if(subcommand==='configure'){
+        const policy=structuredClone(current.policy);
+        for(const vendor of ['openai','cloud'])if(has(args,'--acknowledge-'+vendor+'-processing')&&has(args,'--revoke-'+vendor+'-processing'))throw new Error('Choose acknowledgement or revocation for each provider.');
+        if(has(args,'--mode'))policy.mode=option(args,'--mode');
+        if(has(args,'--provider'))policy.provider=option(args,'--provider');
+        if(has(args,'--acknowledge-openai-processing'))policy.openaiConsent=true;
+        if(has(args,'--revoke-openai-processing'))policy.openaiConsent=false;
+        if(has(args,'--revoke-cloud-processing'))policy.cloudConsent=false;
+        if(has(args,'--use-cases'))policy.useCases=option(args,'--use-cases').split(',').map(s=>s.trim());
+        for(const [flag,key]of [['--max-calls','maxCalls'],['--max-input-tokens','maxInputTokens'],['--timeout-ms','timeoutMs'],['--minimum-confidence','minConfidence']])if(has(args,flag))policy[key]=Number(option(args,flag));
+        if(has(args,'--acknowledge-cloud-processing'))policy.cloudConsent=true;
+        value=saveJevSettings(root,{confirmed:has(args,'--yes'),expectedRevision:option(args,'--expected-revision',current.revision),policy});
+      }
+      if(subcommand==='decide'){const file=option(args,'--input');if(!file)throw new Error('Provide a project-local JSON decision input.');value=await decideWithJev(root,readProjectJsonInput(root,file,'Jev decision'));}
+      if(subcommand==='personas')value=await recommendPersonasWithJev(root,{focus:option(args,'--focus'),limit:Number(option(args,'--limit','4'))},listPersonas(availablePersonaRoots(root)));
+      if(subcommand==='experiment')value=await runJevExperiment(root,{limit:has(args,'--limit')?Number(option(args,'--limit')):6});
+      print(json?value:JSON.stringify(value,null,2),json);return;
+    }
     if(command==='providers'){
       if(!['show','set','auto','defaults','model'].includes(subcommand))throw new Error('Choose providers show, set, auto, model or defaults.');
       const valued=new Set(['--project','--expected-digest',...(subcommand==='set'?['--primary','--secondary','--tertiary','--pool','--input']:[]),...(subcommand==='auto'?['--pool']:[]),...(subcommand==='model'?['--suggest','--allow-model']:[])]);
@@ -1127,7 +1170,7 @@ export async function run(args) {
     if (command === 'companion' && subcommand === 'status') {
       assertCompanionArguments(args);
       const project = selectedProject(args);
-      print(readCompanionGuidance(project, {
+      print(await readCompanionWithJev(project, {
         focus: option(args, '--focus'),
         personas: listPersonas(availablePersonaRoots(project)),
       }), json);
@@ -1316,7 +1359,7 @@ export async function run(args) {
       const profile = args[2] ?? '';
       const budgetValue = option(args, '--budget');
       const projectRoot = selectedProject(args);
-      print(prepareProjectContext(projectRoot, {
+      print(await prepareProjectContextWithJev(projectRoot, {
         profile,
         slug: option(args, '--slug'),
         taskId: option(args, '--task'),
@@ -2518,6 +2561,8 @@ export async function run(args) {
 
     throw new Error(`Unknown command: ${args.join(' ')}`);
   } catch (error) {
+    if(command==='providers'&&subcommand==='credentials'&&args[2]==='openai'){const safe=safeOpenaiCredentialError(error);console.error(json?JSON.stringify(safe):safe.error);process.exitCode=1;return;}
+    if(['jev','decisions'].includes(command)){const safe=safeJevError(error);console.error(json?JSON.stringify(safe):safe.error);process.exitCode=1;return;}
     if (command !== 'error-report') {
       try {
         const projectRoot = selectedProject(args);

package/src/jev-credentials.mjs

@@ -0,0 +1,104 @@
+// TypeSafe uses the same audited private storage safeguards as Grok, with a separate key lifecycle.
+import {constants,openSync,closeSync,fstatSync,lstatSync,realpathSync,readFileSync,mkdirSync,writeFileSync,renameSync,unlinkSync,rmSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {resolve,relative,isAbsolute} from 'node:path';
+import {randomUUID,createHash} from 'node:crypto';
+
+const messages={
+ 'jev-credential-invalid':'Provide a valid TypeSafe API key using the private setup form or hidden terminal prompt.',
+ 'jev-credential-input':'Use the supported credential action and confirm the change.',
+ 'jev-credential-unsafe-storage':'Private credential storage is unsafe or unavailable. Repair its permissions or use TYPESAFE_API_KEY in the launching environment.',
+ 'jev-credential-invalid-storage':'The saved credential could not be read safely. Repair the private credential file before continuing.',
+ 'jev-credential-stale':'The saved credential changed. Refresh its status and try again.',
+ 'jev-credential-busy':'Another credential change is running. Retry after it finishes.',
+ 'jev-credential-missing':'No Jev key is configured. Use private credential setup or TYPESAFE_API_KEY in the launching environment.',
+ 'jev-key-rejected':'The key was not accepted. Check the key and its API permissions, then try again. The previous saved key was retained.',
+ 'jev-check-rate-limited':'TypeSafe limited the authentication check. Wait before trying again. The previous saved key was retained.',
+ 'jev-check-unavailable':'The authentication check could not complete. Check your connection and try again. The previous saved key was retained.',
+};
+function fail(code,statusCode=400){const error=new Error(messages[code]??messages['jev-credential-input']);error.code=code;error.statusCode=statusCode;throw error;}
+function key(value){if(typeof value!=='string'||value.length>512||!/^apikey_[A-Za-z0-9_-]{16,508}$/.test(value.trim()))fail('jev-credential-invalid');return value.trim();}
+function request(input,fields){if(!input||typeof input!=='object'||Array.isArray(input)||Object.keys(input).some(k=>!fields.includes(k))||input.confirmed!==true||typeof input.expectedRevision!=='string'||input.expectedRevision.length>80)fail('jev-credential-input');}
+function stat(path){try{return lstatSync(path);}catch(error){if(error.code==='ENOENT')return null;fail('jev-credential-unsafe-storage');}}
+function owned(s){return s&&!s.isSymbolicLink()&&(process.getuid===undefined||s.uid===process.getuid());}
+function paths(options={},create=false){
+ const declaredHome=resolve(options.home??homedir());
+ const root=stat(declaredHome);if(!owned(root)||!root.isDirectory()||(root.mode&0o022))fail('jev-credential-unsafe-storage');
+ let home,project;try{home=realpathSync(declaredHome);if(options.projectRoot)project=realpathSync(resolve(options.projectRoot));}catch{fail('jev-credential-unsafe-storage');}
+ const folder=resolve(home,'.ewai/credentials'),file=resolve(folder,'jev.json');
+ if(project){const rel=relative(project,file);if(rel===''||(!isAbsolute(rel)&&rel!=='..'&&!rel.startsWith('../')))fail('jev-credential-unsafe-storage');}
+ const canonicalRoot=stat(home);if(!owned(canonicalRoot)||canonicalRoot.ino!==root.ino||canonicalRoot.dev!==root.dev)fail('jev-credential-unsafe-storage');
+ for(const path of [resolve(home,'.ewai'),folder]){
+  let s=stat(path);if(!s&&create){try{mkdirSync(path,{mode:0o700});}catch(error){if(error.code!=='EEXIST')fail('jev-credential-unsafe-storage');}s=stat(path);}
+  if(s&&(!owned(s)||!s.isDirectory()||(s.mode&(path===folder?0o077:0o022))))fail('jev-credential-unsafe-storage');
+ }
+ return {folder,file,location:JSON.stringify([home,root.dev,root.ino])};
+}
+function stored(options={}){
+ const {file,location}=paths(options),before=stat(file);if(!before)return {value:null,signature:'missing',location};
+ if(process.platform==='win32'||!owned(before)||!before.isFile()||before.nlink!==1||(before.mode&0o077)||before.size>4096)fail('jev-credential-unsafe-storage');
+ let fd;try{
+  fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW);const bytes=readFileSync(fd),after=fstatSync(fd),current=stat(file);
+  if(bytes.length>4096||!current||before.ino!==after.ino||before.dev!==after.dev||before.mtimeMs!==after.mtimeMs||after.ino!==current.ino||after.mtimeMs!==current.mtimeMs)fail('jev-credential-unsafe-storage');
+  let value;try{value=JSON.parse(bytes.toString('utf8'));}catch{fail('jev-credential-invalid-storage');}
+  if(value?.schema!=='ewai.jev-credential/v1'||typeof value.revision!=='string'||!/^[a-f0-9-]{36}$/.test(value.revision)||Object.keys(value).some(k=>!['schema','revision','apiKey'].includes(k)))fail('jev-credential-invalid-storage');
+  try{key(value.apiKey);}catch{fail('jev-credential-invalid-storage');}
+  return {value,location,signature:JSON.stringify([after.dev,after.ino,after.mtimeMs,after.ctimeMs,createHash('sha256').update(bytes).digest('hex')])};
+ }catch(error){if(error.code?.startsWith('jev-'))throw error;fail('jev-credential-unsafe-storage');}finally{if(fd!==undefined)closeSync(fd);}
+}
+function environment(options){const env=options.env??process.env;return env.TYPESAFE_API_KEY?key(env.TYPESAFE_API_KEY):null;}
+export function jevCredentialStatus(options={}){
+ const override=environment(options);let value,storageIssue=null;
+ try{({value}=stored(options));}catch(error){if(!override)throw error;storageIssue='unsafe-saved-storage';}
+
+ return {schema:'ewai.jev-credential-status/v1',provider:'jev',configured:Boolean(override||value),saved:storageIssue?null:Boolean(value),storageIssue,source:override?'environment':value?'saved':'missing',revision:value?.revision??(storageIssue?'unavailable':'missing'),storage:'owner-only-local-file',encrypted:false,storageSupported:!storageIssue&&process.platform!=='win32',authority:'credentials-only'};
+}
+export function resolveJevApiKey(options={}){const override=environment(options);return override??stored(options).value?.apiKey??null;}
+function predecessor(input,options,expected){const current=stored(options);if((current.value?.revision??'missing')!==input.expectedRevision||(expected&&(current.signature!==expected.signature||current.location!==expected.location)))fail('jev-credential-stale',409);return current;}
+function mutation(options,operation){
+ if(process.platform==='win32')fail('jev-credential-unsafe-storage');
+ const {folder}=paths(options,true),lock=resolve(folder,'.jev.lock');
+ try{mkdirSync(lock,{mode:0o700});}catch(error){fail(error.code==='EEXIST'?'jev-credential-busy':'jev-credential-unsafe-storage',409);}
+ const identity=lstatSync(lock);
+ try{return operation();}finally{const current=stat(lock);if(owned(current)&&current.isDirectory()&&current.ino===identity.ino)rmSync(lock,{recursive:true});}
+}
+async function authenticate(apiKey,options={}){
+ const controller=new AbortController();let timer;
+ try{
+  const timeout=Math.min(10000,Math.max(10,options.timeoutMs??10000));
+  const response=await Promise.race([(options.fetchImpl??fetch)('https://api.typesafe.ai/v1/models',{method:'GET',headers:{authorization:'Bearer '+apiKey},redirect:'manual',signal:controller.signal}),new Promise((_,reject)=>{timer=setTimeout(()=>{controller.abort();reject(Error('deadline'));},timeout);})]);
+  // Discard provider bodies, including errors. They are not safe evidence.
+  if(response.body)void response.body.cancel().catch(()=>{});
+  if(response.status===200)return {status:'verified',code:'jev-authentication-verified',message:'TypeSafe authentication check passed. No output was generated; credit and coding readiness remain unverified.'};
+  const code=[401,403].includes(response.status)?'jev-key-rejected':response.status===429?'jev-check-rate-limited':'jev-check-unavailable';return {status:'failed',code,message:messages[code]};
+ }catch{return {status:'failed',code:'jev-check-unavailable',message:messages['jev-check-unavailable']};}
+ finally{clearTimeout(timer);controller.abort();}
+}
+export async function checkJevConnection(options={}){
+ const apiKey=resolveJevApiKey(options);
+ if(!apiKey)return {...jevCredentialStatus(options),status:'failed',code:'jev-credential-missing',message:messages['jev-credential-missing']};
+ return {...jevCredentialStatus(options),...await authenticate(apiKey,options)};
+}
+// Internal cache identity includes physical file identity and exact bytes; it
+// is never included in status, diagnostics or model-facing credential tools.
+export function jevCredentialIdentity(options={}) {
+ const override=environment(options);if(override)return createHash('sha256').update('environment '+override).digest('hex');
+ const value=stored(options);return createHash('sha256').update(value.location+' '+value.signature).digest('hex');
+}
+export async function configureJevCredentials(input,options={}){
+ request(input,['confirmed','expectedRevision','apiKey']);const apiKey=key(input.apiKey);environment(options);const previous=predecessor(input,options);
+ const check=await authenticate(apiKey,options);if(check.status!=='verified')fail(check.code);
+ mutation(options,()=>{
+  predecessor(input,options,previous);const {file}=paths(options,true),temporary=file+'.'+randomUUID()+'.tmp';
+  try{writeFileSync(temporary,JSON.stringify({schema:'ewai.jev-credential/v1',revision:randomUUID(),apiKey})+'\n',{flag:'wx',mode:0o600});paths(options);predecessor(input,options,previous);renameSync(temporary,file);}
+  catch(error){if(error.code?.startsWith('jev-'))throw error;fail('jev-credential-unsafe-storage');}
+  finally{if(stat(temporary))unlinkSync(temporary);}
+ });
+ return {...jevCredentialStatus(options),check,message:'Jev key checked and saved for your account on this computer. No work started.'};
+}
+export function removeJevCredentials(input,options={}){
+ request(input,['confirmed','expectedRevision']);environment(options);const previous=predecessor(input,options);
+ mutation(options,()=>{const current=predecessor(input,options,previous);if(current.value)unlinkSync(paths(options).file);});
+ const status=jevCredentialStatus(options);return {...status,message:status.source==='environment'?'Saved key removed. TYPESAFE_API_KEY still supplies the active credential.':'Saved Jev key removed. No work started.'};
+}
+export function safeJevCredentialError(error){const code=Object.hasOwn(messages,error?.code)?error.code:'jev-credential-input';return {error:messages[code],code};}

package/src/jev.mjs

@@ -0,0 +1,220 @@
+import { constants,openSync,closeSync,readFileSync,writeFileSync,lstatSync,fstatSync,realpathSync,mkdirSync,renameSync,unlinkSync,rmSync } from 'node:fs';
+import { resolve,dirname,relative } from 'node:path';
+import { randomUUID,createHash } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { resolveJevApiKey,jevCredentialIdentity,jevCredentialStatus } from './jev-credentials.mjs';
+import {resolveOpenaiApiKey,openaiCredentialIdentity,openaiCredentialStatus} from './openai-credentials.mjs';
+import {OPENAI_DECISIONS_MODEL,buildOpenaiDecisionPayload,normaliseOpenaiDecisionResponse,openaiDecisionUsage} from './openai-decisions.mjs';
+
+export const JEV_MODEL='jev-1.13.0';
+export const JEV_USE_CASES=Object.freeze(['context','personas','skill','claim','failure','impact','tests']);
+const defaultPolicy=Object.freeze({mode:'off',provider:'auto',openaiConsent:false,useCases:['context','personas'],cloudConsent:false,maxCalls:100,maxInputTokens:100000,timeoutMs:3000,minConfidence:0.65});
+const sources=new Set(['public','synthetic','cloud-approved','metadata-only']);
+const validId=value=>/^[-a-zA-Z0-9_.]{1,80}$/.test(value)&&!['__proto__','constructor','prototype'].includes(value);
+const sensitive=/(?:apikey_[A-Za-z0-9_-]{16,}|xai-[A-Za-z0-9_-]{16,}|sk-[A-Za-z0-9_-]{16,}|AKIA[A-Z0-9]{16}|-----BEGIN[^\n]*PRIVATE KEY-----|authorization\s*[:=]|(?:password|api[_-]?key|access[_-]?token)["']?\s*[:=]\s*["']?\S{4,})/i;
+function sensitiveInput(value,depth=0){
+ if(depth>12)return true;
+ if(typeof value==='string'){
+  if(sensitive.test(value)||sensitive.test(value.replace(/\\u([a-f0-9]{4})/gi,(_,hex)=>String.fromCharCode(parseInt(hex,16))).replace(/\\["\\]/g,'')))return true;
+  try{const decoded=JSON.parse(value);if(typeof decoded!=='number'&&typeof decoded!=='boolean'&&decoded!==null&&decoded!==value)return sensitiveInput(decoded,depth+1);}catch{/* Ordinary text is checked above. */}
+  return false;
+ }
+ if(value&&typeof value==='object')return Object.entries(value).some(([key,item])=>/^(?:password|api[_-]?key|access[_-]?token|authorization)$/i.test(key)||sensitiveInput(item,depth+1));
+ return false;
+}
+const digest=value=>createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const plain=value=>Boolean(value&&typeof value==='object'&&!Array.isArray(value));
+const own=(value,fields)=>plain(value)&&Object.keys(value).every(k=>fields.includes(k));
+function fail(code,message){const error=new Error(message);error.code=code;error.statusCode=code==='jev-settings-stale'||code==='jev-storage-busy'?409:400;throw error;}
+function invalid(){fail('jev-input','Use a supported, bounded Jev request.');}
+function stat(path){try{return lstatSync(path);}catch(e){if(e.code==='ENOENT')return null;fail('jev-storage','Jev local state could not be read safely.');}}
+function owned(s){return s&&!s.isSymbolicLink()&&(!process.getuid||s.uid===process.getuid());}
+
+// No source or prompt is stored here. Every file and ancestor is checked before
+// no-follow reads/atomic writes; unsafe operational state prevents paid calls.
+function pathFor(root,name,create=false){
+ const base=realpathSync(resolve(root));
+ const folders=name==='settings'?[resolve(base,'.ewai-pipeline')]:[resolve(base,'.ewai-pipeline'),resolve(base,'.ewai-pipeline/runtime'),resolve(base,'.ewai-pipeline/runtime/jev')];
+ for(const path of folders){let s=stat(path);if(!s&&create){mkdirSync(path,{mode:0o700});s=stat(path);}if(s&&(!owned(s)||!s.isDirectory()||(s.mode&0o022)))fail('jev-storage','Jev local state could not be read safely.');}
+ return resolve(folders.at(-1),name==='settings'?'jev.json':name+'.json');
+}
+function read(root,name,fallback){
+ const path=pathFor(root,name),s=stat(path);if(!s)return structuredClone(fallback);
+ if(!owned(s)||!s.isFile()||s.nlink!==1||(s.mode&0o077)||s.size>1048576)fail('jev-storage','Jev local state could not be read safely.');
+ let fd;try{fd=openSync(path,constants.O_RDONLY|constants.O_NOFOLLOW);const bytes=readFileSync(fd),opened=fstatSync(fd),current=stat(path);if(!current||opened.ino!==s.ino||opened.dev!==s.dev||opened.nlink!==1||current.ino!==s.ino||current.mtimeMs!==s.mtimeMs||opened.mtimeMs!==s.mtimeMs||bytes.length>1048576)fail('jev-storage','Jev local state changed while reading.');return JSON.parse(bytes);}catch(e){if(e.code?.startsWith('jev-'))throw e;fail('jev-storage','Jev local state could not be read safely.');}finally{if(fd!==undefined)closeSync(fd);}
+}
+function write(root,name,value){
+ const path=pathFor(root,name,true),before=stat(path);if(before&&(!owned(before)||!before.isFile()||before.nlink!==1||(before.mode&0o077)))fail('jev-storage','Jev local state could not be written safely.');
+ const temporary=path+'.'+randomUUID()+'.tmp';
+ try{writeFileSync(temporary,JSON.stringify(value)+'\n',{flag:'wx',mode:0o600});pathFor(root,name,true);renameSync(temporary,path);}finally{if(stat(temporary))unlinkSync(temporary);}
+}
+function locked(root,fn){
+ const path=pathFor(root,'state',true),lock=resolve(dirname(path),'.mutation-lock');
+ try{mkdirSync(lock,{mode:0o700});}catch(e){fail(e.code==='EEXIST'?'jev-storage-busy':'jev-storage','Another Jev state change is running or local state is unavailable.');}
+ const identity=lstatSync(lock);
+ try{return fn();}finally{const current=stat(lock);if(owned(current)&&current.ino===identity.ino&&current.dev===identity.dev)rmSync(lock,{recursive:true});}
+}
+function policy(value){
+ // Historical policies disclosed only TypeSafe. Reading or saving that shape
+ // never opts the account into a second vendor or changes its preference.
+ if(plain(value)&&!Object.hasOwn(value,'provider')&&!Object.hasOwn(value,'openaiConsent'))value={...value,provider:'jev',openaiConsent:false};
+ if(!own(value,Object.keys(defaultPolicy))||Object.keys(value).length!==Object.keys(defaultPolicy).length||!['off','shadow','active'].includes(value.mode)||!['auto','openai','jev'].includes(value.provider)||typeof value.openaiConsent!=='boolean'||typeof value.cloudConsent!=='boolean'||!Array.isArray(value.useCases)||value.useCases.length>7||new Set(value.useCases).size!==value.useCases.length||value.useCases.some(v=>!JEV_USE_CASES.includes(v)))invalid();
+ for(const [key,min,max]of [['maxCalls',1,1000],['maxInputTokens',2000,1000000],['timeoutMs',100,10000]])if(!Number.isSafeInteger(value[key])||value[key]<min||value[key]>max)invalid();
+ if(!Number.isFinite(value.minConfidence)||value.minConfidence<0.5||value.minConfidence>1)invalid();
+ if(value.mode!=='off'&&!(value.provider==='openai'?value.openaiConsent:value.provider==='jev'?value.cloudConsent:value.openaiConsent||value.cloudConsent))fail('jev-consent','Confirm the selected provider text disclosure consent before enabling decision assistance.');
+ return structuredClone(value);
+}
+function selectedProvider(root,settings,options={}){
+ const order=settings.policy.provider==='auto'?['openai','jev']:[settings.policy.provider];
+ for(const provider of order){
+  if(!(provider==='openai'?settings.policy.openaiConsent:settings.policy.cloudConsent))continue;
+  try{
+   const o={...options,projectRoot:root},apiKey=provider==='openai'?resolveOpenaiApiKey(o):resolveJevApiKey(o);if(!apiKey)continue;
+   return {provider,apiKey,model:provider==='openai'?OPENAI_DECISIONS_MODEL:JEV_MODEL,endpoint:provider==='openai'?'https://api.openai.com/v1/decisions':'https://api.typesafe.ai/v1/systemone',price:provider==='openai'?0.10:0.042,identity:provider==='openai'?openaiCredentialIdentity(o):jevCredentialIdentity(o)};
+  }catch(error){if(settings.policy.provider!=='auto')throw error;/* An unusable, unselected credential must not disable another authorised vendor. */}
+ }
+ return null;
+}
+const selectedIdentity=selected=>selected?digest({provider:selected.provider,model:selected.model,credential:selected.identity,keyDigest:digest(selected.apiKey)}):'local';
+export function decisionCredentialIdentity(root,options={}){
+ const settings=readJevSettings(root);
+ if(settings.policy.mode==='off')return 'local';
+ // Credential failures cannot interrupt optional persona/context assistance.
+ // A changed identity still invalidates any advice from an earlier request.
+ try{return selectedIdentity(selectedProvider(root,settings,options));}catch{return 'credential-unavailable';}
+}
+export function readDecisionCredentials(root,options={}){
+ const readStatus=(provider,fn)=>{try{return fn({...options,projectRoot:root});}catch{return {provider,configured:null,saved:null,source:'unavailable',storageSupported:false,storageIssue:'credential-unavailable',authority:'credentials-only'};}};
+ return {credentials:readStatus('jev',jevCredentialStatus),openaiCredentials:readStatus('openai',openaiCredentialStatus)};
+}
+export function readJevSettings(root){
+ const value=read(root,'settings',{schema:'ewai.jev-settings/v1',revision:'missing',policy:structuredClone(defaultPolicy)});
+ if(!own(value,['schema','revision','policy'])||value.schema!=='ewai.jev-settings/v1'||typeof value.revision!=='string'||!(/^[a-f0-9-]{36}$/.test(value.revision)||value.revision==='missing'))invalid();
+ return {...value,policy:policy(value.policy)};
+}
+export function saveJevSettings(root,input){
+ if(!own(input,['confirmed','expectedRevision','policy'])||input.confirmed!==true||typeof input.expectedRevision!=='string')invalid();
+ const next=policy(input.policy);
+ return locked(root,()=>{const current=readJevSettings(root);if(current.revision!==input.expectedRevision)fail('jev-settings-stale','Jev settings changed. Refresh before saving again.');const value={schema:'ewai.jev-settings/v1',revision:randomUUID(),policy:next};write(root,'settings',value);return value;});
+}
+function emptyState(revision){return{schema:'ewai.jev-runtime/v1',revision,calls:0,reservedTokens:0,inputTokens:0,estimatedUSD:0,unknownUsage:false,budgetBlocked:false,observations:[],cache:{},pending:{}};}
+function state(root,revision){const value=read(root,'state',emptyState(revision));if(!Object.hasOwn(value,'pending'))value.pending={};if(!Object.hasOwn(value,'estimatedUSD'))value.estimatedUSD=value.inputTokens*0.042/1000000;if(!plain(value.pending)||Object.keys(value.pending).length>1000||Object.entries(value.pending).some(([id,p])=>!validId(id)||!own(p,['settingsRevision'])||typeof p.settingsRevision!=='string'))fail('jev-storage','Jev pending usage could not be read safely.');if(value.schema!=='ewai.jev-runtime/v1'||!Number.isSafeInteger(value.calls)||value.calls<0||!Number.isSafeInteger(value.reservedTokens)||value.reservedTokens<0||!Number.isSafeInteger(value.inputTokens)||value.inputTokens<0||!Number.isFinite(value.estimatedUSD)||value.estimatedUSD<0||typeof value.unknownUsage!=='boolean'||typeof value.budgetBlocked!=='boolean'||!Array.isArray(value.observations)||value.observations.length>500||!plain(value.cache))fail('jev-storage','Jev measurements could not be read safely.');return value.revision===revision?value:{...value,revision,calls:0,reservedTokens:0,budgetBlocked:false,cache:{},pending:{},unknownUsage:value.unknownUsage||Object.keys(value.pending).length>0};}
+function observe(root,revision,observation,cacheEntry){
+ locked(root,()=>{const current=readJevSettings(root),value=state(root,current.revision);delete value.pending[observation.id];value.observations.push({...observation,id:observation.id??randomUUID(),settingsRevision:revision});value.observations=value.observations.slice(-500);if(observation.providerCall){if(observation.inputTokens===null){value.unknownUsage=true;if(current.revision===revision)value.budgetBlocked=true;}else {value.inputTokens+=observation.inputTokens;value.estimatedUSD+=observation.estimatedUSD;}}if(observation.reason==='token-reservation-exceeded'&&current.revision===revision)value.budgetBlocked=true;if(cacheEntry&&current.revision===revision){value.cache[cacheEntry.key]=cacheEntry.value;while(Buffer.byteLength(JSON.stringify(value.cache))>131072)delete value.cache[Object.keys(value.cache)[0]];}write(root,'state',value);});
+}
+export function readJevMeasurements(root){
+ const settings=readJevSettings(root),value=state(root,settings.revision),latencies=value.observations.filter(o=>o.providerCall).map(o=>o.elapsedMs).sort((a,b)=>a-b);
+ return {schema:'ewai.jev-measurements/v1',revision:settings.revision,budget:{callsUsed:value.calls,maxCalls:settings.policy.maxCalls,reservedTokens:value.reservedTokens,maxInputTokens:settings.policy.maxInputTokens},summary:{unresolvedCalls:Object.keys(value.pending).length,historyLimit:500,historyScope:'latest 500 observation events; input/cost totals cover all recorded provider calls',providerCalls:value.observations.filter(o=>o.providerCall).length,cacheHits:value.observations.filter(o=>o.cacheHit).length,fallbacks:value.observations.filter(o=>o.status==='fallback').length,inputTokens:value.unknownUsage||Object.keys(value.pending).length?null:value.inputTokens,estimatedUSD:value.unknownUsage||Object.keys(value.pending).length?null:value.estimatedUSD,medianMs:latencies.length?latencies[Math.floor(latencies.length/2)]:null,p95Ms:latencies.length?latencies[Math.min(latencies.length-1,Math.ceil(latencies.length*0.95)-1)]:null,downstreamSavings:null,priceSource:'Base-rate estimates: TypeSafe models and OpenAI Decisions guide; OpenAI estimate precedes free cache adjustments and regional/long-context premiums',priceUSDPerMillionInputTokens:null,priceByProvider:{jev:0.042,openai:0.10}},observations:value.observations};
+}
+export function recordJevEffect(root,decision,details){
+ if(!decision?.measurement?.id)return;
+ if(!own(details,['effect','baselineIds','suggestedIds','actualIds'])||!['unchanged','context-ordering','persona-additions','review-addition'].includes(details.effect))invalid();
+ for(const ids of [details.baselineIds,details.suggestedIds,details.actualIds])if(!Array.isArray(ids)||ids.length>64||ids.some(id=>!validId(id)))invalid();
+ const revision=readJevSettings(root).revision;
+ observe(root,revision,{id:randomUUID(),decisionId:decision.measurement.id,useCase:decision.measurement.useCase,provider:decision.measurement.provider??'jev',model:decision.measurement.model??JEV_MODEL,mode:decision.mode,status:'effect-recorded',providerCall:false,cacheHit:false,elapsedMs:0,inputTokens:0,outputTokens:0,estimatedUSD:0,downstreamSavings:null,...details});
+}
+function question(q){
+ if(!own(q,['type','instructions','criteria'])||!['choice','score','noul'].includes(q.type)||typeof q.instructions!=='string'||!q.instructions.trim()||q.instructions.length>2000)invalid();
+ if(q.type==='choice'){if(!plain(q.criteria)||Object.keys(q.criteria).length<2||Object.keys(q.criteria).length>64||Object.entries(q.criteria).some(([k,v])=>!validId(k)||typeof v!=='string'||v.length>1000))invalid();}
+ if(q.type==='score'&&(!Array.isArray(q.criteria)||q.criteria.length<2||q.criteria.length>10||q.criteria.some(v=>typeof v!=='string'||!v.trim()||v.length>1000)))invalid();
+ if(q.type==='noul'&&q.criteria!==undefined&&(!own(q.criteria,['true','false'])||Object.values(q.criteria).some(v=>typeof v!=='string'||v.length>1000)))invalid();
+ return q;
+}
+function usage(body){const u=body?.usage;return own(u,['input_tokens','output_tokens'])&&Number.isSafeInteger(u.input_tokens)&&u.input_tokens>=0&&Number.isSafeInteger(u.output_tokens)&&u.output_tokens>=0?{inputTokens:u.input_tokens,outputTokens:u.output_tokens}:null;}
+function validatedAnswers(body,questions){
+ if(body?.model!==JEV_MODEL||!plain(body.answers)||Object.keys(body.answers).length!==Object.keys(questions).length)throw Error('invalid-response');
+ const output={};
+ for(const [id,q]of Object.entries(questions)){
+  const a=body.answers[id];if(!plain(a)||a.type!==q.type)throw Error('invalid-response');
+  if(q.type==='noul'){if(!own(a,['type','noul'])||!Number.isFinite(a.noul)||a.noul<0||a.noul>1)throw Error('invalid-response');output[id]={type:'noul',noul:a.noul};continue;}
+  const keys=q.type==='choice'?Object.keys(q.criteria):q.criteria.map((_,i)=>String(i));
+  if(!own(a,q.type==='choice'?['type','choice','probabilities','confidence']:['type','score','legend','probabilities','confidence'])||!plain(a.probabilities)||Object.keys(a.probabilities).length!==keys.length||!keys.every(k=>Object.hasOwn(a.probabilities,k))||!Object.values(a.probabilities).every(p=>Number.isFinite(p)&&p>=0&&p<=1)||Math.abs(Object.values(a.probabilities).reduce((s,p)=>s+p,0)-1)>0.001||!Number.isFinite(a.confidence)||a.confidence<0||a.confidence>1)throw Error('invalid-response');
+  if(q.type==='choice'){
+   if(!keys.includes(a.choice)||a.probabilities[a.choice]+1e-9<Math.max(...Object.values(a.probabilities)))throw Error('invalid-response');output[id]={type:'choice',choice:a.choice,probabilities:a.probabilities,confidence:a.confidence};
+  }else{
+   const expected=keys.reduce((s,k)=>s+Number(k)*a.probabilities[k],0);
+   if(!Number.isFinite(a.score)||a.score<0||a.score>q.criteria.length-1||Math.abs(a.score-expected)>0.01||!plain(a.legend)||Object.keys(a.legend).length!==keys.length||!keys.every(k=>a.legend[k]===q.criteria[Number(k)]))throw Error('invalid-response');output[id]={type:'score',score:a.score,confidence:a.confidence,probabilities:a.probabilities,legend:a.legend};
+  }
+ }
+ return output;
+}
+async function boundedResponse(response){
+ const chunks=[];let size=0;
+ if(!response.body)throw Error('invalid-response');
+ for await(const chunk of response.body){size+=chunk.length;if(size>65536)throw Error('response-too-large');chunks.push(chunk);}
+ try{return JSON.parse(Buffer.concat(chunks).toString('utf8'));}catch{throw Error('invalid-response');}
+}
+export async function evaluateJev(root,input,options={}){
+ const started=performance.now();let settings,selected,apiKey,reservation,controller,timer,watcher,providerUsage=null,dispatched=false;
+ const fallback=(reason,status='fallback',extra={})=>({schema:'ewai.jev-decision/v1',status,reason,mode:settings?.policy.mode??'off',authority:'advisory',...extra});
+ try{
+  settings=readJevSettings(root);
+  if(settings.policy.mode==='off')return fallback('off','disabled');
+  if(!own(input,['useCase','source','state','questions'])||!JEV_USE_CASES.includes(input.useCase))invalid();
+  if(!settings.policy.useCases.includes(input.useCase))return fallback('use-case-disabled','disabled');
+  if(!sources.has(input.source))return fallback('source-ineligible');
+
+  if(!plain(input.questions)||Object.keys(input.questions).length<1||Object.keys(input.questions).length>32||Object.keys(input.questions).some(id=>!validId(id)))invalid();
+  Object.values(input.questions).forEach(question);
+  const neutralPayload={model:JEV_MODEL,state:input.state,questions:input.questions};
+  if(sensitiveInput(neutralPayload))return fallback('sensitive-input');
+  selected=selectedProvider(root,settings,options);if(!selected)return fallback('missing-key');apiKey=selected.apiKey;
+  const payload=selected.provider==='openai'?buildOpenaiDecisionPayload(input.state,input.questions):neutralPayload,serialised=JSON.stringify(payload);
+  if(!['string','object'].includes(typeof input.state)||input.state===null||Buffer.byteLength(serialised)>16000)invalid();
+  if(sensitiveInput(payload))return fallback('sensitive-input');
+
+  if(serialised.includes(apiKey))return fallback('sensitive-input');
+  // UTF-8 bytes plus headroom is a conservative local reservation, not a
+  // claimed token count. Unknown/over-reservation usage exhausts the budget.
+  const namespace=selectedIdentity(selected);
+  const reserve=Buffer.byteLength(serialised)+1024,cacheKey=digest({revision:settings.revision,credential:namespace,provider:selected.provider,model:selected.model,source:input.source,useCase:input.useCase,payload});
+  reservation=locked(root,()=>{
+   if(digest(readJevSettings(root))!==digest(settings))return {reason:'policy-changed'};
+   const value=state(root,settings.revision),cached=value.cache[cacheKey];
+   if(cached){try{const answers=Object.fromEntries(Object.entries(cached.answers).map(([id,a])=>[id,a.type==='score'?{...a,legend:Object.fromEntries(input.questions[id].criteria.map((label,index)=>[String(index),label]))}:a]));validatedAnswers({model:JEV_MODEL,answers},input.questions);return {cached:{answers}};}catch{return {reason:'invalid-cache'};}}
+   if(value.budgetBlocked||Object.keys(value.pending).length||value.calls>=settings.policy.maxCalls||value.reservedTokens+reserve>settings.policy.maxInputTokens)return {reason:'budget-exhausted'};
+   const id=randomUUID();value.calls++;value.reservedTokens+=reserve;value.pending[id]={settingsRevision:settings.revision};write(root,'state',value);return {id,reserve,cacheKey};
+  });
+  if(reservation.reason)return fallback(reservation.reason);
+  const stillCurrent=()=>digest(readJevSettings(root))===digest(settings)&&decisionCredentialIdentity(root,options)===namespace;
+  if(reservation.cached){
+   if(!stillCurrent())return fallback('policy-changed');
+   const measurement={id:randomUUID(),useCase:input.useCase,provider:selected?.provider??null,model:selected?.model??null,mode:settings.policy.mode,status:'suggested',providerCall:false,cacheHit:true,elapsedMs:Math.round(performance.now()-started),inputTokens:0,outputTokens:0,estimatedUSD:0,effect:settings.policy.mode==='shadow'?'shadow':'advisory',downstreamSavings:null};
+   observe(root,settings.revision,measurement);return {...fallback('cached','suggested'),answers:reservation.cached.answers,cacheHit:true,measurement};
+  }
+  if(!stillCurrent())throw Error('policy-changed');
+  controller=new AbortController();let rejectDeadline;
+  const deadline=new Promise((_,reject)=>{rejectDeadline=reject;timer=setTimeout(()=>{controller.abort();reject(Error('timeout'));},settings.policy.timeoutMs);});
+  watcher=setInterval(()=>{try{if(!stillCurrent()){controller.abort();rejectDeadline(Error('policy-changed'));}}catch{controller.abort();rejectDeadline(Error('policy-changed'));}},100);
+  const operation=(async()=>{
+   dispatched=true;const response=await(options.fetchImpl??fetch)(selected.endpoint,{method:'POST',headers:{authorization:'Bearer '+apiKey,'content-type':'application/json'},body:serialised,redirect:'manual',signal:controller.signal});
+   if(!response.ok){if(response.body)void response.body.cancel().catch(()=>{});throw Error('http-'+response.status);}
+   return boundedResponse(response);
+  })();
+  const body=await Promise.race([operation,deadline]);providerUsage=selected.provider==='openai'?openaiDecisionUsage(body):usage(body);
+  if(!providerUsage)throw Error('missing-usage');
+  if(providerUsage.inputTokens>reserve)throw Error('token-reservation-exceeded');
+  const answers=validatedAnswers(selected.provider==='openai'?normaliseOpenaiDecisionResponse(body,input.questions):body,input.questions);
+  if(!stillCurrent())throw Error('policy-changed');
+  if(Object.values(answers).some(a=>a.type!=='noul'&&a.confidence<settings.policy.minConfidence))throw Error('low-confidence');
+  const measurement={id:reservation.id,useCase:input.useCase,provider:selected?.provider??null,model:selected?.model??null,mode:settings.policy.mode,status:'suggested',providerCall:true,cacheHit:false,elapsedMs:Math.round(performance.now()-started),...providerUsage,estimatedUSD:providerUsage.inputTokens*selected.price/1000000,effect:settings.policy.mode==='shadow'?'shadow':'advisory',downstreamSavings:null};
+  // Choice cache carries bounded IDs and numeric probabilities/confidence,
+  // never rubrics, instructions or source bodies.
+  const cachedAnswers=Object.fromEntries(Object.entries(answers).map(([id,a])=>[id,a.type==='choice'?{...a}:a.type==='noul'?{...a}:{...a,legend:{}}]));
+  // Score legends are reconstructed from the caller's matching hashed rubric.
+  // Persist only numeric results and bounded IDs, never catalogue descriptions.
+  const cacheEntry={key:cacheKey,value:{answers:cachedAnswers}};
+  observe(root,settings.revision,measurement,cacheEntry);
+  return {...fallback('evaluated','suggested'),answers,cacheHit:false,measurement};
+ }catch(error){
+  const allowed=/^(?:timeout|policy-changed|invalid-response|refusal|response-too-large|missing-usage|token-reservation-exceeded|low-confidence|http-\d{3})$/;
+  const reason=allowed.test(error?.message??'')?error.message:error.code?.startsWith('jev-')?'local-state-or-input-unavailable':'provider-unavailable';
+  const result=fallback(reason);
+  if(reservation?.reserve){
+   const measurement={id:reservation.id,useCase:input.useCase,provider:selected?.provider??null,model:selected?.model??null,mode:settings.policy.mode,status:'fallback',reason,providerCall:dispatched,cacheHit:false,elapsedMs:Math.round(performance.now()-started),...providerUsage,inputTokens:providerUsage?.inputTokens??(dispatched?null:0),outputTokens:providerUsage?.outputTokens??(dispatched?null:0),estimatedUSD:providerUsage?providerUsage.inputTokens*selected.price/1000000:dispatched?null:0,effect:'none',downstreamSavings:null};
+   try{observe(root,settings.revision,measurement);}catch{/* No unsafe diagnostic or source is emitted. */}result.measurement=measurement;
+  }
+  return result;
+ }finally{clearTimeout(timer);clearInterval(watcher);controller?.abort();apiKey=undefined;}
+}
+export function safeJevError(error){return {code:error?.code?.startsWith('jev-')?error.code:'jev-input',error:error?.code?.startsWith('jev-')?error.message:'Jev could not complete this request. Refresh status and try again.'};}

package/src/openai-credentials.mjs

@@ -0,0 +1,104 @@
+// OpenAI uses the same audited private storage safeguards as Grok, with a separate key lifecycle.
+import {constants,openSync,closeSync,fstatSync,lstatSync,realpathSync,readFileSync,mkdirSync,writeFileSync,renameSync,unlinkSync,rmSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {resolve,relative,isAbsolute} from 'node:path';
+import {randomUUID,createHash} from 'node:crypto';
+
+const messages={
+ 'openai-credential-invalid':'Provide a valid OpenAI API key using the private setup form or hidden terminal prompt.',
+ 'openai-credential-input':'Use the supported credential action and confirm the change.',
+ 'openai-credential-unsafe-storage':'Private credential storage is unsafe or unavailable. Repair its permissions or use OPENAI_API_KEY in the launching environment.',
+ 'openai-credential-invalid-storage':'The saved credential could not be read safely. Repair the private credential file before continuing.',
+ 'openai-credential-stale':'The saved credential changed. Refresh its status and try again.',
+ 'openai-credential-busy':'Another credential change is running. Retry after it finishes.',
+ 'openai-credential-missing':'No OpenAI key is configured. Use private credential setup or OPENAI_API_KEY in the launching environment.',
+ 'openai-key-rejected':'The metadata authentication check was not accepted. Check the key and its models-read permission, then try again. This does not determine Decisions endpoint access. The previous saved key was retained.',
+ 'openai-check-rate-limited':'OpenAI limited the authentication check. Wait before trying again. The previous saved key was retained.',
+ 'openai-check-unavailable':'The authentication check could not complete. Check your connection and try again. The previous saved key was retained.',
+};
+function fail(code,statusCode=400){const error=new Error(messages[code]??messages['openai-credential-input']);error.code=code;error.statusCode=statusCode;throw error;}
+function key(value){if(typeof value!=='string'||value.length>512||!/^sk-[A-Za-z0-9_-]{16,508}$/.test(value.trim()))fail('openai-credential-invalid');return value.trim();}
+function request(input,fields){if(!input||typeof input!=='object'||Array.isArray(input)||Object.keys(input).some(k=>!fields.includes(k))||input.confirmed!==true||typeof input.expectedRevision!=='string'||input.expectedRevision.length>80)fail('openai-credential-input');}
+function stat(path){try{return lstatSync(path);}catch(error){if(error.code==='ENOENT')return null;fail('openai-credential-unsafe-storage');}}
+function owned(s){return s&&!s.isSymbolicLink()&&(process.getuid===undefined||s.uid===process.getuid());}
+function paths(options={},create=false){
+ const declaredHome=resolve(options.home??homedir());
+ const root=stat(declaredHome);if(!owned(root)||!root.isDirectory()||(root.mode&0o022))fail('openai-credential-unsafe-storage');
+ let home,project;try{home=realpathSync(declaredHome);if(options.projectRoot)project=realpathSync(resolve(options.projectRoot));}catch{fail('openai-credential-unsafe-storage');}
+ const folder=resolve(home,'.ewai/credentials'),file=resolve(folder,'openai.json');
+ if(project){const rel=relative(project,file);if(rel===''||(!isAbsolute(rel)&&rel!=='..'&&!rel.startsWith('../')))fail('openai-credential-unsafe-storage');}
+ const canonicalRoot=stat(home);if(!owned(canonicalRoot)||canonicalRoot.ino!==root.ino||canonicalRoot.dev!==root.dev)fail('openai-credential-unsafe-storage');
+ for(const path of [resolve(home,'.ewai'),folder]){
+  let s=stat(path);if(!s&&create){try{mkdirSync(path,{mode:0o700});}catch(error){if(error.code!=='EEXIST')fail('openai-credential-unsafe-storage');}s=stat(path);}
+  if(s&&(!owned(s)||!s.isDirectory()||(s.mode&(path===folder?0o077:0o022))))fail('openai-credential-unsafe-storage');
+ }
+ return {folder,file,location:JSON.stringify([home,root.dev,root.ino])};
+}
+function stored(options={}){
+ const {file,location}=paths(options),before=stat(file);if(!before)return {value:null,signature:'missing',location};
+ if(process.platform==='win32'||!owned(before)||!before.isFile()||before.nlink!==1||(before.mode&0o077)||before.size>4096)fail('openai-credential-unsafe-storage');
+ let fd;try{
+  fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW);const bytes=readFileSync(fd),after=fstatSync(fd),current=stat(file);
+  if(bytes.length>4096||!current||before.ino!==after.ino||before.dev!==after.dev||before.mtimeMs!==after.mtimeMs||after.ino!==current.ino||after.mtimeMs!==current.mtimeMs)fail('openai-credential-unsafe-storage');
+  let value;try{value=JSON.parse(bytes.toString('utf8'));}catch{fail('openai-credential-invalid-storage');}
+  if(value?.schema!=='ewai.openai-credential/v1'||typeof value.revision!=='string'||!/^[a-f0-9-]{36}$/.test(value.revision)||Object.keys(value).some(k=>!['schema','revision','apiKey'].includes(k)))fail('openai-credential-invalid-storage');
+  try{key(value.apiKey);}catch{fail('openai-credential-invalid-storage');}
+  return {value,location,signature:JSON.stringify([after.dev,after.ino,after.mtimeMs,after.ctimeMs,createHash('sha256').update(bytes).digest('hex')])};
+ }catch(error){if(error.code?.startsWith('openai-'))throw error;fail('openai-credential-unsafe-storage');}finally{if(fd!==undefined)closeSync(fd);}
+}
+function environment(options){const env=options.env??process.env;return env.OPENAI_API_KEY?key(env.OPENAI_API_KEY):null;}
+export function openaiCredentialStatus(options={}){
+ const override=environment(options);let value,storageIssue=null;
+ try{({value}=stored(options));}catch(error){if(!override)throw error;storageIssue='unsafe-saved-storage';}
+
+ return {schema:'ewai.openai-credential-status/v1',provider:'openai',configured:Boolean(override||value),saved:storageIssue?null:Boolean(value),storageIssue,source:override?'environment':value?'saved':'missing',revision:value?.revision??(storageIssue?'unavailable':'missing'),storage:'owner-only-local-file',encrypted:false,storageSupported:!storageIssue&&process.platform!=='win32',authority:'credentials-only'};
+}
+export function resolveOpenaiApiKey(options={}){const override=environment(options);return override??stored(options).value?.apiKey??null;}
+function predecessor(input,options,expected){const current=stored(options);if((current.value?.revision??'missing')!==input.expectedRevision||(expected&&(current.signature!==expected.signature||current.location!==expected.location)))fail('openai-credential-stale',409);return current;}
+function mutation(options,operation){
+ if(process.platform==='win32')fail('openai-credential-unsafe-storage');
+ const {folder}=paths(options,true),lock=resolve(folder,'.openai.lock');
+ try{mkdirSync(lock,{mode:0o700});}catch(error){fail(error.code==='EEXIST'?'openai-credential-busy':'openai-credential-unsafe-storage',409);}
+ const identity=lstatSync(lock);
+ try{return operation();}finally{const current=stat(lock);if(owned(current)&&current.isDirectory()&&current.ino===identity.ino)rmSync(lock,{recursive:true});}
+}
+async function authenticate(apiKey,options={}){
+ const controller=new AbortController();let timer;
+ try{
+  const timeout=Math.min(10000,Math.max(10,options.timeoutMs??10000));
+  const response=await Promise.race([(options.fetchImpl??fetch)('https://api.openai.com/v1/models',{method:'GET',headers:{authorization:'Bearer '+apiKey},redirect:'manual',signal:controller.signal}),new Promise((_,reject)=>{timer=setTimeout(()=>{controller.abort();reject(Error('deadline'));},timeout);})]);
+  // Discard provider bodies, including errors. They are not safe evidence.
+  if(response.body)void response.body.cancel().catch(()=>{});
+  if(response.status===200)return {status:'verified',code:'openai-authentication-verified',message:'OpenAI authentication check passed. No output was generated; Decisions endpoint access, credit and decision quality remain unverified.'};
+  const code=[401,403].includes(response.status)?'openai-key-rejected':response.status===429?'openai-check-rate-limited':'openai-check-unavailable';return {status:'failed',code,message:messages[code]};
+ }catch{return {status:'failed',code:'openai-check-unavailable',message:messages['openai-check-unavailable']};}
+ finally{clearTimeout(timer);controller.abort();}
+}
+export async function checkOpenaiConnection(options={}){
+ const apiKey=resolveOpenaiApiKey(options);
+ if(!apiKey)return {...openaiCredentialStatus(options),status:'failed',code:'openai-credential-missing',message:messages['openai-credential-missing']};
+ return {...openaiCredentialStatus(options),...await authenticate(apiKey,options)};
+}
+// Internal cache identity includes physical file identity and exact bytes; it
+// is never included in status, diagnostics or model-facing credential tools.
+export function openaiCredentialIdentity(options={}) {
+ const override=environment(options);if(override)return createHash('sha256').update('environment '+override).digest('hex');
+ const value=stored(options);return createHash('sha256').update(value.location+' '+value.signature).digest('hex');
+}
+export async function configureOpenaiCredentials(input,options={}){
+ request(input,['confirmed','expectedRevision','apiKey']);const apiKey=key(input.apiKey);environment(options);const previous=predecessor(input,options);
+ const check=await authenticate(apiKey,options);if(check.status!=='verified')fail(check.code);
+ mutation(options,()=>{
+  predecessor(input,options,previous);const {file}=paths(options,true),temporary=file+'.'+randomUUID()+'.tmp';
+  try{writeFileSync(temporary,JSON.stringify({schema:'ewai.openai-credential/v1',revision:randomUUID(),apiKey})+'\n',{flag:'wx',mode:0o600});paths(options);predecessor(input,options,previous);renameSync(temporary,file);}
+  catch(error){if(error.code?.startsWith('openai-'))throw error;fail('openai-credential-unsafe-storage');}
+  finally{if(stat(temporary))unlinkSync(temporary);}
+ });
+ return {...openaiCredentialStatus(options),check,message:'OpenAI key checked and saved for your account on this computer. No work started.'};
+}
+export function removeOpenaiCredentials(input,options={}){
+ request(input,['confirmed','expectedRevision']);environment(options);const previous=predecessor(input,options);
+ mutation(options,()=>{const current=predecessor(input,options,previous);if(current.value)unlinkSync(paths(options).file);});
+ const status=openaiCredentialStatus(options);return {...status,message:status.source==='environment'?'Saved key removed. OPENAI_API_KEY still supplies the active credential.':'Saved OpenAI key removed. No work started.'};
+}
+export function safeOpenaiCredentialError(error){const code=Object.hasOwn(messages,error?.code)?error.code:'openai-credential-input';return {error:messages[code],code};}