@antprofuse/saddle-islands-tools 0.0.0-stage → 0.1.4

package/tools/modules/backend/util.mjs

@@ -0,0 +1,24 @@
+import {spawn} from 'node:child_process';
+import {createServer} from 'node:net';
+import {mkdir,open} from 'node:fs/promises';
+import {resolve,relative} from 'node:path';
+import {setTimeout as sleep} from 'node:timers/promises';
+export {sleep};
+export async function port() {
+  const s=createServer(); await new Promise((yes,no)=>{s.once('error',no);s.listen(0,'127.0.0.1',yes);});
+  const p=s.address().port; await new Promise(r=>s.close(r)); return p;
+}
+export async function processStart(binary,args,dir,env={}) {
+  await mkdir(dir,{recursive:true}); const log=await open(resolve(dir,'process.log'),'a',0o600);
+  const child=spawn(binary,args,{cwd:dir,env:{...process.env,...env},stdio:['ignore',log.fd,log.fd]});
+  const done=new Promise((yes,no)=>{child.once('error',no);child.once('exit',(code,signal)=>yes({code,signal}));});
+  done.catch(()=>{});
+  let closed=false;
+  return {child,done,async stop(){if(closed)return;closed=true;try{if(child.exitCode===null && child.signalCode===null){child.kill('SIGTERM');const cancel=new AbortController();let result;try{result=await Promise.race([done,sleep(12000,null,{signal:cancel.signal}).then(()=>null)]);}finally{cancel.abort();}if(!result){child.kill('SIGKILL');await done;throw Error('process required SIGKILL');}}}finally{await log.close();}}};
+}
+export async function command(binary,args,dir,env={}) {
+  const p=await processStart(binary,args,dir,env); const result=await p.done; await p.stop();
+  if(result.code!==0) throw Error(`command failed: ${binary} exit ${result.code}; see ${dir}/process.log`);
+}
+export async function until(fn,timeout=30000) { const end=Date.now()+timeout;let error;while(Date.now()<end){try{return await fn();}catch(e){error=e;await sleep(100);}}throw error ?? Error('readiness timeout'); }
+export function externalOutput(project,out) { const p=resolve(out);const rel=relative(resolve(project),p);if(rel!=='..'&&!rel.startsWith('../')) throw Error('output must be outside source repository');return p; }

package/tools/modules/minifish/checks/guard.test.mjs

@@ -0,0 +1,13 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {createBoundary} from '../harness/request-guard.mjs';
+import {validateObservationModuleName} from '../compiler/observation-module-name.mjs';
+import {validateObservationModule} from '../compiler/semantic-module-gate.mjs';
+const policy={validate:r=>assert(r.id&&r.request&&r.outcome),validatePlan:()=>{},comparison:(operation,value)=>structuredClone(value),requiresConsumption:r=>!!r.requireConsumption,assertPacketCompletion:e=>assert.deepEqual(e.violations,[])};
+const row=()=>({id:'alternate-request',times:1,request:{operation:'sample.service.read',params:{key:'alternate'}},outcome:{kind:'response',value:{value:1}},requireConsumption:true});
+test('exact request, response delivery and callback consumption remain separate',async()=>{const r=row(),guard=createBoundary([r],policy);assert.deepEqual(await guard.receive(r.request.operation,r.request.params),r.outcome.value);assert.throws(()=>guard.assertComplete());guard.markDelivered(r.request.operation,r.request.params);assert.throws(()=>guard.assertComplete());guard.markConsumed(r.request.operation,r.request.params,{kind:'success'});guard.assertComplete();await guard.close();});
+for(const [name,op,params] of [['wrong operation','other.service',{key:'alternate'}],['missing field','sample.service.read',{}],['extra field','sample.service.read',{key:'alternate',extra:true}],['wrong value','sample.service.read',{key:'wrong'}]])test(name+' stays a durable failure',async()=>{const guard=createBoundary([row()],policy);await assert.rejects(guard.receive(op,params));assert.throws(()=>guard.assertComplete());});
+test('duplicate, absent request, and callback type mismatch are rejected',async()=>{const r=row(),guard=createBoundary([r],policy);assert.throws(()=>guard.assertComplete());await guard.receive(r.request.operation,r.request.params);await assert.rejects(guard.receive(r.request.operation,r.request.params));assert.throws(()=>guard.markConsumed(r.request.operation,r.request.params,{kind:'fail'}));assert.throws(()=>guard.assertComplete());});
+test('explicit alternate observation set replaces region constants without widening AST capability',()=>{validateObservationModuleName('views/alternate.mjs',['views/alternate.mjs']);assert.throws(()=>validateObservationModuleName('regions/T1.mjs',['views/alternate.mjs']));assert.throws(()=>validateObservationModuleName('views/alternate.mjs',undefined));validateObservationModule("import assert from 'node:assert/strict';export const value=1;",['node:assert/strict']);for(const source of ["root.locator('x')","root['evaluate'](fn)","import('./hidden.mjs')","document.querySelector('x')","Function('return document')()","root[method]()","const {locator:read}=root;read('x')","import fs from 'node:fs';"])assert.throws(()=>validateObservationModule(source,['node:assert/strict']));});
+
+test('adapter cannot remove explicit callback consumption or mutate exact counts',async()=>{const r=row(),guard=createBoundary([r],{...policy,validate:v=>{v.times=0;v.requireConsumption=false;},requiresConsumption:()=>false});await guard.receive(r.request.operation,r.request.params);guard.markDelivered(r.request.operation,r.request.params);assert.throws(()=>guard.assertComplete(),/callback/);guard.markConsumed(r.request.operation,r.request.params,{kind:'success'});guard.assertComplete();assert.equal(r.times,1);assert.equal(r.requireConsumption,true);assert.throws(()=>createBoundary([{...r,times:0}],policy),/Positive/);});

package/tools/modules/minifish/checks/package.test.mjs

