kangshifu-board/test/unified-workshop-upgrade.test.mjs

import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import crypto from 'node:crypto';
import {fileURLToPath} from 'node:url';
import {planUpgrade,publicPlan,applyUpgrade,verifyUpgrade,rollbackUpgrade} from '../scripts/upgrade-unified-workshop-skill.mjs';

const root=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..');
const hash=b=>crypto.createHash('sha256').update(b).digest('hex');
const digest=p=>hash(fs.readFileSync(p));
function fileMap(dir){const out={};for(const e of fs.readdirSync(dir,{withFileTypes:true})){const p=path.join(dir,e.name);if(e.isDirectory())for(const[n,h]of Object.entries(fileMap(p)))out[e.name+'/'+n]=h;else out[e.name]=digest(p);}return out;}
function sealPackage(packageDir){fs.writeFileSync(path.join(packageDir,'FILES.sha256'),Object.entries(fileMap(packageDir)).filter(([n])=>n!=='FILES.sha256').map(([n,h])=>h+'  '+n+'\n').join(''));}
function fixture(t,{received83=false,stale=true}={}){
 const dir=fs.mkdtempSync(path.join(os.tmpdir(),'ksf-unified-upgrade-test-'));
 t.after(()=>{const abs=fs.realpathSync(dir);assert.ok(abs.startsWith(fs.realpathSync(os.tmpdir())+path.sep)&&path.basename(abs).startsWith('ksf-unified-upgrade-test-'));fs.rmSync(abs,{recursive:true});});
 const dataRoot=path.join(dir,'data'),targetDir=path.join(dataRoot,'skills/ksf-workshop-runtime'),libraryDir=path.join(dataRoot,'skills/ksf-voc-library'),packageDir=path.join(dir,'package');
 fs.mkdirSync(path.dirname(targetDir),{recursive:true});
 const received=path.join(root,'docs/workshop-skill-review-20261108/received-15ffc90f');
 fs.cpSync(path.join(received,'ksf-workshop-runtime'),targetDir,{recursive:true});
 fs.cpSync(path.join(root,'skills/ksf-voc-library'),libraryDir,{recursive:true});
 // The working tree has pending library documentation edits. Construct a self-consistent
 // synthetic installation here; this is never a repair of the real library or its manifest.
 fs.writeFileSync(path.join(libraryDir,'FILES.sha256'),Object.entries(fileMap(libraryDir)).filter(([n])=>n!=='FILES.sha256').map(([n,h])=>h+'  '+n+'\n').join(''));
 let legacyManifestPolicy;
 if(received83){
  // Exact received SKILL bytes; the other 18 members are isolated synthetic fixture bytes.
  // Freeze the historical 19-member layout; later migration scripts are outside this fixture.
  for(const name of ['scripts/review_correction.py','scripts/unified_store.py'])fs.rmSync(path.join(libraryDir,name),{force:true});
  const incoming=path.join(root,'docs/workshop-skill-release-20261108-r2/received-library-2773fc95');
  fs.copyFileSync(path.join(incoming,'ksf-voc-library-SKILL.md'),path.join(libraryDir,'SKILL.md'));
  const old='b4266efed78c19c0162aa2200cf0be83b0e7afa2473cef134459eb14c97ce69c';
  const members=Object.entries(fileMap(libraryDir)).filter(([n])=>n!=='FILES.sha256');
  assert.equal(members.length,19);
  fs.writeFileSync(path.join(libraryDir,'FILES.sha256'),members.map(([n,h])=>(n==='SKILL.md'&&stale?old:h)+'  '+n+'\n').join(''));
  const runtimeNames=['query_voc.py','library_channel.py','voc_db.py','retrieval.py'];
  legacyManifestPolicy={entryNames:members.map(([n])=>n),verifiedRuntimeEntries:Object.fromEntries(runtimeNames.map(n=>['scripts/'+n,digest(path.join(libraryDir,'scripts',n))])),knownStaleSkill:{actualSha256:digest(path.join(libraryDir,'SKILL.md')),declaredSha256:old,evidenceSha256:digest(path.join(incoming,'ksf-voc-library-current-20261108-v1.zip'))}};
 }
 fs.mkdirSync(packageDir);fs.cpSync(path.join(root,'skills/ksf-workshop-runtime'),path.join(packageDir,'skill'),{recursive:true});
 fs.copyFileSync(path.join(root,'scripts/upgrade-unified-workshop-skill.mjs'),path.join(packageDir,'upgrade-skill.mjs'));
 const exportReceipt=JSON.parse(fs.readFileSync(path.join(received,'EXPORT.json')));
 const baseline=Object.fromEntries(exportReceipt.files.map(e=>[e.path,e.sha256]));
 const candidate=Object.fromEntries(fs.readFileSync(path.join(packageDir,'skill/FILES.sha256'),'utf8').trim().split(/\r?\n/).map(l=>{const[h,n]=l.split('  ');return[n,h];}));
 candidate['FILES.sha256']=digest(path.join(packageDir,'skill/FILES.sha256'));
 fs.writeFileSync(path.join(packageDir,'release.json'),JSON.stringify({schema:'ksf.unified-workshop-release.v1',releaseId:'ksf-unified-test',baseline,candidate,legacySkillSha256:digest(path.join(libraryDir,'SKILL.md')),...(legacyManifestPolicy?{legacyManifestPolicy}:{})}));
 sealPackage(packageDir);
 fs.writeFileSync(path.join(targetDir,'credential-binding.json'),'{"fixtureOnly":true}',{mode:0o600});
 fs.writeFileSync(path.join(targetDir,'private-fixture-envelope.json'),'{"syntheticFixture":true}',{mode:0o600});
 fs.mkdirSync(path.join(dataRoot,'ksf-workshop-state/agents'),{recursive:true});
 fs.writeFileSync(path.join(dataRoot,'ksf-workshop-state/agents/offline-fixture.json'),'{"fixtureOnly":true}');
 return{dir,dataRoot,targetDir,libraryDir,packageDir,before:fileMap(dataRoot)};
}
function unchanged(f){assert.deepEqual(fileMap(f.dataRoot),f.before);}

