@starci/hfs 4.0.9 → 4.1.0

package/runtime/engine/invalid-config.mjs

@@ -1,15 +1,15 @@
 import path from 'node:path';
 import {isPlainObject as plain} from './plain-object.mjs';
 /** The one `Invalid config.yaml:` raiser every section validator shares: bad('<rest>') throws it. */
-export const invalid=section=>message=>{throw Error(`Invalid config.yaml: ${section}${message}`);};
+export const invalid=section=>message=>{throw new Error(`Invalid config.yaml: ${section}${message}`);};
 
-/** The host roots the owner may relocate (config.yaml `roots`): the archive root and the lanes root. */
-const ROOT_KEYS=Object.freeze(['archive','lanes']);
-/** config.yaml `roots` - {archive?, lanes?}: absolute directories, or null; an absent key means <starciLocalRoot>/archive and <starciLocalRoot>/lanes. */
+/** The host roots the owner may relocate (config.yaml `roots`): the archive root, the lanes root and the temp root. */
+export const ROOT_KEYS=Object.freeze(['archive','lanes','temp']);
+/** config.yaml `roots` - {archive?, lanes?, temp?}: absolute directories, or null; an absent key means <starciLocalRoot>/archive and the per-user lanes directory (scripts/machine/home.mjs lanesDefault). */
 export function validateRoots(roots){
   if(roots===null)return;
   const bad=invalid('roots');
-  if(!plain(roots))bad(` must be {archive?: <absolute directory>, lanes?: <absolute directory>} or null.`);
+  if(!plain(roots))bad(` must be {archive?: <absolute directory>, lanes?: <absolute directory>, temp?: <absolute directory>} or null.`);
   for(const key of Object.keys(roots))if(!ROOT_KEYS.includes(key))bad(` has unknown key ${key} (allowed: ${ROOT_KEYS.join(', ')}).`);
   for(const key of ROOT_KEYS)if(roots[key]!==undefined&&roots[key]!==null&&!(typeof roots[key]==='string'&&roots[key].trim()&&path.isAbsolute(roots[key])))bad(`.${key} must be an absolute directory path or null.`);
 }