@@ -0,0 +1,23 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {mkdtemp,mkdir,writeFile,readFile,symlink,rm} from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {loadProject} from '../compiler/config.mjs';
+import {packageRunner} from '../compiler/package-runner.mjs';
+import {compileCase} from '../compiler/case-plan.mjs';
+async function fixture(){
+ const root=await mkdtemp(path.join(os.tmpdir(),'alternate-tool-project-')),project=path.join(root,'alternate'),configFile=path.join(project,'config.json');
+ await mkdir(path.join(project,'harness/regions'),{recursive:true});await mkdir(path.join(project,'definitions'));await mkdir(path.join(project,'harness/plugin'));
+ const config={schemaVersion:1,definitions:'definitions',catalog:'catalog.json',compilerAdapter:'harness/compiler.mjs',adapterRoots:['harness'],observationRoot:'harness',observationModules:['regions/alternate.mjs'],observationImports:['node:assert/strict','@antprofuse/saddle-islands-tools/tools/modules/minifish/harness/semantic-anchor.mjs'],pageRoute:'pages/alternate/view',pluginSource:'harness/plugin',repositoryRoot:'.',runtimeAdapters:{'@minifish/project-runtime':'harness/runtime.mjs','@minifish/project-host':'harness/host.mjs'}};
+ await writeFile(configFile,JSON.stringify(config));
+ await writeFile(path.join(project,'harness/compiler.mjs'),'export function compile(){throw Error("synthetic compile adapter")}');
+ await writeFile(path.join(project,'harness/runtime.mjs'),'export const prepareHeldSnapshot=()=>{},independentBoundary=()=>{},assertNativeState=()=>{},projectAssert=()=>{},locateProject=()=>{},queryBoundaryIds=()=>{},validateReleasedPaymentRows=()=>{};');
+ await writeFile(path.join(project,'harness/host.mjs'),'export const hostPolicy={};');
+ await writeFile(path.join(project,'harness/regions/alternate.mjs'),"import {semanticLocator} from '@antprofuse/saddle-islands-tools/tools/modules/minifish/harness/semantic-anchor.mjs';export function locate(root,name){return semanticLocator(root,name)};export function assertTarget(){}");
+ return {root,project,configFile,config,loaded:await loadProject(project,configFile)};
+}
+test('alternate project static closure records tool/adapter separately and copies no unrelated region',async()=>{const f=await fixture();try{const output=path.join(f.root,'artifact'),records=await packageRunner(f.loaded,output,'regions/alternate.mjs');assert(records.some(r=>r.kind==='tool'&&r.path==='harness/semantic-anchor.mjs'));assert(records.some(r=>r.kind==='adapter'&&r.path==='harness/regions/alternate.mjs'));assert(records.every(r=>/^[a-f0-9]{64}$/.test(r.sha256)));assert(!records.some(r=>r.path.includes('T1')));assert((await readFile(path.join(output,'adapters/harness/regions/alternate.mjs'),'utf8')).includes('../../../tools/harness/semantic-anchor.mjs'));}finally{await rm(f.root,{recursive:true,force:true});}});
+for(const [name,code] of [['unknown package',"import 'fs';"],['dependency traversal',"import '../../outside.mjs';"],['direct DOM',"export const read=root=>root.evaluate(()=>1);"],['dynamic import',"export const read=()=>import('./other.mjs');"]])test(name+' is rejected from the closed observation dependency graph',async()=>{const f=await fixture();try{await writeFile(path.join(f.project,'harness/regions/alternate.mjs'),code);await writeFile(path.join(f.project,'outside.mjs'),'export const leaked=true;');await assert.rejects(packageRunner(f.loaded,path.join(f.root,'artifact'),'regions/alternate.mjs'));}finally{await rm(f.root,{recursive:true,force:true});}});
+test('symlink aliases, undeclared module, missing config, and package output are rejected',async()=>{const f=await fixture();try{const module=path.join(f.project,'harness/regions/alternate.mjs');await rm(module);await writeFile(path.join(f.project,'harness/other.mjs'),'export const safe=true;');await symlink('../other.mjs',module);await assert.rejects(packageRunner(f.loaded,path.join(f.root,'alias'),'regions/alternate.mjs'),/Symlink/);await assert.rejects(packageRunner(f.loaded,path.join(f.root,'unknown'),'regions/unknown.mjs'),/declared module/);await assert.rejects(loadProject(f.project,path.join(f.project,'missing.json')));await assert.rejects(packageRunner(f.loaded,path.join(f.project,'artifact'),'regions/alternate.mjs'),/outside/);}finally{await rm(f.root,{recursive:true,force:true});}});
+test('generic composition preserves exact preparation and original ID mappings without project names',()=>{const noop=()=>{},policy={validateSemanticTargets:noop,supplementalDefinition:()=>null,officialTitle:()=>false,validatePreparationOverrides:noop,validateFixtureTypes:noop,validateSpecialBoundaries:noop,validateIndependentFixture:noop,validatePacketPlan:noop,validatePluginEvents:noop,validatePluginAssertionIdentity:noop,validateObservationModuleName:noop};const catalog={cases:[{id:'alternate / page / value / content',title:'value'}]},definition={caseId:catalog.cases[0].id,ancestors:['open'],basis:[{path:'alternate/source.yaml'}],preparation:{},assertions:[{id:'value',kind:'text',target:'alternate / page / value',expected:'42',count:1}]},fragment={id:'open',inputs:{query:{key:'42'}},boundaries:[],actions:[{kind:'open-page'}]};const plan=compileCase(catalog,definition,[fragment],policy);assert.deepEqual(plan.inputs,fragment.inputs);assert.deepEqual(plan.assertions,definition.assertions);assert.equal(plan.case.id,definition.caseId);assert.throws(()=>compileCase(catalog,{...definition,ancestors:['unknown']},[fragment],policy),/missing preparation/);});

