@starci/eslint-grammar-offset-pop 0.12.13 → 0.13.0

package/runtime/engine/invalid-config.mjs

@@ -0,0 +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 new Error(`Invalid config.yaml: ${section}${message}`);};
+
+/** 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>, 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

@@ -0,0 +1,29 @@
+import {isPlainObject as plain} from './plain-object.mjs';
+import {invalid} from './invalid-config.mjs';
+
+/**
+ * config.yaml `orca` — the owner's Orca app settings the runtime must know. maxWorkerDepth is the deepest worker Orca
+ * lets start under the owner's chat (chat = depth 0, a Kernel or the [Supervisor] 1, an op or a [Worker] 2, the draw
+ * critic 3); a deeper worker-start is refused by Orca with nested_worker_depth_exceeded. Orca exposes no read of that
+ * setting, so it is declared here and MUST equal the Orca app setting: scripts/agent/lib.mjs spawnAgent refuses a launch
+ * deeper than it before worker-start (worker-depth-exceeded), and `start --check` with STARCI_ORCA_LIVE=1 compares it with
+ * 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(!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.`);
+}
+/** The owner's Orca settings: {maxWorkerDepth, source: 'orca'|'default'}. An absent or null block or key is the default. */
+export function orcaSettings(config){
+  if(config?.orca!==undefined)validateOrca(config.orca);
+  const value=plain(config?.orca)?config.orca.maxWorkerDepth:null;
+  return Number.isInteger(value)?{maxWorkerDepth:value,source:'orca'}:{maxWorkerDepth:ORCA_DEFAULTS.maxWorkerDepth,source:'default'};
+}

package/runtime/engine/release-config.mjs

@@ -0,0 +1,28 @@
+import {isPlainObject as plain} from './plain-object.mjs';
+import {invalid} from './invalid-config.mjs';
+
+/** The keys of the release block. */
+export const RELEASE_KEYS=Object.freeze(['suite']);
+/** Where the full test suite of a release is judged: `local` (the release cut also runs the L4 rows before it tags, the shipped default) or `ci` (the GitHub workflows judge EVERY row on each push to main; the cut runs none). */
+export const SUITE_MODES=Object.freeze(['local','ci']);
+const RELEASE_DEFAULTS=Object.freeze({suite:'local'});
+
+/**
+ * config.yaml `release` - {suite?: local | ci}: who judges the full suite of a release (docs/releasing.md "Where the suite runs"). `local` is the shipped default: `starci release cut` also runs the
+ * L4 rows on this host before it tags. `ci` is the owner's recorded choice (2026-10-09, widened 2026-10-26 by push-main-after-scoped-check): the full suite runs on GitHub only, on every push
+ * to main; the cut runs no row and the verdict is read with `starci release ci-status`. The push of main needs neither mode: it needs a green scoped check.
+ * `none` is refused: the suite does not vanish, it moves to CI, and the value says so.
+ */
+export function validateRelease(release){
+  if(release===null)return;
+  const bad=invalid('release');
+  if(!plain(release))bad(` must be {suite?: ${SUITE_MODES.join(' | ')}} or null.`);
+  for(const key of Object.keys(release))if(!RELEASE_KEYS.includes(key))bad(` has unknown key ${key} (allowed: ${RELEASE_KEYS.join(', ')}).`);
+  const value=release.suite;
+  if(value===undefined||value===null)return;
+  if(value==='none')bad('.suite: "none" is not a mode: write "ci" (no local full suite, CI judges) or "local".');
+  if(!SUITE_MODES.includes(value))bad(`.suite must be ${SUITE_MODES.join(' or ')}, or null.`);
+}
+
+/** The suite mode a validated owner config names; an absent block or key is the shipped default. */
+export const releaseSuiteMode=config=>config?.release?.suite??RELEASE_DEFAULTS.suite;

package/runtime/engine/removed-vocabulary.mjs

@@ -0,0 +1,26 @@
+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;
+}
+
+
+/** 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/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/knowledge/hfs/canon-pins.yaml

@@ -21,7 +21,7 @@ pins:
     install: registry
     side: fe
     source: packages/heroicons/package.json
-    why: 'StarCi custom Heroicons-compatible cuts; eslint-grammar-starci (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
+    why: 'StarCi custom Heroicons-compatible cuts; eslint-grammar-core (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
   '@starci/event-stream':
     version: 0.1.0
     group: starci
@@ -30,61 +30,61 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.12.13
+    version: 0.13.0
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     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, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.55
+    version: 3.4.57
     group: starci
     install: registry
     side: be
-    source: packages/eslint/be/package.json
+    source: packages/eslint-canon-be/package.json
     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: 9.1.9
+    version: 9.2.0
     group: starci
     install: registry
     side: fe
-    source: packages/eslint/fe/package.json
+    source: packages/eslint-canon-fe/package.json
     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/eslint-grammar-starci':
-    version: 0.12.13
+  '@starci/eslint-grammar-core':
+    version: 0.13.0
     group: starci
     install: registry
     side: fe
-    source: packages/eslint/grammar-starci/package.json
+    source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.12.13
+    version: 0.13.0
     group: starci
     install: registry
     side: fe
-    source: packages/eslint/grammar-offset-pop/package.json
+    source: packages/eslint-grammar-offset-pop/package.json
     why: 'the Offset Pop Grammar component API lint, versioned with @starci/grammar; its shared component contract comes from the StarCi family lint without copying rules.'
   '@starci/stylelint-canon':
-    version: 2.0.13
+    version: 2.1.0
     group: starci
     install: registry
     side: fe
-    source: packages/stylelint/package.json
+    source: packages/stylelint-canon/package.json
     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.7
+    version: 2.0.8
     group: starci
     install: registry
     side: both
     source: packages/tsconfig/package.json
   '@starci/prettier-config':
-    version: 1.0.4
+    version: 1.0.5
     group: starci
     install: registry
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.3.6
+    version: 2.3.7
     group: starci
     install: registry
     side: be
@@ -98,14 +98,13 @@ pins:
     source: packages/test-world/package.json
     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.7.46
+    version: 1.7.47
     group: starci
     install: registry
     side: both
-    source: packages/cli/package.json
     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.7.46
+    version: 4.8.0
     group: starci
     install: registry
     side: both
@@ -406,7 +405,7 @@ pins:
     version: 2.2.0
     group: ui
     side: fe
-    why: 'the base of the one application icon set (fe-stack icons, with @starci/heroicons for the glyphs it lacks); eslint-grammar-starci (icon.mjs) admits @heroicons/react/24/outline and /16/solid.'
+    why: 'the base of the one application icon set (fe-stack icons, with @starci/heroicons for the glyphs it lacks); eslint-grammar-core (icon.mjs) admits @heroicons/react/24/outline and /16/solid.'
   '@dicebear/core':
     version: 10.4.0
     group: ui