package/runtime/engine/model-config.mjs

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {parseYaml} from './yaml.mjs';
+import {isPlainObject as plain} from './plain-object.mjs';
+import {invalid} from './invalid-config.mjs';
+import {byCodeUnit} from './by-code-unit.mjs';
+import {removedOfKind} from './removed-vocabulary.mjs';
+
+/** The effort vocabulary, ordered weakest to strongest — the only list of it. */
+export const EFFORT_LEVELS=new Set(['none','minimal','low','medium','high','xhigh','max','ultra']);
+const DIFFICULTIES=['easy','medium','hard','insane'];
+export const MODELS_KEYS=['tiers','seats','balance','usage'];
+const known=names=>[...names].sort(byCodeUnit).join(', ');
+
+const hasPath=(root,dotted)=>dotted.split('.').reduce((node,key)=>(plain(node)&&Object.hasOwn(node,key)?node[key]:undefined),root)!==undefined;
+
+/** Refuse an old-shape config (the removed keys of modules/kernel/removed-vocabulary.yaml), naming every removed key and where its meaning lives now. */
+export function refuseRemovedKeys(config){
+  const found=removedOfKind('config-key').filter(({name})=>hasPath(config,name));
+  if(!found.length)return;
+  const removed=found.map(({name,use})=>`${name} is removed (${use})`).join('; ');
+  throw new Error(`Invalid config.yaml: ${removed}.`);
+}
+
+let shippedCache=null;
+/** modules/models/tiers.yaml as shipped, parsed once per file version. */
+export function shippedTiers(){
+  const file=fileURLToPath(new URL('../modules/models/tiers.yaml',import.meta.url));
+  let stat;try{stat=fs.statSync(file);}catch{throw new Error('Missing modules/models/tiers.yaml');}
+  const version=`${stat.mtimeMs}:${stat.size}`;
+  if(shippedCache?.version!==version)shippedCache={version,doc:parseYaml(fs.readFileSync(file,'utf8'))};
+  return structuredClone(shippedCache.doc);
+}
+
+function validateMember(bad,where,member,profile){
+  if(!plain(member)||Object.keys(member).some(key=>!['agent','model','effort'].includes(key))||typeof member.agent!=='string'||typeof member.model!=='string')
+    bad(`${where} must be {agent, model, effort?}.`);
+  if(profile.models?.[member.model]?.provider!==member.agent)bad(`${where}: model ${member.model} is not declared by agent ${member.agent} in modules/models/registry.yaml models.`);
+  if(member.effort!==undefined&&!EFFORT_LEVELS.has(member.effort))bad(`${where}.effort must use the effort vocabulary.`);
+}
+
+function validateChains(bad,tiers,profile){
+  for(const [name,chain] of Object.entries(tiers)){
+    if(!Array.isArray(chain)||!chain.length)bad(`.${name} must be a non-empty ordered list of {agent, model, effort?}.`);
+    chain.forEach((member,index)=>validateMember(bad,`.${name}[${index}]`,member,profile));
+    if(new Set(chain.map(member=>`${member.agent}/${member.model}`)).size!==chain.length)bad(`.${name} names each member once.`);
+  }
+}
+
+/** A call tier is taken by a headless call only: no seat, difficulty, kind, order or caller reference may name it, and every call names one. */
+function validateUse(bad,{doc,names,refs}){
+  const callTiers=new Set(Object.entries(doc.tierUse).filter(([,use])=>use==='call').map(([tier])=>tier));
+  for(const tier of Object.keys(doc.tierUse))if(!names.has(tier))bad(`: tierUse names tier ${tier} (known: ${known(names)}).`);
+  for(const [where,tier] of refs)if(callTiers.has(tier))bad(`: ${where} names tier ${tier}, a call tier (tierUse): a headless call is made on it, no seat or op is seated on it.`);
+  for(const [call,spec] of Object.entries(doc.calls))if(!callTiers.has(spec.tier))bad(`: calls.${call}.tier ${spec.tier} must be a tier whose tierUse is call.`);
+}
+
+/** The tier document the picker reads: the shipped tiers.yaml with config.yaml `models` laid over it. Validated. */
+export function effectiveTiers(config,profile){
+  const doc=shippedTiers(),models=plain(config?.models)?config.models:{};
+  const bad=invalid('models');
+  const tiers={...doc.tiers,...models.tiers};
+  validateChains(bad,tiers,profile);
+  const seats={...doc.seats,...models.seats};
+  const balance={...doc.balance,...models.balance};
+  const usage={...doc.usage,...models.usage};
+  const names=new Set(Object.keys(tiers));
+  const refs=[...Object.entries(seats).map(([seat,tier])=>[`.seats.${seat}`,tier]),...DIFFICULTIES.map(level=>[`difficulty.${level}`,doc.difficulty[level]]),
+    ...Object.entries(doc.kindTiers).map(([kind,tier])=>[`kindTiers.${kind}`,tier]),...doc.tierOrder.map(tier=>['tierOrder',tier])];
+  for(const [where,tier] of refs)if(!names.has(tier))bad(`: ${where} names tier ${tier} (known: ${known(names)}).`);
+  validateUse(bad,{doc,names,refs});
+  if(!(Number.isInteger(balance.maxStreak)&&balance.maxStreak>=1))bad('.balance.maxStreak must be an integer >= 1.');
+  if(!(typeof balance.maxSharePercent==='number'&&balance.maxSharePercent>0&&balance.maxSharePercent<=100))bad('.balance.maxSharePercent must be a number in (0, 100].');
+  const {reservePercent,biasPercent,exhaustedPercent}=usage;
+  if(![reservePercent,biasPercent,exhaustedPercent].every(value=>typeof value==='number'&&value>=0&&value<=100)||!(reservePercent<=biasPercent&&biasPercent<exhaustedPercent))
+    bad('.usage must hold numbers with reservePercent <= biasPercent < exhaustedPercent, each within 0..100.');
+  return {...doc,tiers,seats,balance,usage};
+}
+
+/** config.yaml `models` — {tiers?, seats?, balance?, usage?}; the shipped defaults make every key optional. */
+export function validateModelsBlock(config,profile){
+  refuseRemovedKeys(config);
+  const models=config?.models;
+  if(models===undefined||models===null)return;
+  const bad=invalid('models');
+  if(!plain(models)||Object.keys(models).some(key=>!MODELS_KEYS.includes(key)))bad(` must be {${MODELS_KEYS.map(key=>key+'?').join(', ')}} or null (unknown keys are refused).`);
+  if(models.tiers!==undefined&&!plain(models.tiers))bad('.tiers must map tier names to ordered member lists.');
+  for(const key of ['seats','balance','usage'])if(models[key]!==undefined&&!plain(models[key]))bad(`.${key} must be a mapping.`);
+  effectiveTiers(config,profile);
+}

package/runtime/engine/orca-config.mjs

@@ -10,12 +10,14 @@ import {invalid} from './invalid-config.mjs';
  * a measured probe (scripts/agent/depth-probe.mjs).
  */
 export const ORCA_DEFAULTS=Object.freeze({maxWorkerDepth:4});