package/tools/modules/minifish/compiler/build-case.mjs

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import {readFile,mkdir,writeFile,realpath} from 'node:fs/promises';
+import {pathToFileURL} from 'node:url';
+import {toolRoot,loadProject,checkOutput} from './config.mjs';
+import {packageRunner} from './package-runner.mjs';
+import {toolIdentity} from './tool-identity.mjs';
+export async function buildCase(file,output,options){
+ const project=await loadProject(options.projectRoot,options.config),root=project.root;
+ const definitionRoot=await realpath(path.resolve(root,project.config.definitions)),source=await realpath(file);
+ assert(source.startsWith(definitionRoot+path.sep),'case must belong to definitions');
+ const fragments=[];
+ for(let dir=path.dirname(source);;dir=path.dirname(dir)){
+  try{fragments.unshift(JSON.parse(await readFile(path.join(dir,'prepare.json'),'utf8')));}catch(error){if(error.code!=='ENOENT')throw error;}
+  if(dir===definitionRoot)break;assert(dir.startsWith(definitionRoot+path.sep),'Preparation escaped definitions');
+ }
+ const definition=JSON.parse(await readFile(source,'utf8'));assert.deepEqual(definition.ancestors,fragments.map(f=>f.id),'declared preparation must match physical ancestry');
+ const catalog=JSON.parse(await readFile(path.resolve(root,project.config.catalog),'utf8'));
+ const adapter=await import(pathToFileURL(await project.resolveAdapter(project.config.compilerAdapter)).href);
+ assert.equal(typeof adapter.compile,'function','Explicit project compiler adapter required');
+ const plan=await adapter.compile({projectRoot:root,config:project.config,catalog,definition,fragments});
+ return buildPlanPackage(plan,output,options);
+}
+export async function buildPlanPackage(plan,output,options){
+ const project=await loadProject(options.projectRoot,options.config),identity=await toolIdentity(project.config.toolSource,project.config.toolSourceManifest?path.resolve(project.root,project.config.toolSourceManifest):undefined),destination=await checkOutput(output,project);await mkdir(destination,{recursive:true});
+ const files=await packageRunner(project,path.join(destination,'runner'),plan.observationModule);
+ const body=`// Generated from project definitions; do not edit.\nimport {test} from '@playwright/test';\nexport const plan = ${JSON.stringify(plan,null,2)};\ntest(plan.case.id,async({page},testInfo)=>{const {runMiniappCase}=await import('./runner/independent-case-runner.mjs');await runMiniappCase({page,plan,testInfo});});\n`;
+ const artifact=path.join(destination,'case.spec.mjs');await writeFile(artifact,body);
+ const lock=JSON.parse(await readFile(path.join(toolRoot,'package-lock.json'),'utf8')),version=lock.packages['node_modules/@playwright/test'].version;
+ const manifest={name:'independent-miniapp-case',private:true,type:'module',scripts:{test:'playwright test --config playwright.config.mjs'},devDependencies:{'@playwright/test':version}};
+ // Keep only the locked Playwright runtime closure, not compiler dependencies.
+ const packages=Object.fromEntries(Object.entries(lock.packages).filter(([name])=>name===''||['node_modules/@playwright/test','node_modules/playwright','node_modules/playwright-core','node_modules/fsevents'].includes(name)));
+ packages['']={name:manifest.name,devDependencies:manifest.devDependencies};
+ await writeFile(path.join(destination,'package.json'),JSON.stringify(manifest,null,2)+'\n');await writeFile(path.join(destination,'package-lock.json'),JSON.stringify({...lock,name:manifest.name,packages},null,2)+'\n');
+ await writeFile(path.join(destination,'playwright.config.mjs'),`import {defineConfig} from '@playwright/test';\nimport os from 'node:os';\nimport path from 'node:path';\nexport default defineConfig({testDir:'.',testMatch:'case.spec.mjs',workers:1,retries:0,timeout:45000,expect:{timeout:10000},outputDir:process.env.MINIFISH_TEST_REPORT_DIR??path.join(os.tmpdir(),'independent-miniapp-case',String(Date.now())),reporter:'list',use:{headless:true,viewport:{width:1400,height:1100},deviceScaleFactor:3,serviceWorkers:'block',screenshot:'off',trace:'off',video:'off'}});\n`);
+ const packageInfo=JSON.parse(await readFile(path.resolve(toolRoot,'../../../package.json'),'utf8'));
+ await writeFile(path.join(destination,'tool-input.json'),JSON.stringify({package:packageInfo.name,version:packageInfo.version,toolIdentity:identity,projectConfig:project.config,files},null,2)+'\n');
+ return {caseId:plan.case.id,artifact};
+}

package/tools/modules/minifish/compiler/case-plan.mjs