test('dry does not create backups, write files or retire either existing entry',t=>{
 const f=fixture(t),p=planUpgrade(f);assert.equal(p.ok,true);assert.equal(p.readOnly,true);assert.equal(p.alreadyApplied,false);
 assert.equal(p.runtimeFilesModified,0);assert.ok(p.changes.length>20);assert.ok(p.changes.some(e=>e.remove));unchanged(f);
});
test('apply, verify, repeat apply, rollback preserve runtimes, binding, envelope and identity state',t=>{
 const f=fixture(t),r=applyUpgrade(f);assert.equal(r.ok,true);assert.ok(!fs.existsSync(path.join(f.libraryDir,'SKILL.md')));
 assert.ok(!fs.readFileSync(path.join(f.libraryDir,'FILES.sha256'),'utf8').includes('  SKILL.md'));
 assert.equal(verifyUpgrade({backup:r.backup}).runtimeAndBindingPreserved,true);
 assert.equal(applyUpgrade(f).alreadyApplied,true);
 assert.equal(fs.readdirSync(f.dataRoot).filter(n=>n.startsWith('ksf-workshop-unified-backup-')).length,1);
 const rolled=rollbackUpgrade({backup:r.backup});assert.equal(rolled.legacyEntrypointRestored,true);
 const restored=fileMap(f.dataRoot);for(const[n,h]of Object.entries(f.before))assert.equal(restored[n],h,n);
 for(const n of Object.keys(restored).filter(n=>!n.startsWith('ksf-workshop-unified-backup-')))assert.ok(Object.hasOwn(f.before,n),n);
 assert.equal(rollbackUpgrade({backup:r.backup}).alreadyRolledBack,true);
});
test('a corrupted package is rejected before touching the installation',t=>{
 const f=fixture(t);fs.appendFileSync(path.join(f.packageDir,'skill/SKILL.md'),'tampered');
 assert.throws(()=>applyUpgrade(f),{code:'PACKAGE_HASH_MISMATCH'});unchanged(f);
});
test('unknown current workshop entry is rejected with zero writes',t=>{
 const f=fixture(t);fs.appendFileSync(path.join(f.targetDir,'SKILL.md'),'another upgrade');const before=fileMap(f.dataRoot);
 assert.throws(()=>applyUpgrade(f),{code:'UNKNOWN_TARGET_SKILL'});assert.deepEqual(fileMap(f.dataRoot),before);
});
test('changed installed executable is never overwritten',t=>{
 const f=fixture(t);fs.appendFileSync(path.join(f.targetDir,'scripts/ksf-secure.mjs'),'\n// unknown');const before=fileMap(f.dataRoot);
 assert.throws(()=>applyUpgrade(f),{code:'RUNTIME_BASELINE_MISMATCH'});assert.deepEqual(fileMap(f.dataRoot),before);
});
test('an unknown file at a newly introduced reference path is preserved and blocks upgrade',t=>{
 const f=fixture(t);fs.writeFileSync(path.join(f.targetDir,'references/workshop-category-scan.md'),'another author');const before=fileMap(f.dataRoot);
 assert.throws(()=>applyUpgrade(f),{code:'UNEXPECTED_EXISTING_FILE'});assert.deepEqual(fileMap(f.dataRoot),before);
});
test('unknown library Skill entry is not retired',t=>{
 const f=fixture(t);fs.appendFileSync(path.join(f.libraryDir,'SKILL.md'),'new library entry');const before=fileMap(f.dataRoot);
 assert.throws(()=>applyUpgrade(f),{code:'UNKNOWN_LEGACY_SKILL'});assert.deepEqual(fileMap(f.dataRoot),before);
});
test('an inconsistent library runtime manifest blocks upgrade',t=>{
 const f=fixture(t);fs.appendFileSync(path.join(f.libraryDir,'scripts/query_voc.py'),'\n# another version');const before=fileMap(f.dataRoot);
 assert.throws(()=>applyUpgrade(f),{code:'RESEARCH_MANIFEST_MISMATCH'});assert.deepEqual(fileMap(f.dataRoot),before);
});
test('injected mid-apply failure restores original bytes and both entry states',t=>{
 const f=fixture(t);let error;
 try{applyUpgrade(f,{afterMutation:i=>{if(i===5)throw Object.assign(Error('injected'),{code:'INJECTED_FAILURE'});}});}catch(e){error=e;}
 assert.equal(error.recoveryStatus,'FAILED_RESTORED');
 const restored=fileMap(f.dataRoot);for(const[n,h]of Object.entries(f.before))assert.equal(restored[n],h,n);
 assert.equal(fs.existsSync(path.join(f.targetDir,'references/research-library/operations.md')),false);
});
test('concurrent edits block rollback before any files are restored',t=>{
 const f=fixture(t),r=applyUpgrade(f);const changed=path.join(f.targetDir,'references/workshop-category-scan.md');fs.appendFileSync(changed,'\nconcurrent edit');
 const before=fileMap(f.dataRoot);assert.throws(()=>rollbackUpgrade({backup:r.backup}),{code:'CONCURRENT_FILE_CHANGE'});assert.deepEqual(fileMap(f.dataRoot),before);
});
test('corrupt backup is rejected before rollback mutates anything',t=>{
 const f=fixture(t),r=applyUpgrade(f);const j=JSON.parse(fs.readFileSync(path.join(r.backup,'journal.json')));const row=j.rows.find(e=>e.backupFile);
 fs.appendFileSync(path.join(r.backup,row.backupFile),'corrupt');const before=fileMap(f.dataRoot);
 assert.throws(()=>rollbackUpgrade({backup:r.backup}),{code:'BACKUP_HASH_MISMATCH'});assert.deepEqual(fileMap(f.dataRoot),before);
});
test('a package modified during apply is rejected and earlier writes are restored',t=>{
 const f=fixture(t);let error;
 try{applyUpgrade(f,{afterMutation:i=>{if(i===0)fs.appendFileSync(path.join(f.packageDir,'skill/references/research-library/operations.md'),'changed during installation');}});}catch(e){error=e;}
 assert.equal(error.code,'PACKAGE_CHANGED_DURING_APPLY');assert.equal(error.recoveryStatus,'FAILED_RESTORED');
 const after=fileMap(f.dataRoot);for(const[n,h]of Object.entries(f.before))assert.equal(after[n],h,n);
});
test('directory links are rejected before writing into their targets',t=>{
 const f=fixture(t),real=path.join(f.dir,'saved-references');fs.renameSync(path.join(f.targetDir,'references'),real);
 try{fs.symlinkSync(real,path.join(f.targetDir,'references'),process.platform==='win32'?'junction':'dir');}catch(e){if(['EPERM','EACCES'].includes(e.code)){t.skip('symlinks unavailable');return;}throw e;}
 assert.throws(()=>applyUpgrade(f),{code:'SYMLINK_PATH'});assert.ok(fs.lstatSync(path.join(f.targetDir,'references')).isSymbolicLink());
});