+/** The keys of the orca block. */
+export const ORCA_KEYS=Object.freeze(Object.keys(ORCA_DEFAULTS));
 export const MAX_WORKER_DEPTH_CEILING=16;
 export function validateOrca(orca){
   if(orca===null)return;
   const bad=invalid('orca');
   if(!plain(orca))bad(' must be {maxWorkerDepth?} or null.');
-  for(const key of Object.keys(orca))if(key!=='maxWorkerDepth')bad(` has unknown key ${key} (allowed: maxWorkerDepth).`);
+  for(const key of Object.keys(orca))if(!ORCA_KEYS.includes(key))bad(` has unknown key ${key} (allowed: ${ORCA_KEYS.join(', ')}).`);
   const v=orca.maxWorkerDepth;
   if(v!==undefined&&v!==null&&!(Number.isInteger(v)&&v>=1&&v<=MAX_WORKER_DEPTH_CEILING))bad(`.maxWorkerDepth must be an integer from 1 to ${MAX_WORKER_DEPTH_CEILING} equal to the Orca app's worker depth setting (default ${ORCA_DEFAULTS.maxWorkerDepth}), or null.`);
 }

package/runtime/engine/removed-vocabulary.mjs

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {parseYaml} from './yaml.mjs';
+
+const FILE=fileURLToPath(new URL('../modules/kernel/removed-vocabulary.yaml',import.meta.url));
+
+let cache=null;
+function loaded(){
+  let stat;try{stat=fs.statSync(FILE);}catch{throw new Error('Missing modules/kernel/removed-vocabulary.yaml');}
+  const version=`${stat.mtimeMs}:${stat.size}`;
+  if(cache?.version!==version)cache={version,doc:parseYaml(fs.readFileSync(FILE,'utf8'))};
+  return cache.doc;
+}
+
+/** The kinds a removed spelling has. */
+export const removedKinds=()=>loaded().kinds;
+
+/** modules/kernel/removed-vocabulary.yaml: the one list of spellings the runtime refuses, each with its replacement and the release that removed it. */
+export const removedVocabulary=()=>loaded().removed;
+
+/** The removed spellings of one kind. */
+export const removedOfKind=kind=>removedVocabulary().filter(entry=>entry.kind===kind);
+
+/** `<name> is removed (<replacement>)` for a removed spelling of the kind, or undefined when the name is not one. */
+export function removedNotice(kind,name){
+  const entry=removedOfKind(kind).find(candidate=>candidate.name===name);
+  return entry?`${entry.name} is removed (${entry.use})`:undefined;
+}

package/runtime/engine/resources-config.mjs

@@ -0,0 +1,52 @@
+import {isPlainObject as plain} from './plain-object.mjs';
+import {invalid} from './invalid-config.mjs';
+
+/**
+ * config.yaml `resources` — the owner's host-capacity floors, which override the shipped numbers of
+ * modules/models/runtimes.yaml `allocation.resources`. minFreeDiskGb: the free space a drive holding the temp root or the
+ * repository must keep before `starci kernel dispatch --spawn` launches another worker. minFreeDiskPct: the same floor as a
+ * percentage of the drive's size; when both are set the larger requirement applies. minFreeRamPct: the free-RAM floor below
+ * which no new heavy op starts. A null or absent key leaves the shipped number.
+ */
+const FLOOR_LIMITS=Object.freeze({minFreeDiskGb:Infinity,minFreeDiskPct:100,minFreeRamPct:100});
+const inRange=(value,limit)=>typeof value==='number'&&Number.isFinite(value)&&value>0&&value<=limit;
+
+/** The keys of the resources block. */
+export const RESOURCE_KEYS=Object.freeze(Object.keys(FLOOR_LIMITS));
+
+export function validateResources(resources){
+  if(resources===null)return;
+  const bad=invalid('resources');
+  const keys=RESOURCE_KEYS;
+  const shape=keys.map(key=>`${key}?`).join(', ');
+  if(!plain(resources))bad(` must be {${shape}} or null.`);
+  for(const key of Object.keys(resources))if(!keys.includes(key))bad(` has unknown key ${key} (allowed: ${keys.join(', ')}).`);
+  for(const key of keys){
+    const value=resources[key];
+    if(value!==undefined&&value!==null&&!inRange(value,FLOOR_LIMITS[key])){
+      const cap=FLOOR_LIMITS[key]===Infinity?'':` and at most ${FLOOR_LIMITS[key]}`;
+      bad(`.${key} must be a number above 0${cap}, or null.`);
+    }
+  }
+}
+
+const declared=(block,key,source)=>{
+  const value=block?.[key];
+  if(value===undefined||value===null)return null;
+  if(!inRange(value,FLOOR_LIMITS[key]))throw new Error(`${source}.${key} must be a number above 0 (at most ${FLOOR_LIMITS[key]})`);
+  return value;
+};
+
+/**
+ * The floors in force: the owner's `resources` (config.yaml) over the shipped `allocation.resources`.
+ * {minFreeDiskGb, minFreeDiskPct (null when unset), minFreeRamPct}. The shipped policy owns the default numbers: when it
+ * omits or misspells minFreeDiskGb or minFreeRamPct this refuses, there is no fallback constant.
+ */
+export function hostFloors(shipped,owner=null){
+  const source='modules/models/runtimes.yaml allocation.resources';
+  const base={minFreeDiskGb:declared(shipped,'minFreeDiskGb',source),minFreeDiskPct:declared(shipped,'minFreeDiskPct',source),minFreeRamPct:declared(shipped,'minFreeRamPct',source)};
+  for(const key of ['minFreeDiskGb','minFreeRamPct'])if(base[key]===null)throw new Error(`${source}.${key} must declare a positive number`);
+  if(owner!==null&&owner!==undefined)validateResources(owner);
+  const pick=key=>declared(owner,key,'config.yaml resources')??base[key];
+  return {minFreeDiskGb:pick('minFreeDiskGb'),minFreeDiskPct:pick('minFreeDiskPct'),minFreeRamPct:pick('minFreeRamPct')};
+}