@@ -0,0 +1,175 @@
+import assert from 'node:assert/strict';
+import {validateTargetActions} from '../harness/target-actions.mjs';
+function jsonValue(value, path = '$') {
+  assert(value !== undefined, `${path}: undefined is not a fixed input`);
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number') { assert(Number.isFinite(value), `${path}: non-finite number`); return; }
+  assert(typeof value === 'object', `${path}: expected JSON data`);
+  assert(Array.isArray(value) || Object.getPrototypeOf(value) === Object.prototype, `${path}: non-JSON object`);
+  for (const [key, item] of Object.entries(value)) jsonValue(item, `${path}.${key}`);
+}
+
+function unique(items, key, kind) {
+  const seen = new Set();
+  for (const item of items) {
+    assert(typeof item[key] === 'string' && item[key].trim(), `${kind}: missing ${key}`);
+    assert(!seen.has(item[key]), `${kind}: duplicate ${item[key]}`);
+    seen.add(item[key]);
+  }
+}
+
+/** Imports identity and source location only. No generated Islands steps are read. */
+export function importCatalog(input) {
+  assert(Array.isArray(input.cases), 'official cases must be an array');
+  unique(input.cases, 'id', 'official catalog');
+  return { schemaVersion: 1, cases: input.cases.map(item => {
+    assert(item.title && item.formula && item.location, `incomplete catalog entry: ${item.id}`);
+    return { id: item.id, title: item.title, formula: item.formula,
+      category: item.category, domain: item.domain, location: structuredClone(item.location) };
+  }) };
+}
+
+/** Explicitly ordered ancestor fragments, then local preparation; no other case assertions. */
+export function compileCase(catalog, definition, fragments,policy) {
+  assert(policy&&typeof policy.validateSemanticTargets==='function','Explicit project plan policy required');
+  const {validateSemanticTargets,validateIndependentFixture,validatePacketPlan,validatePluginEvents,validatePluginAssertionIdentity,validateObservationModuleName}=policy;
+  jsonValue(definition);
+  validateSemanticTargets(definition);
+  jsonValue(fragments);
+  for(const fragment of fragments)validateSemanticTargets(fragment);
+  const supplementalDefinition=policy.supplementalDefinition(definition);
+  const supplemental=!!supplementalDefinition;
+  const merged = definition.sourceCaseIds !== undefined&&!supplemental;
+  let official, sourceCases;
+  if(supplemental){official=supplementalDefinition;sourceCases=[];}
+  else if (merged) {
+    assert(typeof definition.scope === 'string' && definition.scope.trim(), 'merged case requires a directory scope');
+    assert(typeof definition.caseId === 'string' && (definition.caseId === definition.scope || definition.caseId.startsWith(definition.scope + ' / ')), 'case identity must belong to its directory scope');
+    assert(typeof definition.mergeReason === 'string' && definition.mergeReason.trim(), 'explicit related-scenario merge reason required');
+    assert(Array.isArray(definition.sourceCaseIds) && definition.sourceCaseIds.length > 0, 'source identities required');
+    assert(new Set(definition.sourceCaseIds).size === definition.sourceCaseIds.length, 'duplicate source identity');
+    sourceCases = definition.sourceCaseIds.map(id => {
+      assert(typeof id === 'string' && id.startsWith(definition.scope + ' / '), `source outside directory scope: ${id}`);
+      const entry = catalog.cases.find(item => item.id === id);
+      assert(entry, `unknown official case: ${id}`);
+      return entry;
+    });
+    official = {id: definition.caseId, title: definition.title ?? definition.caseId, scope: definition.scope};
+  } else {
+    official = catalog.cases.find(item => item.id === definition.caseId);
+    assert(official, `unknown official case: ${definition.caseId}`);
+    sourceCases = [official];
+  }
+  const officialTitle=policy.officialTitle(definition,supplemental);
+  assert(Array.isArray(definition.ancestors), 'ancestors must be explicit');
+  unique(fragments, 'id', 'fragment');
+  assert(new Set(definition.ancestors).size === definition.ancestors.length, 'duplicate ancestor');
+  const byId = new Map(fragments.map(fragment => [fragment.id, fragment]));
+  const chain = definition.ancestors.map(id => {
+    assert(byId.has(id), `missing preparation fragment: ${id}`);
+    const fragment = structuredClone(byId.get(id));
+    if (fragment.variants && definition.preparationVariant !== undefined) {
+      assert(typeof definition.preparationVariant === 'string', 'explicit preparationVariant required');
+      const variant = fragment.variants[definition.preparationVariant];
+      assert(variant, `unknown preparationVariant: ${definition.preparationVariant}`);
+      delete fragment.variants;
+      fragment.inputs = {...fragment.inputs, ...variant.inputs};
+      fragment.boundaries = [...(fragment.boundaries ?? []), ...(variant.boundaries ?? [])];
+      fragment.actions = [...(fragment.actions ?? []), ...(variant.actions ?? [])];
+    }
+    return fragment;
+  });
+  chain.push({ id: '$case', ...definition.preparation });
+  const inputs = {}, origins = {}, boundaries = [], actions = [];
+  for (const fragment of chain) {
+    assert(!('assertions' in fragment), `parent assertions are not inherited: ${fragment.id}`);
+    for (const [name, value] of Object.entries(fragment.inputs ?? {})) {
+      assert(!(name in origins), `input conflict ${name}: ${origins[name]} / ${fragment.id}`);
+      inputs[name] = value;
+      origins[name] = fragment.id;
+    }
+    for (const boundary of fragment.boundaries ?? []) {
+      assert(boundary.request && typeof boundary.request === 'object', `missing request: ${boundary.id}`);
+      assert(boundary.outcome && ['response', 'error', 'hold'].includes(boundary.outcome.kind), `missing complete outcome: ${boundary.id}`);
+      assert(Object.hasOwn(boundary.outcome, 'value'), `missing outcome value: ${boundary.id}`);
+      assert(Number.isInteger(boundary.times) && boundary.times > 0, `invalid call count: ${boundary.id}`);
+      boundaries.push({ ...boundary, fragment: fragment.id });
+    }
+    actions.push(...(fragment.actions ?? []));
+  }
+  if(definition.preparationOverrides !== undefined){
+    policy.validatePreparationOverrides(definition);
+    const patch=definition.preparationOverrides;
+    assert(typeof patch.reason==='string' && patch.reason.trim(),'Source-based override reason required');
+    unique(patch.boundaries??[], 'id', 'override boundary');
+    for(const replacement of patch.boundaries??[]){
+      const at=boundaries.findIndex(b=>b.id===replacement.id);assert(at>=0,'Override must name an existing boundary');
+      assert(replacement.request && replacement.outcome && Number.isInteger(replacement.times),'Override requires complete request/outcome pair');
+      boundaries[at]={...replacement,fragment:'$case-override'};
+    }
+    for(const id of patch.omitBoundaryIds??[]){const at=boundaries.findIndex(b=>b.id===id);assert(at>=0,'Omitted boundary must exist');boundaries.splice(at,1);}
+    if(patch.query !== undefined)inputs.query=structuredClone(patch.query);
+    if(patch.actions !== undefined){assert(Array.isArray(patch.actions));actions.splice(0,actions.length,...patch.actions);}
+  }
+  if(supplemental||officialTitle){inputs.hostLanguage=definition.hostSystemPlan.outcome.value.language;origins.hostLanguage='$public-getSystemInfo-language-response';}
+  unique(boundaries, 'id', 'boundary');
+  for(const b of boundaries){assert(Number.isInteger(b.times)&&b.times>0,'Invalid override call count');assert(b.outcome && ['response','hold','error'].includes(b.outcome.kind) && Object.hasOwn(b.outcome,'value'),'Complete override outcome required');}
+  for(const b of boundaries)for(const id of b.after??[])assert(boundaries.some(r=>r.id===id),'Missing boundary dependency');
+  for(const a of actions)if(a.boundaryId)assert(boundaries.some(b=>b.id===a.boundaryId),'Preparation action references omitted boundary');
+  for(const boundary of boundaries)if(boundary.request.params!==undefined)validateIndependentFixture(boundary);
+  const activeDependencies=new Set(),checkedDependencies=new Set();
+  const checkDependencies=id=>{assert(!activeDependencies.has(id),'Cyclic boundary dependency');if(checkedDependencies.has(id))return;activeDependencies.add(id);for(const prior of boundaries.find(b=>b.id===id).after??[])checkDependencies(prior);activeDependencies.delete(id);checkedDependencies.add(id);};
+  for(const boundary of boundaries)checkDependencies(boundary.id);
+  validatePacketPlan(boundaries);
+  for(const a of actions)if(a.kind==='wait-packet-complete'){assert(Array.isArray(a.boundaryIds)&&a.boundaryIds.length,'Packet barrier IDs required');for(const id of a.boundaryIds)assert(boundaries.some(b=>b.id===id),'Unknown packet barrier boundary');}
+  validateTargetActions(definition.beforeTarget,definition.afterTarget,boundaries);
+  for(const a of definition.completion??[])if(a.kind==='wait-boundaries'){
+    assert(Array.isArray(a.boundaryIds)&&a.boundaryIds.length&&new Set(a.boundaryIds).size===a.boundaryIds.length,'Explicit unique completion request batch');
+    for(const id of a.boundaryIds)assert(boundaries.some(b=>b.id===id),'Undeclared completion boundary');
+  }
+  for(const a of definition.assertions??[])if(a.kind==='host-native-ui'){
+    assert(['alert','showLoading','showToast','addToHomeWithGuideDialog'].includes(a.api),'Finite official native UI API');
+    assert(['visible','hidden'].includes(a.state),'Explicit actual host state');
+    assert(['content','state','visual'].includes(a.observation),'Explicit source native responsibility');
+    if(a.state==='visible')assert(boundaries.some(b=>b.id===a.boundaryId&&b.execution==='official-ui'&&b.request.operation==='jsapi:'+a.api),'Visible host UI requires exact official request boundary');
+  }
+
+  policy.validateSpecialBoundaries(definition,official,boundaries);
+  assert(Array.isArray(definition.assertions) && definition.assertions.length, 'case target assertions are required');
+  unique(definition.assertions, 'id', 'assertion');
+  if (merged) {
+    const mapped = new Set();
+    for (const item of [...definition.assertions, ...(definition.completion ?? [])]) {
+      assert(Array.isArray(item.sourceCaseIds) && item.sourceCaseIds.length, `source mapping required: ${item.id ?? item.kind}`);
+      for (const id of item.sourceCaseIds) {
+        assert(definition.sourceCaseIds.includes(id), `undeclared assertion source: ${id}`);
+        mapped.add(id);
+      }
+    }
+    for (const id of definition.sourceCaseIds) assert(mapped.has(id), `source has no assertion mapping: ${id}`);
+  }
+  assert(Array.isArray(definition.basis) && definition.basis.length, 'Spec basis is required');
+  if(definition.assertions.some(a=>a.kind==='region'))assert(definition.observationModule,'region assertion requires observationModule');
+  policy.validateFixtureTypes(definition,boundaries);
+  if (definition.observationModule !== undefined) {
+    validateObservationModuleName(definition.observationModule);
+  }
+  if(definition.plugin){assert(typeof definition.plugin.provider==='string','Declared plugin provider required');validatePluginEvents(definition.plugin.events);}
+  const result = { ...(definition.plugin?{plugin:definition.plugin}:{}), ...(supplemental?{projectSupplemental:definition.projectSupplemental}:{}), ...((supplemental||officialTitle)?{hostSystemPlan:definition.hostSystemPlan}:{}), ...(definition.observationModule ? {observationModule:definition.observationModule} : {}), schemaVersion: 2, case: official, sourceCases,
+    ...(merged ? {mergeReason: definition.mergeReason} : {}), basis: definition.basis, inputs,
+    boundaries, actions, assertions: definition.assertions,
+    beforeTarget: definition.beforeTarget ?? [], afterTarget: definition.afterTarget ?? [],
+    completion: definition.completion ?? [], resources: definition.resources ?? [],
+    provenance: { fragments: chain.map(item => item.id), inputOrigins: origins } };
+  validatePluginAssertionIdentity(result);
+  jsonValue(result);
+  return structuredClone(result);
+}
+
+/** An independent data module. Actual platform execution belongs to the declared runner. */
+export function renderCaseModule(plan,validateSemanticTargets) {
+  assert.equal(typeof validateSemanticTargets,'function','Explicit project source validator required');
+  jsonValue(plan);
+  validateSemanticTargets(plan);
+  return `// Generated from miniapp case definitions. Do not edit.\nexport default ${JSON.stringify(plan, null, 2)};\n`;
+}

