@starci/hfs 4.3.0 → 4.4.1

package/runtime/scripts/hfs/stacks-gate.mjs

@@ -0,0 +1,414 @@
+import { composeEntries } from '../lib/compose-values.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { lsFiles } from '../api/git/ls-files.mjs';
+import {parseYaml} from '../../engine/yaml.mjs';
+import {slash} from '../lib/path-key.mjs';
+import { isInside, walkFiles } from '../lib/walk.mjs';
+import { composeIncludePaths, swarmInventoryIssues, swarmModelIssues } from '../lib/swarm-stack.mjs';
+import { swarmHardeningIssues } from './rules/stacks-swarm.mjs';
+import { ingressIssues } from './rules/stacks-ingress.mjs';
+import { liteBackingIssues } from './rules/stacks-lite-backing.mjs';
+import { releaseBackupIssues, scheduleIssues } from './rules/stacks-release.mjs';
+import { stacksDeploymentContexts } from './rules/stacks-runtime.mjs';
+import { appEdition, applicationStackFindings, liteCustodyDirectory } from './starcistacks-runtime.mjs';
+
+const RESULT='starci/application-stacks-check@1';
+const STACKS_DIR='.starcistacks';
+const MAX_INPUT_BYTES=4*1024*1024;
+const SCHEMA_ID='starci/application-stacks@1';
+const RUNBOOK_COMMANDS=['prepare','doctor','up','status','logs','down','verification'];
+const PLAINTEXT_SECRET_PATTERN=/\.(key|pem|p12|pfx)$/i;
+const inside=(root,target)=>isInside(path.resolve(root),path.resolve(target));
+const object=value=>value&&typeof value==='object'&&!Array.isArray(value);
+const sensitive=/pass(word)?|secret|token|credential|private[_-]?key|api[_-]?key/i;
+const nonempty=value=>typeof value==='string'&&Boolean(value.trim());
+const manifestSchema=parseYaml(fs.readFileSync(new URL('../../modules/schemas/application-stacks.schema.yaml',import.meta.url),'utf8'));
+const HARDENING_CODES=new Set([
+  'STACKS_SECRET_NOT_EXTERNAL','STACKS_SECRET_UNVERSIONED','STACKS_SECRET_ENV_LITERAL','STACKS_PORT_PUBLISHED',
+  'STACKS_SECOND_INGRESS','STACKS_DNS_UNDECLARED','STACKS_HOST_UNROUTED','STACKS_TLS_UNDECLARED',
+  'STACKS_PLACEMENT_MISSING','STACKS_HEALTHCHECK_MISSING','STACKS_UPDATE_POLICY_MISSING','STACKS_REALTIME_SCALED',
+  'STACKS_RELEASE_UNDECLARED','BACKUP_UNDECLARED','BACKUP_PROOF_MISSING','STACKS_MODEL_UNAVAILABLE',
+  'HFS_SCHEDULE_UNDECLARED','STACKS_INGRESS_UNDECLARED','STACKS_INGRESS_UNKNOWN',
+  'STACKS_LITE_SELFHOSTED_DB','STACKS_SIDECAR_VOLUME_UNDECLARED','STACKS_SIDECAR_DB_UNSUPPORTED',
+]);
+
+function regular(file,{root=null}={}){
+  try{
+    const stat=fs.lstatSync(file);if(!stat.isFile()||stat.isSymbolicLink())return false;
+    return !root||inside(root,fs.realpathSync(file));
+  }catch{return false;}
+}
+function directory(file){try{return fs.lstatSync(file).isDirectory()&&!fs.lstatSync(file).isSymbolicLink();}catch{return false;}}
+function safeAncestors(root,target){
+  if(!inside(root,target))return false;
+  let cursor=path.resolve(target),base=path.resolve(root);
+  while(cursor!==base){
+    if(fs.existsSync(cursor)&&fs.lstatSync(cursor).isSymbolicLink())return false;
+    cursor=path.dirname(cursor);
+  }
+  return true;
+}
+function resolvedPath(base,relative){
+  if(!nonempty(relative)||path.isAbsolute(relative)||String(relative).split(/[\\/]/).includes('..'))return null;
+  const target=path.resolve(base,String(relative));return inside(base,target)&&safeAncestors(base,target)?target:null;
+}
+
+function validateSchema(value){
+  const errors=[],isObject=value=>value!==null&&typeof value==='object'&&!Array.isArray(value),resolve=ref=>ref.slice(2).split('/').reduce((node,key)=>node?.[key],manifestSchema);
+  const typeOk=(node,type)=>{
+    if(type==='object')return isObject(node);
+    if(type==='array')return Array.isArray(node);
+    if(type==='integer')return Number.isInteger(node);
+    if(type)return typeof node===type;
+    return true;
+  };
+  const checkString=(node,shape,at)=>{
+    if(shape.minLength&&node.length<shape.minLength)errors.push({path:at,message:'string too short'});
+    if(shape.pattern&&!new RegExp(shape.pattern,'u').test(node))errors.push({path:at,message:'pattern mismatch'});
+  };
+  const checkNumber=(node,shape,at)=>{
+    if(shape.minimum!==undefined&&node<shape.minimum)errors.push({path:at,message:'number below minimum'});
+    if(shape.maximum!==undefined&&node>shape.maximum)errors.push({path:at,message:'number above maximum'});
+  };
+  const checkObject=(node,shape,at)=>{
+    if(shape.minProperties&&Object.keys(node).length<shape.minProperties)errors.push({path:at,message:'object has too few properties'});
+    for(const key of shape.required??[])if(!Object.hasOwn(node,key))errors.push({path:at,message:`missing ${key}`});
+    for(const [key,child] of Object.entries(node)){
+      if(Object.hasOwn(shape.properties??{},key))check(child,shape.properties[key],`${at}/${key}`);
+      else if(shape.additionalProperties===false)errors.push({path:`${at}/${key}`,message:'unknown field'});
+      else if(isObject(shape.additionalProperties))check(child,shape.additionalProperties,`${at}/${key}`);
+    }
+  };
+  const checkAlternatives=(node,shape,at,check)=>{
+    const matched=shape.anyOf.some((option)=>{
+      const start=errors.length;check(node,option,at);
+      if(errors.length===start)return true;
+      errors.splice(start);return false;
+    });
+    if(!matched)errors.push({path:at,message:'matches none of the allowed shapes'});
+  };
+  const checkArray=(node,shape,at,check)=>{
+    if(shape.minItems&&node.length<shape.minItems)errors.push({path:at,message:'array too short'});
+    node.forEach((item,index)=>shape.items&&check(item,shape.items,`${at}/${index}`));
+  };
+  const check=(node,shape,at)=>{
+    if(shape?.$ref)return check(node,resolve(shape.$ref),at);
+    if(Array.isArray(shape?.anyOf)){
+      checkAlternatives(node,shape,at,check);
+      return;
+    }
+    const typed=typeOk(node,shape?.type);
+    if(!typed){errors.push({path:at,message:`expected ${shape.type}`});return;}
+    if(Object.hasOwn(shape??{},'const')&&node!==shape.const)errors.push({path:at,message:'const mismatch'});
+    if(Array.isArray(shape?.enum)&&!shape.enum.includes(node))errors.push({path:at,message:'value outside enum'});
+    if(typeof node==='string')checkString(node,shape,at);
+    if(typeof node==='number')checkNumber(node,shape,at);
+    if(Array.isArray(node)){
+      checkArray(node,shape,at,check);
+      return;
+    }
+    if(!isObject(node))return;
+    checkObject(node,shape,at);
+  };check(value,manifestSchema,'$');return errors;
+}
+const unresolved=value=>typeof value==='string'&&/(^|[^$])\$\{/.test(value);
+const serviceUnresolved=(service)=>{
+  const build=object(service?.build)?service.build:{context:service?.build};
+  const values=[service?.image,build.context,build.dockerfile,...(Array.isArray(service?.ports)?service.ports:[])];
+  for(const volume of Array.isArray(service?.volumes)?service.volumes:[])values.push(object(volume)?volume.source:String(volume).split(':')[0]);
+  for(const [key,value] of composeEntries(service?.environment, { isMapping: object }))if(!sensitive.test(key))values.push(value);
+  return values.some(unresolved);
+};
+function unresolvedCompose(model){
+  for(const service of Object.values(object(model?.services)?model.services:{})){
+    if(serviceUnresolved(service))return true;
+  }
+  return Object.values(object(model?.secrets)?model.secrets:{}).some(item=>unresolved(item?.file));
+}
+function sopsEnvelope(file){
+  // Recognizes both the YAML/JSON envelope (a "sops" object) and the flattened dotenv envelope SOPS
+  // emits for a .env member (sops_lastmodified=, sops_mac=, sops_age__list_0__map_enc=, ...).
+  try{
+    if(fs.statSync(file).size>MAX_INPUT_BYTES)return false;
+    const text=fs.readFileSync(file,'utf8');
+    return (/(?:(?:^|\n)sops:|["']sops["']\s*:|(?:^|\n)sops_[a-z0-9_]+=)/.test(text))&&/ENC\[AES256_GCM,data:/.test(text);
+  }catch{return false;}
+}
+
+function gitTrackedSet(root){
+  try{
+    const result=lsFiles(['--',STACKS_DIR],{dir:root,timeout:5000});
+    if(result.error||result.status!==0||typeof result.stdout!=='string')return null;
+    return new Set(result.stdout.split(/\r?\n/).filter(Boolean).map(slash));
+  }catch{return null;}
+}
+function composeLike(file){
+  try{
+    if(fs.statSync(file).size>MAX_INPUT_BYTES)return false;
+    const doc=parseYaml(fs.readFileSync(file,'utf8'));
+    return object(doc)&&(object(doc.services)||Array.isArray(doc.include));
+  }catch{return false;}
+}
+function reachableComposeFiles(envDir,entries){
+  const reachable=new Set(),queue=[...entries];
+  while(queue.length){
+    const relative=queue.shift(),target=resolvedPath(envDir,relative);
+    if(!target||reachable.has(target))continue;
+    reachable.add(target);
+    if(!regular(target,{root:envDir}))continue;
+    let doc=null;try{doc=parseYaml(fs.readFileSync(target,'utf8'));}catch{continue;}
+    for(const include of composeIncludePaths(doc??{}).paths)
+      queue.push(path.isAbsolute(include)?include:slash(path.join(path.relative(envDir,path.dirname(target)),include)));
+  }
+  return reachable;
+}
+function scanForUndeclaredCompose(root,envDir,reachable,add,at){
+  const infra=path.join(envDir,'infra');
+  if(!directory(infra))return;
+  const stack=[infra];
+  while(stack.length){
+    const dir=stack.pop();
+    let entries=[];try{entries=fs.readdirSync(dir,{withFileTypes:true});}catch{continue;}
+    for(const entry of entries){
+      const full=path.join(dir,entry.name);
+      if(entry.isSymbolicLink())continue;
+      if(entry.isDirectory()){stack.push(full);continue;}
+      if(!/\.ya?ml$/i.test(entry.name)||reachable.has(full)||!composeLike(full))continue;
+      add('STACKS_UNDECLARED_COMPOSE',at,`${slash(path.relative(root,full))} is a Compose-shaped file under infra/ that is not declared or reachable from composeFiles; the composeFiles list must be the complete list for this environment`);
+    }
+  }
+}
+
+const loadInputs=({manifestFile,deploymentModelFile,errors,add})=>{
+  const input={manifest:{},model:{}};
+  try{if(!errors.some(item=>['manifest-unavailable','input-too-large'].includes(item.code)&&item.path===`${STACKS_DIR}/application-stacks.yaml`))input.manifest=parseYaml(fs.readFileSync(manifestFile,'utf8'));}
+  catch{add('manifest-invalid',`${STACKS_DIR}/application-stacks.yaml`,'manifest YAML could not be parsed');}
+  try{if(!errors.some(item=>['deployment-model-unavailable','input-too-large'].includes(item.code)&&item.path==='deploymentModelFile')){
+    const text=fs.readFileSync(deploymentModelFile,'utf8');try{input.model=JSON.parse(text);}catch{input.model=parseYaml(text);}
+  }}catch{add('deployment-model-invalid','deploymentModelFile','rendered deployment JSON or YAML could not be parsed');}
+  if(!object(input.manifest))input.manifest={};
+  if(!object(input.model))input.model={};
+  return input;
+};
+const checkStackEntry=(entry,environmentNames,add,{stacksRoot,lite})=>{
+  if(!entry.isDirectory()||entry.isSymbolicLink())return;
+  if(entry.name==='tmp'){add('STACKS_SCRATCH_IN_CANONICAL',`${STACKS_DIR}/tmp`,'scratch belongs in the OS temp directory, not a tracked .starcistacks/tmp');return;}
+  if(entry.name==='k8s')return;
+  if(lite&&liteCustodyDirectory(path.join(stacksRoot,entry.name)))return;
+  if(!environmentNames.has(entry.name))add('STACKS_UNDECLARED_ENVIRONMENT',`${STACKS_DIR}/${entry.name}`,`${entry.name} is not an environment the declaration admits; either the declaration admits it or it is not an environment`);
+};
+const checkDeclaredEnvironmentDirs=(stacksRoot,environmentNames,add)=>{
+  for(const name of environmentNames)if(!directory(path.join(stacksRoot,name)))add('environment-directory-missing',`${STACKS_DIR}/${name}`,`declared environment ${name} has no directory`);
+};
+const checkStacksTree=({stacksRoot,manifest,environmentNames,add,lite})=>{
+  if(!directory(stacksRoot))return;
+  let entries=[];try{entries=fs.readdirSync(stacksRoot,{withFileTypes:true});}catch{}
+  for(const entry of entries)checkStackEntry(entry,environmentNames,add,{stacksRoot,lite});
+  checkDeclaredEnvironmentDirs(stacksRoot,environmentNames,add);
+  const k8sDir=path.join(stacksRoot,'k8s'),k8sExists=directory(k8sDir);
+  if(manifest.k8s?.status==='supported'&&!k8sExists)add('k8s-directory-missing',`${STACKS_DIR}/k8s`,'k8s.status is supported but .starcistacks/k8s is missing');
+  if(manifest.k8s?.status==='deferred'&&k8sExists)add('k8s-directory-unexpected',`${STACKS_DIR}/k8s`,'k8s.status is deferred, so a .starcistacks/k8s directory contradicts the declaration');
+};
+const checkComposeFiles=({spec,environment,envDir,root,add})=>{
+  const composeFiles=Array.isArray(spec.composeFiles)?spec.composeFiles:[];
+  if(!composeFiles.length)add('compose-files-empty',`environments.${environment}.composeFiles`,'declare at least one environment-relative Compose source file');
+  const safeComposeFiles=[];
+  for(const [index,relative] of composeFiles.entries()){
+    const target=resolvedPath(envDir,relative);
+    if(!target||!regular(target,{root:envDir}))add('compose-path-unsafe',`environments.${environment}.composeFiles[${index}]`,'Compose source must be a regular non-symlink file below the environment directory');
+    else safeComposeFiles.push(relative);
+  }
+  if(directory(envDir)){
+    if(nonempty(spec.renderedModel))safeComposeFiles.push(spec.renderedModel);
+    const reachable=reachableComposeFiles(envDir,safeComposeFiles);
+    scanForUndeclaredCompose(root,envDir,reachable,add,`environments.${environment}.composeFiles`);
+  }
+};
+const checkRunbook=({spec,environment,envDir,add})=>{
+  if(!nonempty(spec.runbook))add('runbook-path-invalid',`environments.${environment}.runbook`,'runbook must name a file inside the environment directory');
+  else{
+    const runbookFile=resolvedPath(envDir,spec.runbook);
+    const oversized=(()=>{try{return fs.statSync(runbookFile).size>MAX_INPUT_BYTES;}catch{return true;}})();
+    if(!runbookFile||!regular(runbookFile,{root:envDir})||oversized)
+      add('runbook-path-invalid',`environments.${environment}.runbook`,'runbook must resolve to an existing regular non-symlink file below the environment directory');
+    else{
+      let text='';try{text=fs.readFileSync(runbookFile,'utf8');}catch{}
+      for(const command of RUNBOOK_COMMANDS){
+        const rowPattern=new RegExp(String.raw`^\s*\|\s*${command}\s*\|`,'im');
+        if(!rowPattern.test(text))add('runbook-command-missing',`environments.${environment}.runbook#${command}`,`runbook must document the ${command} command`);
+      }
+    }
+  }
+};
+const checkSecret=(secret,at,{envDir,environment,root,tracked,secretNames,add})=>{
+  if(!object(secret))return;
+  if(secretNames.has(secret.name))add('secret-duplicate',`${at}.name`,'secret names must be unique');else secretNames.add(secret.name);
+  const plain=nonempty(secret.where)?resolvedPath(envDir,secret.where):null;
+  const enc=nonempty(secret.where)?resolvedPath(envDir,`${secret.where}.enc`):null;
+  if(!enc||!regular(enc,{root:envDir})||!sopsEnvelope(enc))
+    add('encrypted-ref-invalid',`${at}.where`,'secret must resolve to <where>.enc as a recognizable SOPS envelope, an existing regular file below the environment directory');
+  if(nonempty(secret.where)&&!plain)
+    add('materialized-path-invalid',`${at}.where`,'secret plaintext path and its existing ancestors must remain below the environment directory without symlinks');
+  if(!String(secret.recipientPolicy??'').trim()||!String(secret.keyCustody??'').trim())
+    add('secret-policy-missing',at,'secret recipient and key custody policies are required');
+  if(tracked&&plain&&tracked.has(slash(path.relative(root,plain))))
+    add('STACKS_PLAINTEXT_SECRET',`${at}.where`,'a decrypted secret member must never be a tracked file; only its .enc member is committed');
+};
+const checkSecrets=({spec,environment,envDir,root,add})=>{
+  const declaredSecrets=Array.isArray(spec.secrets)?spec.secrets:[],secretNames=new Set();
+  const tracked=directory(envDir)?gitTrackedSet(root):null;
+  for(const [index,secret] of declaredSecrets.entries())
+    checkSecret(secret,`environments.${environment}.secrets[${index}]`,{envDir,environment,root,tracked,secretNames,add});
+  if(tracked){
+    const envPrefix=`${slash(path.relative(root,envDir))}/`;
+    for(const relTracked of tracked){
+      if(!relTracked.startsWith(envPrefix))continue;
+      const base=path.basename(relTracked);
+      if(PLAINTEXT_SECRET_PATTERN.test(base)||base==='id_rsa')
+        add('STACKS_PLAINTEXT_SECRET',relTracked,'a tracked file below the environment directory matches a plaintext secret pattern; only <name>.enc may be committed');
+    }
+  }
+};
+const checkEnvironmentSpec=({spec,environment,envDir,ids,root,add})=>{
+  if(spec.status!=='supported')add('environment-unsupported',`environments.${environment}`,'environment must be explicitly supported');
+  if(!['docker-compose','docker-swarm'].includes(spec.runtime))add('runtime-invalid',`environments.${environment}.runtime`,'runtime must be docker-compose or docker-swarm');
+  checkComposeFiles({spec,environment,envDir,root,add});
+  const bindings=object(spec.components)?spec.components:{};
+  for(const id of Object.keys(bindings))if(!ids.has(id))
+    add('binding-component-unknown',`environments.${environment}.components.${id}`,'environment binds a component id that is absent from the top-level inventory');
+  checkRunbook({spec,environment,envDir,add});
+  checkSecrets({spec,environment,envDir,root,add});
+};
+const checkServiceIds=(services,ids,add)=>{
+  for(const service of Object.keys(services))if(!ids.has(service))
+    add('compose-service-unclassified',`services.${service}`,'rendered service name is not a declared component id');
+};
+const checkServiceEnvironment=(services,add)=>{
+  for(const [service,definition] of Object.entries(services))for(const [key] of composeEntries(definition?.environment, { isMapping: object }))
+    if(sensitive.test(key)&&!/_FILE$/i.test(key))add('plaintext-sensitive-environment',`services.${service}.environment.${key}`,'sensitive configuration is present as a direct environment value; value redacted');
+};
+const checkModel=({model,ids,spec,manifest,lite,add})=>{
+  const services=object(model.services)?model.services:{};
+  checkServiceIds(services,ids,add);
+  if(unresolvedCompose(model))add('compose-placeholder-unresolved','composeModel','rendered Compose still contains an unresolved interpolation placeholder in a host-resolved field');
+  checkServiceEnvironment(services,add);
+  if(object(spec)&&spec.runtime==='docker-swarm')for(const issue of swarmModelIssues({model,components:manifest.components,bindings:spec.components,lite}))
+    add('HFS_STACKS_SHAPE',issue.at,issue.message);
+};
+
+const checkInputPaths=({environment,stacksRoot,manifestFile,deploymentModelFile,add})=>{
+  if(!nonempty(environment))add('environment-invalid','environment','environment must name a declared environment');
+  if(!regular(manifestFile,{root:stacksRoot}))add('manifest-unavailable',`${STACKS_DIR}/application-stacks.yaml`,`manifest must be a regular file inside ${STACKS_DIR}`);
+  if(!regular(deploymentModelFile))add('deployment-model-unavailable','deploymentModelFile','rendered deployment evidence must be a regular, non-symlink file');
+  for(const [file,at] of [[manifestFile,`${STACKS_DIR}/application-stacks.yaml`],[deploymentModelFile,'deploymentModelFile']])
+    try{if(fs.statSync(file).size>MAX_INPUT_BYTES)add('input-too-large',at,'input exceeds the 4 MiB static-check limit');}catch{}
+};
+const componentIdsOf=(manifest,add)=>{
+  const catalog=object(manifest.components)?manifest.components:{},ids=new Set(Object.keys(catalog));
+  if(!ids.size)add('components-empty','components','declare at least one applicable application component');
+  for(const id of ids)if(!/^[a-z][a-z0-9-]*$/.test(id))add('component-invalid',`components.${id}`,'component ids must be lowercase kebab-case');
+  return ids;
+};
+const environmentMapOf=(manifest,add)=>{
+  const environments=object(manifest.environments)?manifest.environments:{},environmentNames=new Set(Object.keys(environments));
+  if(!environmentNames.size)add('environments-empty','environments','declare at least one supported environment');
+  return {environments,environmentNames};
+};
+const checkKubernetesDeclaration=(manifest,add)=>{
+  if(!['deferred','supported'].includes(manifest.k8s?.status)||!String(manifest.k8s?.reason??'').trim())
+    add('k8s-status-invalid','k8s','Kubernetes must be explicitly deferred or supported with a reason');
+};
+const checkSelectedEnvironment=({environment,environmentNames,environments,stacksRoot,ids,root,model,manifest,lite,add})=>{
+  if(nonempty(environment)&&!environmentNames.has(String(environment)))
+    add('environment-unknown','environment',`environment must be one the declaration admits: ${[...environmentNames].join(', ')}`);
+  const spec=environments[String(environment)],envDir=path.join(stacksRoot,String(environment??''));
+  if(object(spec))checkEnvironmentSpec({spec,environment,envDir,ids,root,add});
+  checkModel({model,ids,spec,manifest,lite,add});
+};
+const checkStacksManifest=(manifest,model,{stacksRoot,environment,root,repo,add})=>{
+  for(const issue of validateSchema(manifest))add('schema-shape-invalid',issue.path,issue.message);
+  if(manifest.schema!==SCHEMA_ID)add('schema-invalid','schema',`expected ${SCHEMA_ID}`);
+  const ids=componentIdsOf(manifest,add),{environments,environmentNames}=environmentMapOf(manifest,add);
+  const lite=repo.edition==='lite';
+  checkStacksTree({stacksRoot,manifest,environmentNames,add,lite});
+  checkKubernetesDeclaration(manifest,add);
+  for(const issue of swarmInventoryIssues({components:manifest.components,lite}))add('HFS_STACKS_SHAPE',issue.at,issue.message);
+  checkSelectedEnvironment({environment,environmentNames,environments,stacksRoot,ids,root,model,manifest,lite,add});
+};
+
+function deploymentAvailable(model,errors){
+  const invalid=errors.some(item=>item.path==='deploymentModelFile');
+  return !invalid&&object(model.services)&&Object.keys(model.services).length>0&&model.include===undefined;
+}
+
+function diskEvidenceFiles(root){
+  const excluded=new Set(['node_modules','.git','.claude','.aws','.codex']);
+  return walkFiles(root,{ignoreReadErrors:true,exclude:(name,_file,entry)=>entry.isSymbolicLink()||excluded.has(name)})
+    .map(file=>slash(path.relative(root,file)));
+}
+
+function checkSwarmHardening({manifest,model,environment,root,files,repo,errors,add}){
+  const spec=manifest.environments?.[environment];
+  if(spec?.runtime!=='docker-swarm')return;
+  if(!deploymentAvailable(model,errors)){
+    add('STACKS_MODEL_UNAVAILABLE',`environments.${environment}`,'a rendered deployment model with nonempty services is required to judge Swarm safety');
+    return;
+  }
+  const context={doc:manifest,environment,spec,model,repoRoot:root,files,repo};
+  for(const finder of [swarmHardeningIssues,ingressIssues,liteBackingIssues,releaseBackupIssues,scheduleIssues])
+    for(const issue of finder(context))add(issue.code,issue.at,issue.message);
+}
+
+export function checkApplicationStacks({repoRoot,environment,deploymentModelFile,files,repo}={}){
+  const root=path.resolve(String(repoRoot??'')),stacksRoot=path.join(root,STACKS_DIR),manifestFile=path.join(stacksRoot,'application-stacks.yaml'),errors=[];
+  const declaration=repo??{edition:appEdition(root)};
+  const add=(code,at,message)=>errors.push({code,path:at,message});
+  checkInputPaths({environment,stacksRoot,manifestFile,deploymentModelFile,add});
+  const {manifest,model}=loadInputs({manifestFile,deploymentModelFile,errors,add});
+  checkStacksManifest(manifest,model,{stacksRoot,environment,root,repo:declaration,add});
+  checkSwarmHardening({manifest,model,environment,root,files:files??diskEvidenceFiles(root),repo:declaration,errors,add});
+  for(const item of applicationStackFindings(root))add(item.code,item.path,item.message);
+
+  return {schema:RESULT,ok:errors.length===0,environment,manifest:manifestFile,deploymentModel:path.resolve(String(deploymentModelFile??'')),errors,
+    limitations:['static conformance only; Docker was not invoked, host application processes were not started, and remote APIs were not called','the deployment model must be rendered by Docker Compose or Docker Stack tooling; provenance is supplied by the caller and is not independently authenticated','component classification, runbook completeness and secret custody are author assertions checked for consistency and structure, not independently discovered facts','SOPS envelope recognition is structural, not cryptographic verification or decryption','tracked-plaintext detection uses git ls-files when the repository is reachable and is skipped, not assumed clean, when it is not','runbook prepare, doctor and verification commands are declared and documented but not executed']};
+}
+
+const declarationFindingCodes=new Set(['STACKS_RELEASE_UNDECLARED','BACKUP_UNDECLARED','BACKUP_PROOF_MISSING','HFS_SCHEDULE_UNDECLARED']);
+
+function trackedGateFinding(entry,error){
+  let file=entry.file;
+  const code=HARDENING_CODES.has(error.code)?error.code:'HFS_STACKS_SHAPE';
+  const modelPath=/^(?:services(?:\.|$)|secrets(?:\.|$)|composeModel$|deploymentModelFile$)/.test(error.path);
+  if(declarationFindingCodes.has(error.code)||!modelPath&&code==='HFS_STACKS_SHAPE')file=`${STACKS_DIR}/application-stacks.yaml`;
+  if(error.code==='HFS_SCHEDULE_UNDECLARED'){
+    const source=error.path.replace(/:\d+$/,'');
+    if(/\.(?:sql|[cm]?[jt]s)$/.test(source))file=source;
+  }
+  return {code,level:'error',path:file,message:`${file}: ${error.path}: ${error.message}`};
+}
+
+const findingKey=finding=>`${finding.code}\n${slash(finding.path)}\n${finding.message}`;
+
+function trackedGateErrors(entry,context,files){
+  if(entry.unavailable)return [{code:'STACKS_MODEL_UNAVAILABLE',level:'error',path:entry.file,
+    message:`${entry.file}: environments.${entry.environment}: a tracked rendered deployment model is required to judge Swarm safety`}];
+  const result=checkApplicationStacks({repoRoot:context.repoRoot,environment:entry.environment,
+    deploymentModelFile:path.resolve(context.repoRoot,entry.file),files,repo:context.repo});
+  return result.errors.map(error=>trackedGateFinding(entry,error));
+}
+
+/** Run the public gate on the app's tracked rendered Swarm evidence, without duplicating finder results. */
+export function trackedStacksGateFindings(context={}){
+  const {deployments,files}=stacksDeploymentContexts(context),findings=[];
+  const existing=context.existingFindings??[],seen=new Set(existing.map(findingKey));
+  for(const entry of deployments){
+    for(const finding of trackedGateErrors(entry,context,files)){
+      if(context.inScope&&!context.inScope(finding.path))continue;
+      const key=findingKey(finding);
+      if(seen.has(key))continue;
+      seen.add(key);findings.push(finding);
+    }
+  }
+  return findings;
+}

package/runtime/scripts/hfs/starcistacks-runtime.mjs

@@ -0,0 +1,61 @@
+// Add app deployment conformance to the delivery/quality service gate without changing legacy runtime custody rules.
+import fs from 'node:fs';
+import path from 'node:path';
+import { walkFiles } from '../lib/walk.mjs';
+import { readJson } from './rules/read.mjs';
+import { stacksFindings } from './rules/stacks.mjs';
+import { stacksRuntimeFindings } from './rules/stacks-runtime.mjs';
+import { findStackDeclaration } from '../lib/stack-declaration.mjs';
+import { loadSlotManifest, openHfs } from './slots.mjs';
+
+/** Source paths admitted to stack and scheduling checks; never descend through symlinks. */
+function safeSourceDirectory(repoRoot, relative) {
+  const root = path.resolve(repoRoot);
+  let cursor = path.resolve(root, relative);
+  while (cursor !== root) {
+    try { if (fs.lstatSync(cursor).isSymbolicLink()) return false; } catch { return false; }
+    cursor = path.dirname(cursor);
+  }
+  return true;
+}
+
+function applicationStackFiles(repoRoot) {
+  return ['.starcistacks', '.github/workflows', 'deploy', 'scripts'].flatMap(relative => {
+    if (!safeSourceDirectory(repoRoot, relative)) return [];
+    return walkFiles(path.join(repoRoot, relative), { ignoreReadErrors: true, exclude: (_name, _file, entry) => entry.isSymbolicLink() })
+      .map(file => path.relative(repoRoot, file).replaceAll('\\', '/'));
+  });
+}
+
+export const appEdition = repoRoot => readJson(repoRoot, 'hfs.json')?.edition ?? 'full';
+
+/** An HFS app uses its edition's slot shape; other repository declarations still receive Swarm runtime checks. */
+export function applicationStackFindings(repoRoot) {
+  const files = applicationStackFiles(repoRoot), declaration = readJson(repoRoot, 'hfs.json');
+  if (declaration?.kind === 'app') {
+    try {
+      const resolver = openHfs({ declaration, manifest: loadSlotManifest() });
+      const findings = stacksFindings({ repoRoot, files, resolver }), manifestFile = '.starcistacks/application-stacks.yaml';
+      if (resolver.slot('app.starcistacks')?.requires?.includes('application-stacks.yaml') && !files.includes(manifestFile))
+        return [{ code: 'HFS_STACKS_SHAPE', level: 'error', path: manifestFile, message: `${manifestFile}: the app stacks slot requires this declaration` }, ...findings];
+      return findings;
+    } catch (error) {
+      return [{ code: 'HFS_STACKS_SHAPE', level: 'error', path: 'hfs.json', message: `hfs.json: cannot resolve the app stacks shape: ${error.message}` }];
+    }
+  }
+  const doc = findStackDeclaration(repoRoot).doc;
+  return doc ? stacksRuntimeFindings({ repoRoot, files, doc }) : [];
+}
+
+/** Lite may retain value-free development custody metadata without declaring a self-hosted development stack. */
+export function liteCustodyDirectory(directory) {
+  let entries;
+  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return false; }
+  return entries.length > 0 && entries.every(entry => {
+    if (entry.isSymbolicLink()) return false;
+    if (entry.isFile()) return entry.name === 'environment.json';
+    if (!entry.isDirectory() || entry.name !== 'secrets') return false;
+    return fs.readdirSync(path.join(directory, entry.name), { withFileTypes: true })
+      .every(secret => secret.isFile() && !secret.isSymbolicLink() && (secret.name === '.gitkeep' || /^[a-z0-9-]+\.enc$/.test(secret.name)));
+  });
+}

package/runtime/scripts/hfs/typescript-programs.mjs

@@ -9,14 +9,6 @@ import { byCodeUnit } from '../lib/list.mjs';
 // builds afresh.
 const runs = new AsyncLocalStorage();
 
-/** A program run: run(fn) shares what is built inside fn; release() drops it. */
-export function typeScriptProgramRun() {
-  const values = new Map();
-  return {
-    run: fn => runs.run(values, fn),
-    release: () => values.clear(),
-  };
-}
 
 function keyOf(value) {
   if (value === undefined) return 'u';

package/runtime/scripts/lib/command-tokens.mjs

@@ -0,0 +1,126 @@
+// command-tokens.mjs — the tokens of the tail of a documented `starci` command (the lexer under doc-commands.mjs).
+//
+// A tail is split into shell-like atoms: a run of non-space characters in which <...>, [...], {...}, (...) and quoted parts may hold
+// spaces. [..] and (..) groups are optional text (all their alternatives are named); a (..) group that opens with a plain word is
+// commentary and ends the command; a token that ends a sentence ends the command.
+
+import { trimEndWhile } from './trim-end.mjs';
+
+const CLOSERS = { '<': '>', '[': ']', '{': '}', '(': ')' };
+const TRAILING_CHARS = '.,;:!?)\'"`]}';
+const GROUP_TRAILING_CHARS = '.,;:)';
+const CUT = { text: '#', optional: false };
+const OPENS_VALUE = /^\s*(--|<|\[|\$)/;
+const QUOTED = /^(['"]).*\1$/;
+const NAME = /^[\w.]+$/;
+
+/** The index of the character that closes the bracket group opened at `from`, or -1 when it never closes. */
+function groupEnd(s, from) {
+  const open = s[from];
+  let depth = 0;
+  for (let j = from; j < s.length; j += 1) {
+    if (s[j] === open) depth += 1;
+    else if (s[j] === CLOSERS[open]) {
+      depth -= 1;
+      if (depth === 0) return j;
+    }
+  }
+  return -1;
+}
+
+/** The end of the atom that starts at `start`. */
+function readAtom(s, start) {
+  let i = start;
+  while (i < s.length && !/\s/.test(s[i])) {
+    const c = s[i];
+    if (c in CLOSERS) {
+      const end = groupEnd(s, i);
+      if (end < 0) return s.length;
+      i = end + 1;
+    } else if ((c === '"' || c === "'") && (i === start || s[i - 1] === '=')) {
+      const j = s.indexOf(c, i + 1);
+      i = j < 0 ? i + 1 : j + 1;
+    } else i += 1;
+  }
+  return i;
+}
+
+const stripTrailing = (atom, chars) => trimEndWhile(atom, (c) => chars.includes(c));
+
+/** The maximal run of sentence punctuation at the end of an atom: {index, text}, or null. */
+const trailingRun = (atom) => {
+  let start = atom.length;
+  while (start > 0 && TRAILING_CHARS.includes(atom[start - 1])) start -= 1;
+  return start < atom.length ? { index: start, text: atom.slice(start) } : null;
+};
+
+// ${NAME}, $NAME and ${NAME with an optional closing brace
+const isDollarName = (t) => {
+  if (!t.startsWith('$')) return false;
+  let rest = t.slice(1);
+  if (rest.startsWith('{')) rest = rest.slice(1);
+  if (rest.endsWith('}')) rest = rest.slice(0, -1);
+  return NAME.test(rest);
+};
+
+// an <...> part with at least one character inside
+const hasAnglePart = (t) => {
+  for (let i = t.indexOf('<'); i >= 0; i = t.indexOf('<', i + 1)) {
+    if (t.indexOf('>', i + 1) > i + 1) return true;
+  }
+  return false;
+};
+
+const wrapped = (t, open, close) => t.startsWith(open) && t.endsWith(close) && t.length >= open.length + close.length;
+
+/** A value written as a placeholder: <id>, $VAR, ${VAR}, {x}. */
+export const isPlaceholder = (t) => wrapped(t, '<', '>') || isDollarName(t) || wrapped(t, '${', '}') || wrapped(t, '{', '}')
+  || hasAnglePart(t) || t.includes('${');
+
+/** <a|b>: alternatives written inside angle brackets. */
+export const isAlternation = (t) => {
+  if (!wrapped(t, '<', '>')) return false;
+  const bar = t.indexOf('|', 2);
+  return bar > 0 && bar <= t.length - 3;
+};
+
+const isGroup = (closed) => closed.length > 2 && ((closed.startsWith('[') && closed.endsWith(']')) || (closed.startsWith('(') && closed.endsWith(')')));
+const unquote = (atom) => (atom.length > 1 && QUOTED.test(atom) ? atom.slice(1, -1) : atom);
+
+// {tokens, stop} of a bracket group atom
+function groupTokens(atom, closed) {
+  const body = closed.slice(1, -1);
+  if (atom.startsWith('(') && !OPENS_VALUE.test(body)) return { tokens: [CUT], stop: true };
+  return {
+    tokens: tokenise(body, true).filter((t) => t.text !== '|'),
+    stop: closed !== atom && /[.,;:]/.test(atom.slice(closed.length)),
+  };
+}
+
+// {tokens, stop} of a plain atom
+function plainTokens(atom, optional) {
+  const tail = /^\.{1,3}$/.test(atom) ? null : trailingRun(atom);
+  const trimmed = tail !== null && !isPlaceholder(atom);
+  const bare = trimmed ? atom.slice(0, tail.index) : atom;
+  return { tokens: bare ? [{ text: bare, optional }] : [], stop: trimmed && /[^\]]/.test(tail.text) };
+}
+
+/** The flat tokens {text, optional} of a command tail. */
+export function tokenise(text, optional = false) {
+  const tokens = [];
+  let i = 0;
+  while (i < text.length) {
+    if (/\s/.test(text[i])) {
+      i += 1;
+      continue;
+    }
+    const end = readAtom(text, i);
+    const atom = text.slice(i, end);
+    i = end;
+    const closed = atom.startsWith('[') ? stripTrailing(atom, GROUP_TRAILING_CHARS) : atom;
+    const step = isGroup(closed) ? groupTokens(atom, closed) : plainTokens(unquote(atom), optional);
+    tokens.push(...step.tokens);
+    if (step.stop) break;
+  }
+  return tokens;
+}

package/runtime/scripts/lib/compose-values.mjs

@@ -0,0 +1,11 @@
+import { isPlainObject } from '../../engine/plain-object.mjs';
+
+/** Compose mapping/list entries; callers choose how bare keys and non-string list items are interpreted. */
+export function composeEntries(value, { missingValue = '', stringsOnly = false, isMapping = isPlainObject } = {}) {
+  if (!Array.isArray(value)) return Object.entries(isMapping(value) ? value : {});
+  const entries = stringsOnly ? value.filter(entry => typeof entry === 'string') : value;
+  return entries.map(entry => {
+    const text = String(entry), separator = text.indexOf('=');
+    return separator < 0 ? [text, missingValue] : [text.slice(0, separator), text.slice(separator + 1)];
+  });
+}

package/runtime/scripts/lib/deployment-findings.mjs

@@ -0,0 +1,7 @@
+/** Project issues from available rendered deployments with the caller's finding factory. */
+export function deploymentFindings(deployments, issuesFor, findingFor, defaultFile) {
+  return deployments.filter(entry => !entry.unavailable).flatMap(entry => {
+    const file = entry.file ?? defaultFile;
+    return issuesFor(entry).map(issue => findingFor(issue.code, file, `${file}: ${issue.at}: ${issue.message}`));
+  });
+}

package/runtime/scripts/lib/env.mjs

@@ -11,8 +11,8 @@ export const isSpecRun = (env = process.env) => Boolean(env.NODE_TEST_CONTEXT);
 
 /**
  * The environment for a child that is itself a test runner: `env` without the mark of an enclosing spec run. A `node --test` that inherits NODE_TEST_CONTEXT believes it is a
- * subtest of that run: it reports to its parent and exits 0 whatever its tests did, so a verb that runs specs as a child (starci test affected, the land gate, the release cut, the
- * suite) would pass red specs from inside a test process. The runner marks the spec files it starts itself, so isSpecRun stays true inside them.
+ * subtest of that run: it reports to its parent and exits 0 whatever its tests did, so a verb that runs specs as a child (the package clean-test, the scaffold e2e, the release cut)
+ * would pass red specs from inside a test process. The runner marks the spec files it starts itself, so isSpecRun stays true inside them.
  */
 export function withoutTestRunner(env = process.env) {
   const { NODE_TEST_CONTEXT: _enclosing, ...rest } = env;