package/runtime/engine/runtime-root.mjs

@@ -22,6 +22,23 @@ export const skillRoot = moduleRoot;
  */
 export const starciSourceRoot = (env = process.env) => (env.STARCI_SOURCE_ROOT ? path.resolve(env.STARCI_SOURCE_ROOT) : path.dirname(skillRoot));
 
+/** Overrides the per-host state base wholesale (debug probes, spec trees); the one seam starciLocalRoot reads. */
+export const LOCAL_ROOT_ENV = 'STARCI_LOCAL_ROOT';
+/** The host-data directory of a runtime root. Git-ignored and never packed; the example fixtures under examples/.runtimes are a separate, public exception. */
+export const RUNTIME_STATE_DIR = '.runtime';
+/**
+ * <root>/.runtime. The root is the `.claude` of the host Source: the checkout, or the copy `starci runtime install` places at
+ * <app>/.claude. ~/.starci/runtime/node_modules/starci is only the CLI's download cache (it supplies the installer and hosts no
+ * state), and `starci runtime link` merely points the launcher at a root, so the state follows the code's own location.
+ */
+export const runtimeStateDir = (root = skillRoot) => path.join(root, RUNTIME_STATE_DIR);
+/**
+ * The per-host state base, the one owner of every host-state location: machine.sqlite, projects/<ledger_id>/runtime.sqlite, archive/,
+ * artifacts/ (the blob store), guards/, host-lock/ and the other process state sit under it. Default <runtime root>/.runtime;
+ * LOCAL_ROOT_ENV replaces it wholesale. Nothing is read from or moved out of the earlier %LOCALAPPDATA%/StarCi and ~/.starci locations.
+ */
+export const starciLocalRoot = (env = process.env, root = skillRoot) => (env[LOCAL_ROOT_ENV] ? path.resolve(env[LOCAL_ROOT_ENV]) : runtimeStateDir(root));
+
 /**
  * Read a runtime contract document. `parts` are path segments under `skillRoot`
  * (e.g. readModuleJson('modules', 'models', 'kinds.yaml')).

package/runtime/engine/secrets.mjs

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** The host-local credential filename, resolved only against a verified runtime main root. */
+export const SECRET_ENV_FILE='secret.env';
+/** The configured credential variable grammar shared by validation and secret resolution. */
+export const ENV_NAME=/^[A-Z_][A-Z0-9_]{0,63}$/;
+export const CREDENTIAL_FILE_MAX_BYTES=1024*1024;
+const resolvedValues = new Set();
+const remember = value => {
+  if (typeof value === 'string' && value.length >= 6) resolvedValues.add(value);
+  return value;
+};
+
+/** Filter credentials resolved by this process; the values never leave their resolution owner. */
+export function redactResolvedSecrets(text) {
+  let clean = text;
+  for (const value of resolvedValues) if (clean.includes(value)) clean = clean.split(value).join('[redacted:resolved-secret]');
+  return clean;
+}
+
+/** Check lexical availability only; blank and conventional template markers never prove provider validity. */
+export function credentialPresent(value){
+  if(typeof value!=='string'||!value.trim())return false;
+  return !/^(?:CHANGE_ME|REPLACE_ME|PLACEHOLDER|TODO|<[^>]*>|YOUR_[A-Z0-9_]+)$/i.test(value.trim());
+}
+
+/** Read one configured credential file with a finite byte budget; no effects beyond the read. */
+export function readSecretBytes(file){
+  const before=fs.lstatSync(file);
+  if(!before.isFile()||before.isSymbolicLink())throw new Error('credential file must be a regular file');
+  if(before.size>CREDENTIAL_FILE_MAX_BYTES)throw new Error('credential file exceeds the byte budget');
+  const fd=fs.openSync(file,fs.constants.O_RDONLY|(fs.constants.O_NOFOLLOW??0));
+  let bytes;
+  try{
+    const stat=fs.fstatSync(fd);
+    if(!stat.isFile()||stat.dev!==before.dev||stat.ino!==before.ino)throw new Error('credential file changed during resolution');
+    bytes=Buffer.alloc(CREDENTIAL_FILE_MAX_BYTES+1);
+    let count=0;
+    while(count<bytes.length){const n=fs.readSync(fd,bytes,count,bytes.length-count,null);if(n===0){break;}count+=n;}
+    if(count>CREDENTIAL_FILE_MAX_BYTES)throw new Error('credential file exceeds the byte budget');
+    return bytes.subarray(0,count);
+  }catch(error){bytes?.fill(0);throw error;}finally{fs.closeSync(fd);}
+}
+
+const readCredentialFile = file => { const bytes=readSecretBytes(file); try{return bytes.toString('utf8');}finally{bytes.fill(0);} };
+
+const DOTENV_LINE_PARTS = [String.raw`^\s*`, String.raw`(?:export\s+)?`, String.raw`([A-Za-z_]\w*)`, String.raw`\s*=\s*`, String.raw`([^\r\n\u2028\u2029]*)`, String.raw`\s*$`];
+const DOTENV_LINE = new RegExp(DOTENV_LINE_PARTS.join(''));
+
+/** Parse a dotenv file (KEY=VALUE lines, # comments, optional export/quotes). An absent file is {}. */
+export function readDotenv(file){
+  let text='';try{text=readCredentialFile(file);}catch(error){if(error?.code==='ENOENT'){return {};}throw error;}
+  const out={};
+  for(const line of text.split(/\r?\n/)){
+    const m=DOTENV_LINE.exec(line);
+    if(!m)continue;
+    let value=m[2].trimEnd();
+    if(value.length>=2&&(value.startsWith('"')||value.startsWith("'"))&&value.at(-1)===value[0])value=value.slice(1,-1);
+    out[m[1]]=value;
+  }
+  return out;
+}
+
+/**
+ * Resolve a configured variable or its supported NAME_FILE custody pointer. An explicitly supplied
+ * blank variable disables the value; it must not resurrect a file value. Never print the result.
+ */
+export function connectorSecret(name,env=process.env){
+  if(typeof name!=='string'||!ENV_NAME.test(name))return null;
+  if(Object.hasOwn(env,name))return typeof env[name]==='string'?remember(env[name].trim()||null):null;
+  const pointer=typeof env[`${name}_FILE`]==='string'?env[`${name}_FILE`].trim():'';
+  if(!pointer)return null;
+  try{const value=readCredentialFile(pointer).trim();return remember(value||null);}catch{return null;}
+}
+
+/**
+ * Load the verified runtime main's local credentials below the actual environment without mutating
+ * either input. The caller owns repository identity; this base-tier reader never infers a root from cwd.
+ * Absence is allowed so the action-specific gate can name only the credentials that action requires.
+ */
+export function secretEnv(verifiedRuntimeRoot,env=process.env){
+  if(typeof verifiedRuntimeRoot!=='string'||!path.isAbsolute(verifiedRuntimeRoot))
+    throw new TypeError('secretEnv requires an absolute verified runtime root');
+  if(env===null||typeof env!=='object'||Array.isArray(env))throw new TypeError('secretEnv requires an environment mapping');
+  const root=fs.lstatSync(verifiedRuntimeRoot);
+  if(!root.isDirectory()||root.isSymbolicLink())throw new Error('secretEnv runtime root must be a regular directory');
+  const file=path.join(verifiedRuntimeRoot,SECRET_ENV_FILE);
+  let stat;
+  try{stat=fs.lstatSync(file);}catch(error){if(error?.code==='ENOENT'){return {...env};}throw error;}
+  if(!stat.isFile()||stat.isSymbolicLink())throw new Error('secret.env must be a regular file');
+  const local = readDotenv(file);
+  const resolved = {...local,...env};
+  for (const name of Object.keys(local)) if (typeof resolved[name] === 'string') remember(resolved[name]);
+  return resolved;
+}
+
+const sopsRefuse=(reason,message)=>{
+  const error=new Error(`SOPS identity [${reason}]: ${message}`);
+  error.name='SopsIdentityRefusal';error.identityRefusal=reason;
+  return {mode:'refused',env:null,error};
+};
+const sopsInlineIdentity=(env,name)=>{
+  if(!credentialPresent(env[name]))return sopsRefuse('disabled-inline','SOPS_AGE_KEY is explicitly empty or invalid');
+  remember(env[name].trim());
+  return {...sopsRefuse('inline-context-unqualified','the supplied SOPS_AGE_KEY awaits an owned selected-identity isolation capability; no SOPS process was launched'),inlineName:name};
+};
+const sopsFileIdentity=(env,file)=>{
+  if(!credentialPresent(file))return sopsRefuse('invalid-file','the original identity file selection is empty or invalid');
+  if(!path.isAbsolute(file))return sopsRefuse('identity-file-location-unqualified','select the original identity by its absolute path; caller and SOPS working directories may differ');
+  try{
+    const stat=fs.lstatSync(file);
+    if(!stat.isFile()||stat.isSymbolicLink())return sopsRefuse('identity-file-unavailable','the explicitly selected original identity must be a regular non-symlink file');
+  }catch{return sopsRefuse('identity-file-unavailable','the explicitly selected original identity file is unavailable');}
+  return {mode:'file',env:{...env,SOPS_AGE_KEY_FILE:file},error:null};
+};
+/** Select a supplied age identity without inventing custody or running a key tool. Inline execution awaits its owned isolation capability. */
+export function sopsIdentityEnv(env,{identity=null,required=false,platform=process.platform}={}){
+  if(!env||typeof env!=='object'||Array.isArray(env))return sopsRefuse('invalid-environment','an environment mapping is required');
+  const names=name=>Object.keys(env).filter(key=>platform==='win32'?key.toUpperCase()===name:key===name);
+  const inline=names('SOPS_AGE_KEY'),files=names('SOPS_AGE_KEY_FILE');
+  if(inline.length>1||files.length>1)return sopsRefuse('ambiguous-environment','multiple Windows aliases select an age identity');
+  if(inline.length)return sopsInlineIdentity(env,inline[0]);
+  let file=identity;
+  if(files.length){
+    const value=env[files[0]];
+    if(!credentialPresent(value))return sopsRefuse('disabled-file','SOPS_AGE_KEY_FILE is explicitly empty or invalid');
+    if(identity!==null&&identity!==undefined&&identity!==value)return sopsRefuse('conflicting-files','two different original identity files were explicitly selected');
+    file=value;
+  }
+  if(file!==null&&file!==undefined)return sopsFileIdentity(env,file);
+  if(required)return sopsRefuse('identity-not-supplied','supply SOPS_AGE_KEY locally or select the original SOPS_AGE_KEY_FILE; no home default was inferred');
+  return {mode:'public-recipient',env:{...env},error:null};
+}