package/tools/modules/minifish/compiler/config.mjs

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import {readFile,realpath} from 'node:fs/promises';
+export const toolRoot=path.resolve(import.meta.dirname,'..');
+export async function loadProject(projectRoot,configFile){
+ assert(projectRoot&&configFile,'Explicit project root and config required');
+ const root=await realpath(projectRoot),file=await realpath(configFile);
+ assert(file.startsWith(root+path.sep),'Config must belong to project');
+ const config=JSON.parse(await readFile(file,'utf8'));
+ assert.equal(config.schemaVersion,1,'Supported explicit config required');
+ for(const key of ['definitions','catalog','compilerAdapter','observationRoot','pageRoute','pluginSource','repositoryRoot'])assert(typeof config[key]==='string'&&config[key],'Missing project config: '+key);
+ assert(Array.isArray(config.adapterRoots)&&config.adapterRoots.length,'Explicit adapter roots required');
+ assert(Array.isArray(config.observationModules)&&config.observationModules.length,'Explicit observation modules required');
+ assert(Array.isArray(config.observationImports),'Explicit observation import capabilities required');
+ const adapterRoots=[];
+ for(const relative of config.adapterRoots){const declared=path.resolve(root,relative),actual=await realpath(declared);assert.equal(actual,declared,'Symlink adapter root forbidden');assert(actual.startsWith(root+path.sep),'Adapter root must belong to project');adapterRoots.push(actual);}
+ const resolveAdapter=async relative=>{const declared=path.resolve(root,relative),actual=await realpath(declared);assert.equal(actual,declared,'Symlink adapter dependency forbidden');assert(adapterRoots.some(r=>actual.startsWith(r+path.sep)),'Adapter dependency escaped declared roots');return actual;};
+ assert(config.runtimeAdapters&&typeof config.runtimeAdapters==='object','Explicit runtime adapters required');
+ for(const name of ['@minifish/project-runtime','@minifish/project-host'])await resolveAdapter(config.runtimeAdapters[name]);
+ return {root,config,adapterRoots,resolveAdapter};
+}
+export async function checkOutput(output,project){
+ assert(output,'Explicit output directory required');const destination=path.resolve(output);
+ const repository=await realpath(path.resolve(project.root,project.config.repositoryRoot));
+ for(const forbidden of [repository,path.resolve(toolRoot,'../../..')])assert(destination!==forbidden&&!destination.startsWith(forbidden+path.sep),'Output must be outside source and tool package');
+ // Resolve existing ancestry to reject output symlink escape into either input.
+ let parent=destination;while(true){try{const actual=await realpath(parent);for(const forbidden of [repository,path.resolve(toolRoot,'../../..')])assert(actual!==forbidden&&!actual.startsWith(forbidden+path.sep),'Output symlink enters source/package');break;}catch(error){if(error.code!=='ENOENT')throw error;const next=path.dirname(parent);assert(next!==parent);parent=next;}}
+ return destination;
+}