test('received 83-line entry with the exact stale declaration passes dry without repairing it',t=>{
 const f=fixture(t,{received83:true}),p=planUpgrade(f),r=publicPlan(p);
 assert.equal(r.readOnly,true);assert.equal(r.legacyManifestState,'KNOWN_STALE_SKILL_DECLARATION');
 assert.equal(r.legacyManifestMismatches.length,1);
 assert.equal(r.legacyManifestMismatches[0].actualSha256,'2773fc95fd98fa2367390c72ac5de20435c4a6458cfea45e2b847657af56630a');
 assert.equal(r.legacyManifestMismatches[0].declaredSha256,'b4266efed78c19c0162aa2200cf0be83b0e7afa2473cef134459eb14c97ce69c');
 assert.equal(r.runtimeFilesModified,0);unchanged(f);
});

test('the same 83-line entry with a self-consistent manifest also passes dry',t=>{
 const f=fixture(t,{received83:true,stale:false}),r=publicPlan(planUpgrade(f));
 assert.equal(r.legacyManifestState,'CONSISTENT');assert.deepEqual(r.legacyManifestMismatches,[]);unchanged(f);
});

test('apply then rollback restores received 83-line bytes and the original stale manifest exactly',t=>{
 const f=fixture(t,{received83:true}),entry=fs.readFileSync(path.join(f.libraryDir,'SKILL.md')),manifest=fs.readFileSync(path.join(f.libraryDir,'FILES.sha256'));
 const r=applyUpgrade(f);assert.equal(verifyUpgrade({backup:r.backup}).ok,true);assert.equal(applyUpgrade(f).alreadyApplied,true);
 rollbackUpgrade({backup:r.backup});
 assert.deepEqual(fs.readFileSync(path.join(f.libraryDir,'SKILL.md')),entry);
 assert.deepEqual(fs.readFileSync(path.join(f.libraryDir,'FILES.sha256')),manifest);
 for(const[n,h]of Object.entries(f.before))assert.equal(fileMap(f.dataRoot)[n],h,n);
});