package/runtime/engine/sonar-config.mjs

@@ -0,0 +1,21 @@
+import {isPlainObject as plain} from './plain-object.mjs';
+import {invalid} from './invalid-config.mjs';
+
+/** The keys of the sonar block. */
+const SONAR_KEYS=Object.freeze(['organization']);
+/** A SonarCloud organization key: lowercase letters, digits, hyphens and underscores, starting with a letter or a digit. */
+const ORGANIZATION=/^[a-z0-9][a-z0-9_-]*$/;
+
+/**
+ * config.yaml `sonar` - {organization?}: the key of the SonarCloud organization the release's Sonar proof of the example apps analyses in
+ * (the project key is <organization>_<key the example declares>). It is configuration, not a secret; the environment variable
+ * SONAR_ORGANIZATION wins over it, the repository variable of the same name is what CI reads. Null or absent means "not set yet".
+ */
+export function validateSonar(sonar){
+  if(sonar===null)return;
+  const bad=invalid('sonar');
+  if(!plain(sonar))bad(' must be {organization?: <SonarCloud organization key>} or null.');
+  for(const key of Object.keys(sonar))if(!SONAR_KEYS.includes(key))bad(` has unknown key ${key} (allowed: ${SONAR_KEYS.join(', ')}).`);
+  const value=sonar.organization;
+  if(value!==undefined&&value!==null&&!(typeof value==='string'&&ORGANIZATION.test(value)))bad('.organization must be a SonarCloud organization key (lowercase letters, digits, - and _) or null.');
+}