package/tools/modules/minifish/compiler/observation-module-name.mjs

@@ -0,0 +1,2 @@
+import assert from 'node:assert/strict';
+export function validateObservationModuleName(name,declared){assert(Array.isArray(declared)&&declared.length&&new Set(declared).size===declared.length,'Explicit observation module set required');assert(typeof name==='string'&&declared.includes(name)&&!name.split('/').includes('..')&&!name.startsWith('/'),'observationModule must select a declared module');return name;}

package/tools/modules/minifish/compiler/package-runner.mjs

@@ -0,0 +1,43 @@
+import {SourceTextModule} from 'node:vm';
+import {readFile,mkdir,writeFile,realpath} from 'node:fs/promises';
+import path from 'node:path';
+import assert from 'node:assert/strict';
+import {createHash} from 'node:crypto';
+import ts from 'typescript';
+import {toolRoot,checkOutput} from './config.mjs';
+import {validateObservationModuleName} from './observation-module-name.mjs';
+import {validateObservationModule} from './semantic-module-gate.mjs';
+const publicPrefix='@antprofuse/saddle-islands-tools/tools/modules/minifish/';
+export async function packageRunner(project,output,observation){
+ assert.equal(typeof SourceTextModule,'function','Run compiler with --experimental-vm-modules');
+ const destination=await checkOutput(output,project),actualTool=await realpath(toolRoot),visited=new Map();
+ const ownership=file=>file.startsWith(actualTool+path.sep)?'tool':project.adapterRoots.some(r=>file.startsWith(r+path.sep))?'adapter':null;
+ const target=file=>path.join(destination,ownership(file)==='tool'?'tools':'adapters',path.relative(ownership(file)==='tool'?actualTool:project.root,file));
+ const resolve=async (file,name)=>{
+  if(name.startsWith('node:')||name==='@playwright/test')return null;
+  let declared;
+  if(name.startsWith('.'))declared=path.resolve(path.dirname(file),name);
+  else if(name.startsWith(publicPrefix))declared=path.resolve(actualTool,name.slice(publicPrefix.length));
+  else if(Object.hasOwn(project.config.runtimeAdapters,name))declared=await project.resolveAdapter(project.config.runtimeAdapters[name]);
+  else throw Error('undeclared runner package: '+name);
+  const actual=await realpath(declared);assert.equal(actual,declared,'Symlink runner dependency forbidden');assert(ownership(actual),'runner dependency escaped declared roots');return actual;
+ };
+ const visit=async declared=>{
+  const file=await realpath(declared);assert.equal(file,declared,'Symlink runner dependency forbidden');assert(ownership(file),'runner dependency escaped declared roots');
+  if(visited.has(file))return;const code=await readFile(file,'utf8');visited.set(file,{kind:ownership(file),path:path.relative(ownership(file)==='tool'?actualTool:project.root,file),sha256:createHash('sha256').update(code).digest('hex')});
+  const observationRoot=path.resolve(project.root,project.config.observationRoot,'regions');
+  if(file.startsWith(observationRoot+path.sep))validateObservationModule(code,project.config.observationImports);
+  const parsed=new SourceTextModule(code),dependencies=new Map();
+  for(const name of parsed.dependencySpecifiers){const dependency=await resolve(file,name);if(dependency){dependencies.set(name,dependency);await visit(dependency);}}
+  const ast=ts.createSourceFile(file,code,ts.ScriptTarget.Latest,true,ts.ScriptKind.JS),edits=[];
+  for(const statement of ast.statements){const node=statement.moduleSpecifier;if(node&&dependencies.has(node.text)){let relative=path.relative(path.dirname(target(file)),target(dependencies.get(node.text))).split(path.sep).join('/');if(!relative.startsWith('.'))relative='./'+relative;edits.push({start:node.getStart(ast),end:node.end,text:JSON.stringify(relative)});}}
+  let transformed=code;for(const edit of edits.reverse())transformed=transformed.slice(0,edit.start)+edit.text+transformed.slice(edit.end);
+  visited.get(file).bundledSha256=createHash('sha256').update(transformed).digest('hex');
+  await mkdir(path.dirname(target(file)),{recursive:true});await writeFile(target(file),transformed);
+ };
+ await visit(path.join(actualTool,'harness/independent-case-runner.mjs'));
+ if(observation){validateObservationModuleName(observation,project.config.observationModules);const file=await project.resolveAdapter(path.join(project.config.observationRoot,observation));await visit(file);const bridge=path.join(destination,'tools/harness',observation);await mkdir(path.dirname(bridge),{recursive:true});let relative=path.relative(path.dirname(bridge),target(file)).split(path.sep).join('/');await writeFile(bridge,'export * from '+JSON.stringify(relative.startsWith('.')?relative:'./'+relative)+';\n');}
+ await writeFile(path.join(destination,'independent-case-runner.mjs'),"export * from './tools/harness/independent-case-runner.mjs';\n");
+ const records=[...visited.values()].sort((a,b)=>(a.kind+a.path).localeCompare(b.kind+b.path));
+ await writeFile(path.join(destination,'files.json'),JSON.stringify(records,null,2)+'\n');return records;
+}

