@starci/eslint-canon-fe 8.0.9 → 8.0.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) StarCi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/comments.mjs

@@ -16,6 +16,7 @@
  */
 
 import { hasSecondLanguage } from "./runtime/scripts/lib/language.mjs"
+import { jsdocBefore } from "./runtime/scripts/lib/jsdoc.mjs"
 import { fileOf, inSlot } from "./lib/scope.mjs"
 
 /**
@@ -82,13 +83,12 @@ export const requireExportJsdoc = {
     schema: [],
     messages: {
       jsdoc:
-        "`{{name}}` is exported with no documentation block. An export is read far more often than it is written, and by people who never open the body - name the ROLE it plays, not the signature, which the signature already states.",
+        "`{{name}}` is exported without an adjacent JSDoc description. An export is read far more often than it is written, and by people who never open the body - name the ROLE it plays, not the signature, which the signature already states.",
     },
   },
   create(context) {
     const source = context.sourceCode || context.getSourceCode()
-    const hasBlock = (node) =>
-      source.getCommentsBefore(node).some((comment) => comment.type === "Block" && comment.value.startsWith("*"))
+    const hasBlock = (node) => jsdocBefore(source, node) !== null
     const check = (node) => {
       const declaration = node.declaration
       if (!declaration) return

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "8.0.9",
+  "version": "8.0.10",
   "description": "The StarCi front-end lint canon: every rule its laws publish, gathered as one flat-config plugin and attached by one factory.",
   "type": "module",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "private": false,
   "exports": {
     ".": "./index.mjs"
   },
   "main": "./index.mjs",
   "files": [
+    "LICENSE",
     "*.mjs",
     "lib/*.mjs",
     "runtime/**",

package/runtime/engine/config.mjs

@@ -6,6 +6,8 @@ import {parseYaml} from './yaml.mjs';
 import {isPlainObject as plain} from './plain-object.mjs';
 import {invalid,validateRoots} from './invalid-config.mjs';
 import {validateOrca} from './orca-config.mjs';
+import {ENV_NAME,secretEnv,connectorSecret} from './secrets.mjs';
+export {readDotenv,connectorSecret} from './secrets.mjs';
 
 export const configRoot=skillRoot;
 export const NON_OPERATION_ROLES={planner:'plan',kernelManager:'decide',validator:'verify'};
@@ -40,6 +42,29 @@ export function runtimeProfile(){
  * here; a literal copy of any of them in a source file would be a second authority.
  */
 export function allocationSettings(){return runtimeProfile()?.allocation??{};}