package/runtime/engine/temp-root.mjs

@@ -0,0 +1,32 @@
+// temp-root.mjs — the one owner of where the runtime puts its temporary files.
+//
+// Every temp directory or file the runtime creates (spec fixtures, land scratch, gate staging, dispatch prompts, scan work
+// dirs) lives under tempRoot(): env STARCI_TEMP_ROOT (a spec, a one-off run), then the owner config `roots.temp`
+// (config.yaml, gitignored), else the OS temp directory of the process (TEMP / TMP / TMPDIR, then os.tmpdir()). The base tier
+// only resolves; the directory is made by scripts/api/fs/make-temp-dir.mjs, temp-path.mjs and ensure-temp-root.mjs. The
+// children the runtime starts get the same directory as TEMP / TMP / TMPDIR (tempChildEnv, applied by withTempEnv in every scripts/api/ spawn wrapper).
+import os from 'node:os';
+import path from 'node:path';
+import { loadConfig } from './config.mjs';
+
+export const TEMP_ROOT_ENV = 'STARCI_TEMP_ROOT';
+
+/** The owner's `roots.temp` (config.yaml, validated by engine/invalid-config.mjs), or null. `config` is the owner config (default: loadConfig(), whose error for an invalid config.yaml propagates: the OS directory never replaces a root the owner set wrongly). */
+const ownerTemp = (config) => (config === undefined ? loadConfig() : config)?.roots?.temp ?? null;
+
+/** The operating-system temp directory of `env`: TEMP, TMP, TMPDIR, else os.tmpdir(). */
+export const osTempDir = (env = process.env) => path.resolve(String(env?.TEMP || env?.TMP || env?.TMPDIR || os.tmpdir()));
+
+/** The one temp root: env STARCI_TEMP_ROOT, then the owner config `roots.temp`, else the OS temp directory. Resolved, not created. */
+export function tempRoot({ env = process.env, config = undefined } = {}) {
+  return path.resolve(String(env?.[TEMP_ROOT_ENV] || ownerTemp(config) || osTempDir(env)));
+}
+
+/** `env` (default: the process environment) as a copy whose TEMP, TMP and TMPDIR name the temp root. */
+export function tempChildEnv(env = process.env) {
+  const root = tempRoot({ env });
+  return { ...env, TEMP: root, TMP: root, TMPDIR: root };
+}
+
+/** The spawn options with `env` replaced by tempChildEnv of the options' own env (default: the process environment). */
+export const withTempEnv = (options = {}) => ({ ...options, env: tempChildEnv(options.env ?? process.env) });

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -22,73 +22,73 @@ pins:
     source: packages/heroicons/package.json
     why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
   '@starci/grammar':