package/tools/modules/minifish/compiler/semantic-module-gate.mjs

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import {createRequire}from 'node:module';
+const require=createRequire(import.meta.url);
+const ts=require('typescript');assert.equal(ts.version,'5.9.3','Locked author-time parser version');
+const forbidden=new Set(['locator','evaluate','evaluateAll','getAttribute','getByText','getByRole','getByTestId','querySelector','querySelectorAll','or']);
+export function validateObservationModule(source,approvedImports){
+ assert(Array.isArray(approvedImports),'Explicit observation import policy required');const approved=new Set(approvedImports);
+ const ast=ts.createSourceFile('observation.mjs',source,ts.ScriptTarget.Latest,true,ts.ScriptKind.JS);
+ assert.equal(ast.parseDiagnostics.length,0,'Invalid business module');
+ const walk=node=>{
+  if(ts.isImportDeclaration(node)||ts.isExportDeclaration(node)&&node.moduleSpecifier)assert(approved.has(node.moduleSpecifier.text),'Undeclared observation dependency');
+  if(ts.isCallExpression(node)){
+   assert(node.expression.kind!==ts.SyntaxKind.ImportKeyword,'Dynamic observation import forbidden');
+   if(ts.isElementAccessExpression(node.expression))assert(ts.isStringLiteral(node.expression.argumentExpression),'Dynamic method execution forbidden');
+  }
+  if(ts.isPropertyAccessExpression(node))assert(!forbidden.has(node.name.text),'Direct DOM observation forbidden');
+  if(ts.isElementAccessExpression(node)&&ts.isStringLiteral(node.argumentExpression))assert(!forbidden.has(node.argumentExpression.text),'Computed DOM observation forbidden');
+  if(ts.isIdentifier(node)){
+   assert(!['document','window','globalThis','Function','eval'].includes(node.text),'Ambient DOM execution forbidden');
+   if(ts.isBindingElement(node)&&node.name)assert(!forbidden.has(node.name.text),'Destructured DOM capability forbidden');
+  }
+  if(ts.isBindingElement(node))assert(!forbidden.has(node.propertyName?.text??node.name.text),'Destructured DOM capability forbidden');
+  ts.forEachChild(node,walk);
+ };walk(ast);return true;
+}

package/tools/modules/minifish/compiler/tool-identity.mjs

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import {readFile,realpath} from 'node:fs/promises';
+import {createHash} from 'node:crypto';
+import {verifyIdentity} from '../../../core/package-identity.mjs';
+export {verifyIdentity};
+const packageRoot=path.resolve(import.meta.dirname,'../../../..');
+const sha=bytes=>createHash('sha256').update(bytes).digest('hex');
+export async function toolIdentity(expected,manifestFile=process.env.MINIFISH_TOOL_SOURCE_LOCK){
+ let identity=expected,manifestSha256;
+ if(manifestFile){const file=await realpath(manifestFile);assert(file!==packageRoot&&!file.startsWith(packageRoot+path.sep),'Trust manifest must be outside tool package');const bytes=await readFile(file);identity=JSON.parse(bytes);manifestSha256=sha(bytes);if(expected)for(const key of ['repository','commit','packagePath','version'])assert.equal(identity[key],expected[key],'Fixed tool source mismatch: '+key);}
+ assert(identity?.files,'Trusted complete external file manifest required');await verifyIdentity(packageRoot,identity);
+ return {package:identity.package,version:identity.version,repository:identity.repository,commit:identity.commit,packagePath:identity.packagePath,kind:'verified-content',manifestSha256,sourceFilesSha256:sha(JSON.stringify(identity.files)),sourceFiles:Object.keys(identity.files).length};
+}

package/tools/modules/minifish/harness/batch_cases.py