+// These are current owner declarations, never a historical runtime owner's consent.
+function validateOwnerProfile(value,name,pathsKey){
+  if(value===null)return;
+  const bad=invalid(name);
+  if(!plain(value))bad(' must be an owner approval mapping or null.');
+  const keys=['approvedBy','approvalRef',pathsKey,...(name==='launchTrust'?['profile']:[])];
+  for(const key of Object.keys(value))if(!keys.includes(key))bad(` has unknown key ${key}.`);
+  if(value.approvedBy!=='owner')bad('.approvedBy must be owner; adoption must come from the current owner.');
+  if(typeof value.approvalRef!=='string'||!value.approvalRef.trim())bad('.approvalRef must identify the current owner approval.');
+  if(name==='launchTrust'&&!['automatic','declined'].includes(value.profile))bad('.profile must be automatic or declined.');
+  const paths=value[pathsKey];
+  if(!Array.isArray(paths)||!paths.length||paths.some(p=>typeof p!=='string'||!(path.isAbsolute(p)||path.win32.isAbsolute(p))||/[\r\n\0]/.test(p)))bad(`.${pathsKey} must list exact absolute repository roots.`);
+}
+export function launchTrustSettings(config=loadConfig()){
+  const value=config?.launchTrust??null;validateOwnerProfile(value,'launchTrust','roots');return value;
+}
+export function workflowPurgeSettings(config=loadConfig()){
+  const retention=config?.retention??null;
+  if(retention===null)return null;
+  const bad=invalid('retention');
+  if(!plain(retention)||Object.keys(retention).some(k=>k!=='workflowPurge'))bad(' must be {workflowPurge?} or null.');
+  const value=retention.workflowPurge??null;validateOwnerProfile(value,'retention.workflowPurge','repos');return value;
+}
 /** One positive millisecond value out of `allocation`, by dotted key. Refuses when the contract omits it. */
 export function allocationMs(dotted){
   const raw=dotted.split('.').reduce((node,key)=>(node==null?node:node[key]),allocationSettings());
@@ -75,13 +100,11 @@ const CLOUDFLARE_MODES=['off','quick','named'];
 /** The serve-ask port band, both ends included (scripts/kernel/ask-server.mjs scans [first..last]); the gateway stays outside it. */
 export const ASK_PORT_BAND=[6969,7069];
 export const CONNECTOR_DEFAULTS=Object.freeze({
-  secretsFile:null,
   repos:[],
   gateway:{port:7070},
   cloudflare:{mode:'off',tunnel:null,credentialsFile:null,tokenEnv:'CLOUDFLARE_TUNNEL_TOKEN',hostname:null,access:false},
   telegram:{enabled:false,botTokenEnv:'TELEGRAM_BOT_TOKEN',chatId:null,exposeCredentialAsks:false},
 });
-const ENV_NAME=/^[A-Z_][A-Z0-9_]{0,63}$/;
 const HOSTNAME=/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
 const TUNNEL_REF=/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
 const CHAT_ID=/^(?:-?\d{1,20}|@[A-Za-z][A-Za-z0-9_]{4,31})$/;
@@ -89,7 +112,7 @@ const SECRET_KEYS=['token','tunnelToken','botToken','secret','apiToken','passwor
 function validateConnectors(connectors){
   if(connectors===null)return;
   const bad=invalid('connectors');
-  if(!plain(connectors))bad(' must be {secretsFile?, repos?, gateway?, cloudflare?, telegram?} or null.');
+  if(!plain(connectors))bad(' must be {repos?, gateway?, cloudflare?, telegram?} or null.');
   const closed=(node,where,keys)=>{
     if(!plain(node))bad(`.${where} must be a mapping.`);
     for(const key of Object.keys(node)){
@@ -97,8 +120,7 @@ function validateConnectors(connectors){
       if(!keys.includes(key))bad(`.${where} has unknown key ${key} (allowed: ${keys.join(', ')}).`);
     }
   };
-  closed(connectors,'',['secretsFile','repos','gateway','cloudflare','telegram']);
-  if(connectors.secretsFile!==undefined&&connectors.secretsFile!==null&&(typeof connectors.secretsFile!=='string'||!connectors.secretsFile.trim()))bad('.secretsFile must be a dotenv file path (relative to the skill root) or null.');
+  closed(connectors,'',['repos','gateway','cloudflare','telegram']);
   if(connectors.repos!==undefined&&(!Array.isArray(connectors.repos)||connectors.repos.some(repo=>typeof repo!=='string'||!repo.trim())))bad('.repos must be a list of repository paths.');
   if(connectors.gateway!==undefined){
     closed(connectors.gateway,'gateway',['port']);
@@ -132,46 +154,14 @@ function validateConnectors(connectors){
     if(tg.enabled===true&&(tg.chatId===undefined||tg.chatId===null))bad('.telegram.enabled needs telegram.chatId.');
   }
 }
-/**
- * The secret an env var NAME resolves to: `env[name]`, else the contents of the file `env[name + '_FILE']`
- * points at (the custody pointer convention). Returns null when neither is set. Callers pass the value to
- * the one API that needs it and never print it.
- */
-/** Parse a dotenv file (KEY=VALUE lines, # comments, optional export/quotes). An absent file is {}. */
-export function readDotenv(file){
-  let text='';try{text=fs.readFileSync(file,'utf8');}catch(error){if(error?.code==='ENOENT')return {};throw error;}
-  const out={};
-  for(const line of text.split(/\r?\n/)){
-    const m=line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
-    if(!m)continue;
-    let value=m[2];
-    if(value.length>=2&&(value[0]==='"'||value[0]==="'")&&value.at(-1)===value[0])value=value.slice(1,-1);
-    out[m[1]]=value;
-  }
-  return out;
-}
-/** The dotenv file connectors.secretsFile names, resolved against the skill root; null when unset. */
-const connectorSecretsFile=(config,root=configRoot)=>{const file=config?.connectors?.secretsFile;return typeof file==='string'&&file.trim()?path.resolve(root,file):null;};
-/**
- * The environment the connectors resolve secrets from: connectors.secretsFile's values under the process
- * environment (a real env var wins). It holds secrets — hand it to connectorSecret, never print it.
- */
-export function connectorEnv(config,env=process.env,root=configRoot){const file=connectorSecretsFile(config,root);return file?{...readDotenv(file),...env}:env;}
-export function connectorSecret(name,env=process.env){
-  if(typeof name!=='string'||!ENV_NAME.test(name))return null;
-  const direct=typeof env[name]==='string'?env[name].trim():'';
-  if(direct)return direct;
-  const pointer=typeof env[`${name}_FILE`]==='string'?env[`${name}_FILE`].trim():'';
-  if(!pointer)return null;
-  try{const value=fs.readFileSync(pointer,'utf8').trim();return value||null;}catch{return null;}
-}
+/** Load connector credentials from the explicitly verified runtime main; never print the returned environment. */
+export function connectorEnv(config,env=process.env,verifiedRuntimeRoot){return secretEnv(verifiedRuntimeRoot,env);}
 /**
  * The normalized `connectors` block: defaults filled in, the secrets' PRESENCE (booleans, never values),
  * whether each connector is ready to run, and the owner-facing warnings the security posture earns.
  */
 export function connectorsConfig(config=loadConfig(),env=process.env,root=configRoot){
   validateConfig(config);
-  env=connectorEnv(config,env,root);
   const raw=plain(config?.connectors)?config.connectors:{},d=CONNECTOR_DEFAULTS;
   const cloudflare={...d.cloudflare,...(raw.cloudflare??{})},telegram={...d.telegram,...(raw.telegram??{})};
   if(cloudflare.credentialsFile)cloudflare.credentialsFile=path.resolve(root,cloudflare.credentialsFile.replace(/^~(?=[\\/])/,env.USERPROFILE??env.HOME??'~'));
@@ -189,7 +179,7 @@ export function connectorsConfig(config=loadConfig(),env=process.env,root=config
   if(cloudflare.auth==='token'&&!cloudflare.tokenPresent)warnings.push(`cloudflare.mode named: the tunnel token is not set — export ${cloudflare.tokenEnv} (or ${cloudflare.tokenEnv}_FILE).`);
   if(telegram.enabled&&!telegram.botTokenPresent)warnings.push(`telegram.enabled: the bot token is not set — export ${telegram.botTokenEnv} (or ${telegram.botTokenEnv}_FILE).`);
   if(telegram.exposeCredentialAsks)warnings.push('telegram.exposeCredentialAsks is true: credential asks are posted as public links; Telegram cloud chats are not end-to-end encrypted.');
-  return {secretsFile:connectorSecretsFile(config,root),repos:[...(raw.repos??d.repos)],gateway:{...d.gateway,...(raw.gateway??{})},cloudflare,telegram,warnings};
+  return {repos:[...(raw.repos??d.repos)],gateway:{...d.gateway,...(raw.gateway??{})},cloudflare,telegram,warnings};
 }
 /**
  * config.yaml `asks` — whether an owner ask that carries a recommended option is answered with it
@@ -305,7 +295,9 @@ function validateAgentSeat(seat,name,profile){
   if(seat.effort!==undefined&&seat.effort!==null&&!EFFORT_LEVELS.includes(seat.effort))throw Error(`Invalid config.yaml: ${name}.effort must use the effort vocabulary.`);
 }
 export function validateConfig(config){
-  const allowed=['language','model','effort','models','debug','allocation','kernel','budgets','supervisor','parallel','delegation','connectors','asks','uat','specs','reconciler','coreDebug','orca','roots'],models=config?.models,profile=runtimeProfile(),runtimes=profile?.runtimes??{};
+  const allowed=['language','model','effort','models','debug','allocation','kernel','budgets','supervisor','parallel','delegation','connectors','asks','uat','specs','reconciler','coreDebug','orca','roots','launchTrust','retention'],models=config?.models,profile=runtimeProfile(),runtimes=profile?.runtimes??{};
+  if(config?.launchTrust!==undefined)launchTrustSettings(config);
+  if(config?.retention!==undefined)workflowPurgeSettings(config);
   if(config?.connectors!==undefined)validateConnectors(config.connectors);
   if(config?.asks!==undefined)validateAsks(config.asks);
   if(config?.uat!==undefined)validateUat(config.uat);
@@ -372,8 +364,8 @@ export function validateConfig(config){
   }
   if(config?.budgets!==undefined){
     const budgets=config.budgets;
-    if(!plain(budgets)||Object.keys(budgets).some(key=>!['maxOps','perOpMs','dailyTokens'].includes(key))||Object.values(budgets).some(value=>value!==null&&!(Number.isInteger(value)&&value>0)))
-      throw Error('Invalid config.yaml: budgets must be {maxOps?, perOpMs?, dailyTokens?} with positive-integer-or-null values.');
+    if(!plain(budgets)||Object.keys(budgets).some(key=>!['maxOps'].includes(key))||Object.values(budgets).some(value=>value!==null&&!(Number.isInteger(value)&&value>0)))
+      throw Error('Invalid config.yaml: budgets must be {maxOps?} with positive-integer-or-null values.');
   }
   if(!plain(config)||Object.keys(config).some(key=>!allowed.includes(key))||typeof config.language!=='string'||!/^[a-z]{2,3}(?:-[A-Za-z0-9]+)*$/.test(config.language)||!(config.model===null||typeof config.model==='string'&&config.model.trim())||!EFFORT_LEVELS.includes(config.effort)||!plain(models)||Object.keys(models).some(key=>!['pools','nonOperation','selection'].includes(key))||models.selection!=='quota-aware'||!plain(models.pools)||!plain(models.nonOperation)||Object.keys(models.pools).length!==Object.keys(DEFAULT_MODEL_POOLS).length||Object.keys(models.pools).some(key=>!Object.hasOwn(DEFAULT_MODEL_POOLS,key))||Object.keys(models.nonOperation).length!==Object.keys(NON_OPERATION_ROLES).length||Object.keys(models.nonOperation).some(key=>!Object.hasOwn(NON_OPERATION_ROLES,key)))throw Error('Invalid config.yaml: expected language, model, effort and the closed quota-aware model pools/non-operation role map.');
   for(const [pool,members] of Object.entries(models.pools))if(!Array.isArray(members)||members.length!==2||new Set(members).size!==2||members.some(id=>typeof id!=='string'||!plain(runtimes[id]))||!(members.length===DEFAULT_MODEL_POOLS[pool].length&&members.every(id=>DEFAULT_MODEL_POOLS[pool].includes(id))))throw Error(`Invalid config.yaml: models.pools.${pool} must contain its canonical pair of two unique known runtime ids.`);
@@ -444,7 +436,7 @@ export function inspectOwnerConfig(root=configRoot){
  *             or `starci kernel run-deferred-tests`); e2e.verify then runs the FULL e2e suite.
  * An absent, null or unreadable owner file reads as the defaults: harness off, unit on, e2e off.
  */
-export const SPEC_FAMILIES=Object.freeze(['harness','unit','e2e']);
+const SPEC_FAMILIES=Object.freeze(['harness','unit','e2e']);
 export const SPEC_DEFAULTS=Object.freeze({harness:false,unit:true,e2e:false});
 export function specsSettings(config){const specs=plain(config?.specs)?config.specs:{};return Object.fromEntries(SPEC_FAMILIES.map(key=>[key,typeof specs[key]==='boolean'?specs[key]:SPEC_DEFAULTS[key]]));}
 /** specs.harness of the owner file under `root` (tolerant read: inspectOwnerConfig): true only when the owner opted in to `--specs all`. */

package/runtime/engine/secrets.mjs

@@ -0,0 +1,130 @@
+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);} };
+
+/** 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=line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+    if(!m)continue;
+    let value=m[2];
+    if(value.length>=2&&(value[0]==='"'||value[0]==="'")&&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;
+}
+
+/** 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}={}){
+  const refuse=(reason,message)=>{
+    const error=new Error(`SOPS identity [${reason}]: ${message}`);
+    error.name='SopsIdentityRefusal';error.identityRefusal=reason;
+    return {mode:'refused',env:null,error};
+  };
+  if(!env||typeof env!=='object'||Array.isArray(env))return refuse('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 refuse('ambiguous-environment','multiple Windows aliases select an age identity');
+  if(inline.length){
+    const name=inline[0];
+    if(!credentialPresent(env[name]))return refuse('disabled-inline','SOPS_AGE_KEY is explicitly empty or invalid');
+    remember(env[name].trim());
+    return {...refuse('inline-context-unqualified','the supplied SOPS_AGE_KEY awaits an owned selected-identity isolation capability; no SOPS process was launched'),inlineName:name};
+  }
+  let file=identity;
+  if(files.length){
+    const value=env[files[0]];
+    if(!credentialPresent(value))return refuse('disabled-file','SOPS_AGE_KEY_FILE is explicitly empty or invalid');
+    if(identity!==null&&identity!==undefined&&identity!==value)return refuse('conflicting-files','two different original identity files were explicitly selected');
+    file=value;
+  }
+  if(file!==null&&file!==undefined){
+    if(!credentialPresent(file))return refuse('invalid-file','the original identity file selection is empty or invalid');
+    if(!path.isAbsolute(file))return refuse('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 refuse('identity-file-unavailable','the explicitly selected original identity must be a regular non-symlink file');
+    }catch{return refuse('identity-file-unavailable','the explicitly selected original identity file is unavailable');}
+    return {mode:'file',env:{...env,SOPS_AGE_KEY_FILE:file},error:null};
+  }
+  if(required)return refuse('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/knowledge/hfs/canon-pins.yaml

@@ -22,68 +22,68 @@ 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).
   '@starci/eslint-canon-be':
-    version: 3.0.9
+    version: 3.0.10
     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.'
   '@starci/eslint-canon-fe':
-    version: 8.0.9
+    version: 8.0.10
     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).'
   '@starci/stylelint-canon':
-    version: 2.0.4
+    version: 2.0.5
     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.'
   '@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.5
     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.'
   '@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).'
   '@starci/cli':
-    version: 1.0.0
+    version: 1.0.1
     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.'
   '@starci/hfs':
-    version: 4.0.9
+    version: 4.0.10
     group: starci
     install: registry
     side: both

package/runtime/modules/models/registry.yaml

@@ -154,9 +154,6 @@ targets:
   # difficulty and whose `defaultModel` covers an unpinned difficulty. A pool target names no model itself.
   codex-agent:
     runtime: codex
-    profiles:
-      working: gpt-6-luna
-      reasoning: gpt-6.1-sol
     orcaLaunch: {agent: codex}   # orca orchestration worker-start --agent codex
   # Launch-only targets: an explicit `--model gpt-6.1-sol` or `--model gpt-6-luna` request reaches that one model
   # on the Codex provider window. They are off every automatic chain; allocation routes the codex-agent pool.
@@ -164,16 +161,10 @@ targets:
   gpt-6.1-sol:
     runtime: codex
     defaultModel: gpt-6.1-sol
-    profiles:
-      working: gpt-6.1-sol
-      reasoning: gpt-6.1-sol
     orcaLaunch: {agent: codex}   # orca orchestration worker-start --agent codex
   gpt-6-luna:
     runtime: codex
     defaultModel: gpt-6-luna
-    profiles:
-      working: gpt-6-luna
-      reasoning: gpt-6-luna
     orcaLaunch: {agent: codex}   # orca orchestration worker-start --agent codex
   # Cursor: Orca agent id `cursor` (binary cursor-agent). A launch-only target like gpt-6.1-sol: off every automatic chain,
   # reached by an explicit `--model auto` (the CLI's default) or any id of the account's `cursor-agent --list-models`.
@@ -183,43 +174,14 @@ targets:
   cursor-agent:
     runtime: cursor
     defaultModel: auto
-    profiles:
-      working: auto
-      reasoning: auto
     orcaLaunch: {agent: cursor}   # orca orchestration worker-start --agent cursor
   claude-agent:
     runtime: claude
-    profiles:
-      working: opus
-      reasoning: opus-reviewer
     orcaLaunch: {agent: claude}   # orca orchestration worker-start --agent claude
   devin-agent:
     runtime: devin
     executionHosts: [orca]
-    profiles:
-      working: devin-worker
-      reasoning: devin-reviewer
     orcaLaunch: {agent: devin}   # orca orchestration worker-start --agent devin
-targetAliases:
-  codex-gpt-6.1-sol: codex-agent
-  codex-gpt-6-luna: codex-agent
-  devin-devin-worker: devin-agent
-  devin-devin-reviewer: devin-agent
-  # Bare model ids that are not targets resolve to the provider-window pool that carries them, so workflow
-  # quota entries land on the right window. gpt-6.1-sol and gpt-6-luna are targets; their `runtime: codex`
-  # names the window.
-  claude-opus: claude-agent
-  claude-opus-5-5: claude-agent
-skills:
-  starci:
-    chains:
-      working:
-        - devin-agent
-        - codex-agent
-        - claude-agent
-      reasoning:
-        - claude-agent
-        - codex-agent
 # An operator whose kind runtimes.yaml roleOfKind marks think work with no declared order carries the
 # think order of runtimes.yaml allocation.preference.think (Opus, then Sol) and nothing else;
 # scripts/route/route-model.mjs refuses any other pool for it. A kind's declared order wins: owner routing
@@ -524,7 +486,7 @@ selection: |-
   operator chain from top to bottom, choosing the first ready runtime/profile. Fall through only
   after an allowed failure with verified no-effect state. This policy never installs an agent,
   authenticates a provider, grants tools or expands the workflow authority. Every pool launches the one
-  way (modules/kernel/contract-changes/launch-through-worker-start.yaml): `orca orchestration worker-start --agent
+  way (modules/kernel/start-workflow.yaml): `orca orchestration worker-start --agent
   <runtime> [--model <id> --effort <level>] --spec <prompt>` (Orca files the Task), the unattended flags from Orca's per-agent
   default args; the launcher takes the agent terminal from the start receipt (else worker-show) and attests the effective agent and model
   (worker-show). Devin takes no model flag (Orca: --model is for Claude, Codex and Cursor) and starts on its CLI default.

package/runtime/modules/models/runtimes.yaml

@@ -275,9 +275,6 @@ allocation:
   # start waits for an Orca that does not answer, and how long after a responding Orca calls a kernel dead
   # it is asked again.
   hostOutage: {waitMs: 90000, deathSettleMs: 10000}
-  # resume: unused since resume-all.mjs was retired (2026-09-28); the logon run waited orcaWaitMs for Orca; the scheduled task
-  # re-runs resume every everyMs (whole minutes: schtasks /MO).
-  resume: {orcaWaitMs: 600000, everyMs: 600000}
   # supervisorTick: the numbers of the retired supervisor tick (2026-09-28) that the reconciler controllers still read
   # (host thresholds, orca probes, statusApp port, owner digest cadence); everyMs is unused. The tick ran every
   # everyMs (whole minutes: schtasks repetition). host: above maxNode node.exe or maxGit git.exe processes the host
@@ -354,9 +351,6 @@ allocation:
     routeAs: implementation.plan
     minDifficulty: hard
     effort: high
-  # restart: unused since restart-all.mjs was retired (2026-09-28); it waited waitMs for every running workflow to show one live
-  # Kernel, polling every pollMs.
-  restart: {waitMs: 480000, pollMs: 20000}
   # selfReload (scripts/machine/self-reload.mjs): a watchdog loop re-execs at most once per minIntervalMs; its
   # replacement takes over the loop's lock within handoverMs or is stopped.
   selfReload: {minIntervalMs: 300000, handoverMs: 30000}

package/runtime/scripts/api/git/lib.mjs

@@ -6,6 +6,7 @@
 // caller's runner into {ok, stdout, stderr}. Only the call files beside this one import it: each names one git verb
 // (diff.mjs, ls-files.mjs, worktree-*.mjs, ...), and a caller folds the spawn result it gets back with the pure
 // helpers of scripts/lib/git.mjs (gitResultOf, gitOutputOf).
+import { assertMutationFence } from '../../lib/mutation-fence.mjs';
 import { spawnSync } from 'node:child_process';
 import { withoutGitLocalEnv } from '../../lib/git.mjs';
 
@@ -16,6 +17,7 @@ import { withoutGitLocalEnv } from '../../lib/git.mjs';
  * ERR_UNKNOWN_ENCODING, so it reaches spawnSync as encoding:null (Buffer output either way).
  */
 export const gitSpawn = (file, args, options = {}) => {
+  assertMutationFence({ kind: 'git-effect', args });
   const spawn = { encoding: 'utf8', windowsHide: true, ...options };
   if (spawn.encoding === 'buffer') spawn.encoding = null;
   return spawnSync(file, args, spawn);

package/runtime/scripts/hfs/architecture/fe-slot-allows.mjs

@@ -10,7 +10,7 @@ import { isFeTestPath } from '../rules/fe-no-tests.mjs';
  * root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
  * Files no slot owns are HFS_PATH_NO_SLOT's (`starci app check`), so together every front-end file is placed by exactly one slot and
  * named by it. A test path (a `.spec.tsx` or `.test.tsx` beside a component, a test directory or test tooling) is FE_NO_TESTS's
- * (R97, contract-change fe-no-tests): that rule is the one finding of such a file, so this check leaves it alone, as
+ * (R97 FE_NO_TESTS): that rule is the one finding of such a file, so this check leaves it alone, as
  * HFS_PATH_NO_SLOT does (scripts/hfs/path-findings.mjs).
  */
 export const FE_SLOT_ALLOWS_RULE_IDS = ['FE_SLOT_FILE_ROLE'];

package/runtime/scripts/lib/jsdoc.mjs

@@ -0,0 +1,35 @@
+/**
+ * The description form shared by runtime and product public-documentation checks.
+ * This proves local form; responsibility, accuracy and important decision rationale remain review.
+ */
+
+/** Whether AST-selected description text contains a letter or number; language and meaning remain review. */
+export const hasJsdocDescription = (description) => typeof description === "string" && /[\p{L}\p{N}]/u.test(description);
+
+/**
+ * Read description text before block tags; file-level headers do not describe a declaration.
+ * Tag payloads and punctuation cannot make an empty API description pass.
+ */
+export const jsdocDescription = (comment) => {
+  if (comment?.type !== "Block" || !comment.value.startsWith("*")) return "";
+  const prose = comment.value.replace(/^\*/, "").split(/\r?\n/u)
+    .map((line) => line.replace(/^\s*\*(?: ?)/u, "")).join("\n");
+  if (/(?:^|\s)@(?:file|fileoverview|overview|license|copyright)\b/u.test(prose)) return "";
+  const description = prose.split(/(?:^|\s)@[A-Za-z][\w-]*(?=\s|$)/u, 1)[0].trim();
+  return hasJsdocDescription(description) ? description : "";
+};
+
+/**
+ * Return the final adjacent JSDoc only when it describes this declaration.
+ * Decorated classes document the export after its decorators; member docs precede their decorators.
+ */
+export const jsdocBefore = (sourceCode, node) => {
+  const exported = node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration";
+  const anchor = exported
+    ? sourceCode.getTokens(node).find((token) => token.type === "Keyword" && token.value === "export")
+    : node.decorators?.[0] ?? node;
+  if (!anchor) return null;
+  const comment = sourceCode.getCommentsBefore(anchor).at(-1);
+  if (!jsdocDescription(comment)) return null;
+  return /^\s*$/u.test(sourceCode.getText().slice(comment.range[1], anchor.range[0])) ? comment : null;
+};

package/runtime/scripts/lib/mutation-fence.mjs

@@ -0,0 +1,15 @@
+// mutation-fence.mjs — ephemeral admission carried through awaited work, never a state store.
+import { AsyncLocalStorage } from 'node:async_hooks';
+const scope = new AsyncLocalStorage();
+
+/** Run one admitted call; the checker is synchronous and reads its existing durable owners again. */
+export const withMutationFence = (check, authority, fn) => scope.run({ check, authority, checking: false }, fn);
+/** Recheck after the actual transaction lock or immediately before a native effect. */
+export function assertMutationFence(boundary) {
+  const current = scope.getStore();
+  if (!current || current.checking) return;
+  current.checking = true;
+  try { current.check(boundary); } finally { current.checking = false; }
+}
+/** Identity stamped by existing write owners, never accepted from a command argument. */
+export const mutationAuthority = () => scope.getStore()?.authority ?? null;

package/runtime/scripts/lib/path-key.mjs

@@ -54,12 +54,12 @@ export const resolvedKey = (p) => foldCase(path.resolve(p));
 /** Whether `a` and `b` resolve to the same path (always case-folded, so differently-cased spellings count). */
 export const sameResolvedPath = (a, b) => pathKey(a, { fold: true }) === pathKey(b, { fold: true });
 /**
- * Whether `file` sits strictly under `root`. `key` normalizes both sides first (e.g. the registry's
- * realpath-folded treeKey) when the callers' spellings need it.
+ * Whether `file` sits under `root`; `includeSelf` also admits the root itself. `key` normalizes
+ * both sides first (e.g. the registry's realpath-folded treeKey) when their spellings need it.
  */
-export const insidePath = (root, file, { key = (p) => p } = {}) => {
+export const insidePath = (root, file, { key = (p) => p, includeSelf = false } = {}) => {
   const rel = path.relative(key(root), key(file));
-  return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel);
+  return (includeSelf || Boolean(rel)) && !rel.startsWith('..') && !path.isAbsolute(rel);
 };
 /**
  * A path-ish value (a string or a {path} entry) in relative compare form: trimmed, forward slashes,

package/runtime/scripts/lib/sops-envelope.mjs

@@ -56,3 +56,57 @@ export function isSopsEnvelope(text) {
   }
   try { return sopsTree(parseYaml(src)); } catch { return false; }
 }
+
+/** Admit one flat age envelope for the native selected-identity invocation; this is shape admission, never cryptographic proof. */
+export function selectedAgeEnvelope(text, format, recipient) {
+  const refuse = reason => ({ ok: false, reason });
+  if (!['binary', 'json', 'yaml', 'dotenv'].includes(format)) return refuse('unsupported-format');
+  let meta;
+  try {
+    if (format === 'dotenv') {
+      const pairs = new Map();
+      for (const line of String(text).split('\n')) {
+        if (!line || line.startsWith('#')) continue;
+        if (line.includes('\r')) return refuse('unsupported-dotenv');
+        const at = line.indexOf('=');
+        if (at < 1) return refuse('unsupported-dotenv');
+        const name = line.slice(0, at);
+        if (pairs.has(name)) return refuse('duplicate-key');
+        pairs.set(name, line.slice(at + 1).replaceAll('\\n', '\n'));
+      }
+      meta = {};
+      const age = {};
+      for (const [name, value] of pairs) {
+        if (!name.startsWith('sops_')) continue;
+        const key = name.slice('sops_'.length);
+        if (key === 'age__list_0__map_recipient') age.recipient = value;
+        else if (key === 'age__list_0__map_enc') age.enc = value;
+        else if (key === 'mac_only_encrypted') {
+          if (value !== 'false') return refuse('partial-mac');
+          meta[key] = false;
+        } else if (key.includes('__')) return refuse('unsupported-key-group');
+        else meta[key] = value;
+      }
+      meta.age = [age];
+    } else {
+      const doc = parseYaml(String(text));
+      if (format !== 'yaml') JSON.parse(String(text));
+      if (format === 'binary' && (!doc || Object.keys(doc).length !== 2 || !Object.hasOwn(doc, 'data') || !Object.hasOwn(doc, 'sops') || typeof doc.data !== 'string')) return refuse('unsupported-binary-shape');
+      meta = doc?.sops;
+    }
+  } catch { return refuse('invalid-envelope'); }
+  if (!meta || typeof meta !== 'object' || Array.isArray(meta) || !isSopsEnvelope(text)) return refuse('invalid-envelope');
+  if (Object.hasOwn(meta, 'key_groups') || Object.hasOwn(meta, 'shamir_threshold')) return refuse('unsupported-key-group');
+  const providers = ['kms', 'gcp_kms', 'hckms', 'azure_kv', 'hc_vault', 'pgp'];
+  for (const name of providers) if (Object.hasOwn(meta, name) && (!Array.isArray(meta[name]) || meta[name].length)) return refuse('non-age-provider');
+  const fields = new Set([...providers, 'age', 'lastmodified', 'mac', 'version', 'unencrypted_suffix', 'encrypted_suffix', 'unencrypted_regex', 'encrypted_regex', 'unencrypted_comment_regex', 'encrypted_comment_regex', 'mac_only_encrypted']);
+  if (Object.keys(meta).some(name => !fields.has(name))) return refuse('unknown-metadata');
+  if (Object.hasOwn(meta, 'mac_only_encrypted') && meta.mac_only_encrypted !== false) return refuse('partial-mac');
+  if (!Array.isArray(meta.age) || meta.age.length !== 1) return refuse('unsupported-age-set');
+  const entry = meta.age[0];
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry) || Object.keys(entry).some(name => !['recipient', 'enc'].includes(name))) return refuse('invalid-age-entry');
+  if (typeof entry.recipient !== 'string' || entry.recipient !== recipient) return refuse('recipient-mismatch');
+  if (typeof entry.enc !== 'string' || !entry.enc.startsWith('-----BEGIN AGE ENCRYPTED FILE-----\n') || !entry.enc.includes('\n-----END AGE ENCRYPTED FILE-----')) return refuse('invalid-age-entry');
+  if (typeof meta.version !== 'string' || !/^\d+\.\d+\.\d+$/.test(meta.version) || typeof meta.lastmodified !== 'string' || !Number.isFinite(Date.parse(meta.lastmodified))) return refuse('invalid-envelope');
+  return { ok: true };
+}