-    version: 0.8.2
+    version: 0.8.3
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
-    why: the product front ends pinned older versions (0.4.11, 0.5.0, 0.5.1); the runtime source is 0.8.0 and wins for a @starci package (the brand layer sets `--font-sans` and `--font-mono`; the grammar reads them; 0.7.2 added the Input tel kind and IconButton disclosure props).
+    why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind and the IconButton disclosure props. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.0.9
+    version: 3.1.0
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
-    why: '3.0.3: its bundled canon-pins copy pins stylelint-canon 2.0.2 and hfs 4.0.3; no rule changed. 3.0.2: its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root (app.starcistacks, app.sops) and pin hfs 4.0.2. 3.0.1: its bundled canon-pins copy pins hfs 4.0.1. 3.0.0: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side; the project graph is built per side. 2.0.0 (C0 release): starciBeConfig({ hfs: loadHfs(import.meta.url) }) typed factory and the BE-CONVENTION laws.'
+    why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.0.9
+    version: 8.1.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
-    why: '8.0.3: its bundled canon-pins copy pins stylelint-canon 2.0.2 and hfs 4.0.3; no rule changed. 8.0.2: its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root (app.starcistacks, app.sops) and pin hfs 4.0.2. 8.0.1: its bundled canon-pins copy pins hfs 4.0.1. 8.0.0: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side; the project graph is built per side. 7.0.0: the front end has no tests (FE_NO_TESTS R97 in hfs); no-vietnamese-in-source (R91).'
+    why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/stylelint-canon':
-    version: 2.0.4
+    version: 2.0.6
     group: starci
     install: registry
     side: fe
     source: packages/stylelint/package.json
-    why: '2.0.2: no-class-selector refuses a compound class selector (`div.card`), which the 2.0.1 pattern let through. 2.0.1 accepts `--font-sans` and `--font-mono` in the brand layer (the vocabulary follows the grammar 0.8.0). 2.0.0 adds status-contrast (HeroUI soft pairs measured per theme), fixes brand-layer-shape on the shared :root,.light,.dark block and the info soft pair, and derives appTokens with loadAppTokens(import.meta.url) for the managed one-line stylelint.config.mjs.'
+    why: 'the front-end stylelint canon: no-class-selector refuses a compound class selector (`div.card`); the brand layer accepts `--font-sans` and `--font-mono`; status-contrast measures the HeroUI soft pairs per theme; brand-layer-shape reads the shared :root,.light,.dark block and the info soft pair; appTokens come from loadAppTokens(import.meta.url) for the managed one-line stylelint.config.mjs.'
   '@starci/tsconfig':