@@ -0,0 +1,91 @@
+"""Exact standalone case identities and immutable inputs for batch runners."""
+import hashlib
+import json
+from pathlib import Path
+
+
+def read_cases(file):
+    file = Path(file).resolve()
+    rows = json.loads(file.read_text())
+    if not isinstance(rows, list) or not rows:
+        raise ValueError("Batch manifest must be a nonempty array")
+    seen, paths, result = set(), set(), []
+    for row in rows:
+        if not isinstance(row, dict) or set(row) != {"id", "package"}:
+            raise ValueError("Each row requires exactly id and package")
+        ident = row["id"]
+        if not isinstance(row["package"], str) or not row["package"]:
+            raise ValueError("Case package must be a nonempty path string")
+        package = (file.parent / row["package"]).resolve()
+        if not isinstance(ident, str) or not ident or ident in seen or package in paths:
+            raise ValueError("Case identities and package paths must be unique")
+        for name in ("case.spec.mjs", "playwright.config.mjs", "package.json", "package-lock.json", "node_modules/.bin/playwright"):
+            if not (package / name).is_file():
+                raise ValueError(f"Incomplete independent package: {package / name}")
+        seen.add(ident); paths.add(package)
+        result.append({"id": ident, "package": str(package)})
+    return result
+
+
+def fingerprint(rows):
+    result = {}
+    for row in rows:
+        p = Path(row["package"])
+        files = [p / n for n in ("case.spec.mjs", "playwright.config.mjs", "package.json", "package-lock.json")]
+        files += sorted(f for f in (p / "runner").rglob("*") if f.is_file())
+        result[row["id"]] = {str(f.relative_to(p)): hashlib.sha256(f.read_bytes()).hexdigest() for f in files}
+    return result
+
+
+def save(file, data):
+    file = Path(file)
+    temp = file.with_suffix(file.suffix + ".tmp")
+    temp.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n")
+    temp.replace(file)
+
+
+def read_result(file, expected_type):
+    try:
+        value = json.loads(Path(file).read_text())
+        if not isinstance(value, expected_type):
+            raise ValueError("unexpected result shape")
+        return value
+    except (OSError, ValueError):
+        return None
+
+
+def worker_certified(received, lifecycle, network, expected_ids, exit_code):
+    if not isinstance(received, list) or not isinstance(lifecycle, dict) or not isinstance(network, dict):
+        return False
+    if any(not isinstance(row, dict) for row in received):
+        return False
+    if [row.get("id") for row in received] != expected_ids:
+        return False
+    if any(row.get("status") not in ("passed", "failed", "artifact-only") for row in received):
+        return False
+    ordinary_failure = any(row["status"] == "failed" for row in received)
+    if exit_code != int(ordinary_failure) or lifecycle.get("inputsVerified") is not True:
+        return False
+    cleanup = network.get("namespaceCleanup")
+    if not isinstance(cleanup, dict) or cleanup.get("remaining") != []:
+        return False
+    for report in (lifecycle, network):
+        children = report.get("children")
+        if not isinstance(children, list) or not children:
+            return False
+        if any(not isinstance(child, dict) or child.get("returncode") is None for child in children):
+            return False
+    return True
+
+
+def product_fingerprint(root):
+    """Match the runner's copied product inputs, excluding generated runtime trees."""
+    root = Path(root)
+    result = {}
+    for file in sorted(root.rglob('*')):
+        relative = file.relative_to(root)
+        if any(part in ('node_modules', '.git', '.mini-ide') or part.startswith('dist-') for part in relative.parts):
+            continue
+        if file.is_file():
+            result[str(relative)] = hashlib.sha256(file.read_bytes()).hexdigest()
+    return result

package/tools/modules/minifish/harness/batch_plugin_groups.py

@@ -0,0 +1,56 @@
+"""Partition a unified batch by exact preflighted plugin artifact identity."""
+import json
+from pathlib import Path
+from plugin_artifact import validate_plugin_artifact
+
+
+def plugin_groups(rows, workers, mapping_file=None, default_artifact=None, *, source):
+    mapping = json.loads(Path(mapping_file).read_text()) if mapping_file else {}
+    if not isinstance(mapping, dict) or set(mapping) - {r['id'] for r in rows}:
+        raise ValueError('Plugin mapping contains unknown case identities')
+    artifacts, manifests, errors = {}, {}, []
+    for row in rows:
+        ident = row['id']
+        try:
+            plan = read_compiled_plan(row['package'])
+            value = mapping.get(ident, default_artifact)
+            if ident in mapping and (not isinstance(value, str) or not value):
+                raise ValueError('Plugin mapping requires exact artifact paths')
+            artifact = Path(value).resolve() if value else None
+            if artifact and artifact not in manifests:
+                manifests[artifact] = validate_plugin_artifact(artifact, source)
+            plugin = plan.get('plugin')
+            if plugin is not None:
+                if not isinstance(plugin, dict) or not isinstance(plugin.get('events'), dict):
+                    raise ValueError('Invalid compiled case plugin plan')
+                if artifact is None:
+                    raise ValueError('Explicit compiled plugin artifact required; use --plugin-artifact-map or --plugin-artifacts')
+                # Same exact plan contract as independent-case-runner, before any worker starts.
+                if json.dumps(manifests[artifact]['plan'], sort_keys=True) != json.dumps(plugin['events'], sort_keys=True):
+                    raise ValueError('Case plugin plan must match compiled artifact')
+            artifacts[ident] = str(artifact) if artifact else None
+        except (OSError, ValueError, KeyError, TypeError) as error:
+            errors.append(f"{ident}: {error}")
+    if errors:
+        raise ValueError('Plugin preflight failed before worker startup:\n' + '\n'.join(errors))
+    groups = {}
+    for row in rows:
+        groups.setdefault(artifacts[row['id']], []).append(row)
+    shards = []
+    for artifact, group in groups.items():
+        count = min(len(group), max(1, round(workers * len(group) / len(rows))))
+        shards.extend((group[i::count], artifact) for i in range(count))
+    return shards
+
+
+def read_compiled_plan(package):
+    """Read the compiler's JSON literal without importing/executing the test module."""
+    text = (Path(package) / 'case.spec.mjs').read_text()
+    marker = '\nexport const plan = '
+    if text.count(marker) != 1:
+        raise ValueError('Rebuild case package: expected one compiler-generated plan')
+    body = text.split(marker, 1)[1]
+    plan, end = json.JSONDecoder().raw_decode(body)
+    if not isinstance(plan, dict) or not body[end:].startswith(';\ntest(plan.case.id,'):
+        raise ValueError('Rebuild case package: invalid compiler-generated plan literal')
+    return plan