test('a stale declaration is rejected without the explicit evidence-bound policy',t=>{
 const f=fixture(t,{received83:true}),p=path.join(f.packageDir,'release.json'),r=JSON.parse(fs.readFileSync(p));delete r.legacyManifestPolicy;
 fs.writeFileSync(p,JSON.stringify(r));sealPackage(f.packageDir);
 assert.throws(()=>planUpgrade(f),{code:'UNKNOWN_LEGACY_SKILL'});unchanged(f);
});

test('a different unknown manifest declaration is not covered by the stale exception',t=>{
 const f=fixture(t,{received83:true}),p=path.join(f.libraryDir,'FILES.sha256');fs.writeFileSync(p,fs.readFileSync(p,'utf8').replace('b4266efed78c19c0162aa2200cf0be83b0e7afa2473cef134459eb14c97ce69c','0'.repeat(64)));
 const before=fileMap(f.dataRoot);assert.throws(()=>planUpgrade(f),{code:'UNKNOWN_LEGACY_SKILL'});assert.deepEqual(fileMap(f.dataRoot),before);
});

test('unknown edits to the received entry, another member or manifest layout remain blocking',t=>{
 for(const scenario of ['skill','reference','layout']){
  const f=fixture(t,{received83:true});
  if(scenario==='skill')fs.appendFileSync(path.join(f.libraryDir,'SKILL.md'),'\nunknown');
  if(scenario==='reference')fs.appendFileSync(path.join(f.libraryDir,'references/query-rules.md'),'\nunknown');
  if(scenario==='layout'){const p=path.join(f.libraryDir,'FILES.sha256');fs.writeFileSync(p,fs.readFileSync(p,'utf8').split('\n').filter(l=>!l.endsWith('  references/query-rules.md')).join('\n'));}
  const before=fileMap(f.dataRoot),code=scenario==='skill'?'UNKNOWN_LEGACY_SKILL':scenario==='reference'?'RESEARCH_MANIFEST_MISMATCH':'RESEARCH_MANIFEST_LAYOUT_MISMATCH';
  assert.throws(()=>planUpgrade(f),{code});assert.deepEqual(fileMap(f.dataRoot),before);
 }
});

test('rewriting a verified runtime and its manifest together cannot bypass the pinned baseline',t=>{
 const f=fixture(t,{received83:true}),p=path.join(f.libraryDir,'scripts/query_voc.py');fs.appendFileSync(p,'\n# unknown executable');
 const m=path.join(f.libraryDir,'FILES.sha256');fs.writeFileSync(m,fs.readFileSync(m,'utf8').replace(/^([a-f0-9]{64})(  scripts\/query_voc.py)$/m,()=>digest(p)+'  scripts/query_voc.py'));
 const before=fileMap(f.dataRoot);assert.throws(()=>planUpgrade(f),{code:'RESEARCH_BASELINE_MISMATCH'});assert.deepEqual(fileMap(f.dataRoot),before);
});