-    version: 2.0.2
+    version: 2.0.3
     group: starci
     install: registry
     side: both
     source: packages/tsconfig/package.json
   '@starci/prettier-config':
-    version: 1.0.2
+    version: 1.0.3
     group: starci
     install: registry
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.2.4
+    version: 2.2.6
     group: starci
     install: registry
     side: be
     source: packages/jest-preset/package.json
-    why: '2.2.4: the world runner runs up to min(--maxWorkers, slots) world files at once, each in its own process bound to one data slot of the test world (STARCI_TEST_WORLD_SLOT), and reads test-world state protocol 2 only: pinned together with @starci/test-world 1.1.0, any other state file is JEST_PRESET_WORLD_PAIR_MISMATCH. 2.2.3: republished after the move (no preset change). 2.2.2: the unit run writes the lcov Sonar and Codecov import (services only); 2.2.0: the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; 2.1.0: four projects on the test world, the unit kit (mockEntityManager, fakeTransaction, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
+    why: 'the Jest preset of a back end: the world runner runs up to min(--maxWorkers, slots) world files at once, each in its own process bound to one data slot of the test world (STARCI_TEST_WORLD_SLOT), and reads test-world state protocol 2 only: it pairs exactly with @starci/test-world, and any other state file is JEST_PRESET_WORLD_PAIR_MISMATCH. The unit run writes the lcov Sonar and Codecov import (services only); the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; it ships the unit kit (mockEntityManager, fakeTransaction, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
   '@starci/test-world':
-    version: 1.2.0
+    version: 1.2.1
     group: starci
     install: registry
     side: be
     source: packages/test-world/package.json
-    why: '1.2.0: Kafka as real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and schema-per-context Postgres (a schema and a login role per context in a shared database); its CLI main is exported at ./cli for starci app stack, and the former starci app stack bin is removed. 1.1.0: per-worker data slots: a run provisions min(jest workers, workers cap, default 2) slots, each its own namespace (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock, so world files run in parallel; state file protocol 2, paired exactly with @starci/jest-preset 2.2.4 (TEST_WORLD_PAIR_MISMATCH otherwise). 1.0.6: republished after the move (no library change). 1.0.5: a modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, and w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client. 1.0.4: world.resolve and scope.resolve take any Nest token (class, string or symbol). 1.0.3: the globalSetup registers the path aliases as TypeScript resolves them (the extends chain, paths from the config that declares them, the effective baseUrl), so a tests tsconfig that only extends the side config loads the declaration. 1.0.2: every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json), where .starcistacks lives, never from the be side. The shared e2e library of every back end (R47, R48): the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock; a devDependency of every back end. 1.0.1: world.keycloak.events/sessions (the user events of the realm and live sessions through the admin API) and world.infra.postgresql.connection(name) (the database of one connection down while the others serve, under the outage lock).'
+    why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.0.0
+    version: 1.1.0
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
-    why: '1.0.0: the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
+    why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.0.9
+    version: 4.1.0
     group: starci
     install: registry
     side: both
     source: packages/hfs/package.json
-    why: '4.0.9: the transitive app implementation used by @starci/cli; it carries the generated runtime slice read by starci app commands.'
+    why: 'the transitive app implementation used by @starci/cli; it carries the generated runtime slice read by starci app commands.'
   # --- tooling
   typescript:
     version: 5.9.3

package/runtime/knowledge/hfs/peer-integrations.yaml

@@ -2,9 +2,8 @@ schema: starci/hfs-peer-integrations@1
 purpose: >-
   The runtime peers a driver integration needs and npm does not install for it: "if the app depends on every package of
   `when` (at the named major, when one is named), it must declare `requires` in its dependencies". A missing peer is
-  invisible to the type checker and the unit specs and only fails when the api boots (ecommerce-app,
-  2026-10-01: the old backend did not declare @as-integrations/express5, so the Apollo GraphQL api could not boot under
-  Express 5 and nothing noticed before e2e). R111 HFS_PEER_INTEGRATION_MISSING judges the app root package.json, the one
+  invisible to the type checker and the unit specs and only fails when the api boots (a backend that does not declare
+  @as-integrations/express5 cannot boot its Apollo GraphQL api under Express 5, and nothing notices before e2e). R111 HFS_PEER_INTEGRATION_MISSING judges the app root package.json, the one
   manifest of both sides, with this catalog; an entry is added the day a boot failure of the same kind is found.
 pairs:
   - id: nestjs-apollo-express5