@antprofuse/saddle-islands-tools 0.1.9 → 0.1.13

package/tools/modules/minifish/compiler/compile-check.mjs

@@ -1,3 +1,6 @@
+import {validateComponentStates} from '../harness/component-state.mjs';
+import {loadComponentContract} from './component-contract.mjs';
+import {assertionComponents,compareCoverage} from './anchor-coverage.mjs';
 import assert from 'node:assert/strict';
 import path from 'node:path';
 import {readFile,realpath,mkdir,writeFile} from 'node:fs/promises';
@@ -37,6 +40,11 @@ export async function compileCheck(options){
  const manifest=await readTracked(options.manifest),catalog=await readTracked(path.resolve(root,config.catalog));
  const parsedManifest=JSON.parse(manifest.bytes),parsedCatalog=JSON.parse(catalog.bytes);
  const rows=activeCases(parsedManifest,parsedCatalog);
+ const componentContract=await loadComponentContract(project);
+ assert.equal(componentContract.head,head,'Component contract candidate mismatch');
+ const inventory=componentContract.inventory;
+ const registry={'anchors.jsonc':componentContract.registry.active,'anchors-retired.jsonc':componentContract.registry.retired};
+ const sourceComponentIds=componentContract.activeComponentIds;
  const adapter=await import(pathToFileURL(await project.resolveAdapter(config.compilerAdapter)).href);
  const definitionRoot=await realpath(path.resolve(root,config.definitions)),results=[];
  for(const row of rows){
@@ -49,13 +57,18 @@ export async function compileCheck(options){
     if(dir===definitionRoot)break;assert(dir.startsWith(definitionRoot+path.sep),'Preparation escaped root');
    }
    assert.deepEqual(definition.ancestors,fragments.map(f=>f.id),'Preparation ancestry mismatch');
-   await adapter.compile({projectRoot:root,config,catalog:parsedCatalog,definition,fragments});
-   results.push({id:row.definition,definition:row.definition,status:'passed'});
+   const plan=await adapter.compile({projectRoot:root,config,catalog:parsedCatalog,definition,fragments});
+   assert(plan.componentContract===undefined,'Project must not override compiler component contract');
+   validateComponentStates(plan,componentContract);
+   const componentIds=assertionComponents(plan);
+   results.push({id:row.definition,definition:row.definition,status:'passed',componentIds});
   }catch(e){results.push({id:row.definition,definition:row.definition,status:'failed',error:e.message});}
  }
  git('diff','--exit-code','HEAD','--');assert.equal(git('rev-parse','HEAD'),head,'Candidate changed during compilation');
- const result={schemaVersion:1,kind:'minifish-full-compile',head,projectPath,projectTree:git('rev-parse',head+':'+projectPath),
+ const anchorCoverage=compareCoverage(sourceComponentIds,results.filter(r=>r.status==='passed'));
+ const result={schemaVersion:2,kind:'minifish-full-compile',head,projectPath,projectTree:git('rev-parse',head+':'+projectPath),
   manifest:{path:manifest.relative,sha256:sha(manifest.bytes)},catalog:{path:catalog.relative,sha256:sha(catalog.bytes)},
+  anchorInventory:inventory,anchorCoverage,registry,componentContract,
   toolIdentity:await toolIdentity(config.toolSource,path.resolve(root,config.toolSourceManifest)),
   total:results.length,passed:results.filter(r=>r.status==='passed').length,failed:results.filter(r=>r.status==='failed').length,
   nonExecutable:(parsedManifest.pending??[]).map(r=>({id:r.sourceCaseId,reason:r.reason})),

package/tools/modules/minifish/compiler/component-contract.mjs

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import {readFile,realpath} from 'node:fs/promises';
+import {execFileSync} from 'node:child_process';
+import {createHash} from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+const sha=bytes=>createHash('sha256').update(bytes).digest('hex');
+
+export async function loadComponentContract(project){
+ const {root,config}=project;
+ const repo=await realpath(path.resolve(root,config.repositoryRoot));
+ const git=(...args)=>execFileSync('git',['-C',repo,...args],{encoding:'utf8'}).trim();
+ const head=git('rev-parse','HEAD'),relative=path.relative(repo,root).split(path.sep).join('/');
+ assert(relative&&!relative.startsWith('../')&&relative.endsWith('/code/minifish-tests'),'Business test directory required');
+ const source=config.anchorInventory;
+ assert(source?.path&&/^[a-f0-9]{64}$/.test(source.sha256??''),'Frozen anchor inventory required');
+ const read=async file=>{
+  assert.equal(await realpath(file),file,'Symlink component input forbidden');
+  const name=path.relative(repo,file).split(path.sep).join('/');
+  assert(git('ls-tree',head,'--',name).startsWith('100644 '),'Committed regular component input required');
+  assert(!git('status','--porcelain','--untracked-files=all','--',name),'Component input must be clean');
+  const bytes=execFileSync('git',['-C',repo,'show',head+':'+name]);
+  assert.equal(sha(await readFile(file)),sha(bytes),'Component input differs from candidate');
+  return {path:name,sha256:sha(bytes),bytes};
+ };
+ assert(project.configFile&&project.configFile.startsWith(root+path.sep),'Explicit project config required');
+ const configInput=await read(project.configFile);
+ assert.deepEqual(JSON.parse(configInput.bytes),config,'Project config changed during compilation');
+ const sourcePath=path.resolve(root,source.path);assert(sourcePath.startsWith(root+path.sep),'Inventory escaped project');
+ const inventory=await read(sourcePath);assert.equal(inventory.sha256,source.sha256,'Inventory digest mismatch');
+ const registry=path.resolve(root,'../.registry');
+ const active=await read(path.join(registry,'anchors.jsonc')),retired=await read(path.join(registry,'anchors-retired.jsonc'));
+ const {activeComponentIds,componentStates,branches}=JSON.parse(execFileSync('python3',[fileURLToPath(new URL('../component_index_bridge.py',import.meta.url))],{input:JSON.stringify({inventory:JSON.parse(inventory.bytes),active:active.bytes.toString(),retired:retired.bytes.toString(),withStates:true}),encoding:'utf8',env:{...process.env,PYTHONDONTWRITEBYTECODE:'1'}}));
+ assert.equal(git('rev-parse','HEAD'),head,'Candidate changed during contract construction');
+ const binding=x=>({path:x.path,sha256:x.sha256});
+ return {schemaVersion:1,head,activeComponentIds,componentStates,branches,config:binding(configInput),inventory:binding(inventory),registry:{active:binding(active),retired:binding(retired)}};
+}

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

@@ -17,7 +17,7 @@ export async function loadProject(projectRoot,configFile){
  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};
+ return {root,config,configFile:file,adapterRoots,resolveAdapter};
 }
 export async function checkOutput(output,project){
  assert(output,'Explicit output directory required');const destination=path.resolve(output);

package/tools/modules/minifish/component_index.py

@@ -0,0 +1,192 @@
+"""Stable allocated references. Mapping changes never imply business decisions."""
+import hashlib
+import json
+import re
+import secrets
+
+
+def fingerprint(value):
+    return hashlib.sha256(json.dumps(value,ensure_ascii=False,sort_keys=True,separators=(',',':')).encode()).hexdigest()
+
+
+def source_ids(inventory):
+    if inventory.get('schemaVersion')!=2 or inventory.get('identityContract')!='islands-point-id':
+        raise ValueError('Official inventory required')
+    if not re.fullmatch('[a-f0-9]{64}',inventory.get('source',{}).get('manifestSha256','')):
+        raise ValueError('Frozen source identity required')
+    seen=set(); components=set()
+    for row in inventory.get('targets',[]):
+        key=row.get('id')
+        if not isinstance(key,str) or not key.startswith('视图:') or key!=row.get('target') or key in seen:
+            raise ValueError('Invalid or duplicate source identity')
+        seen.add(key)
+        if row.get('kind')=='component': components.add(key)
+    if not components: raise ValueError('Empty component inventory')
+    return components
+
+
+def validate(index, inventory=None, retired=None):
+    if not isinstance(index,dict): raise ValueError('Active index must be an object')
+    def valid(key): return isinstance(key,str) and re.fullmatch('cmp_[a-f0-9]{6}',key)
+    if any(not valid(k) or not isinstance(v,str) or not v.startswith('视图:') for k,v in index.items()):
+        raise ValueError('Invalid component mapping')
+    if len(set(index.values()))!=len(index): raise ValueError('Duplicate source mapping')
+    if retired is not None:
+        if not isinstance(retired,list) or any(not valid(k) for k in retired) or len(set(retired))!=len(retired):
+            raise ValueError('Invalid retired ID list')
+        if set(index)&set(retired): raise ValueError('Active and retired IDs overlap')
+    if inventory is not None and set(index.values())!=source_ids(inventory):
+        raise ValueError('Incomplete component mapping')
+    return dict(index)
+
+
+def reconcile(inventory, previous=None, remap=None, retire=(), token=None, retired=None):
+    """Return active map and retired IDs. Never infer business identity changes."""
+    expected=source_ids(inventory); token=token or (lambda:secrets.token_hex(3))
+    previous={} if previous is None else previous
+    retired=[] if retired is None else retired
+    active=validate(previous,retired=retired)
+    remap={} if remap is None else remap
+    if not isinstance(remap,dict): raise ValueError('Remap object required')
+    if not isinstance(retire,(list,tuple)) or len(set(retire))!=len(retire): raise ValueError('Invalid retire list')
+    removing=set(retire)
+    if (set(remap)|removing)-active.keys(): raise ValueError('Only active references can change')
+    if set(remap)&removing: raise ValueError('Cannot remap and retire same reference')
+    for key,destination in remap.items():
+        if destination not in expected: raise ValueError('Unknown remap destination')
+        active[key]=destination
+    for key in removing: del active[key]
+    validate(active)
+    if set(active.values())-expected: raise ValueError('Removed source requires explicit remap or retirement')
+    reserved=set(retired)|removing
+    used=set(previous)|reserved
+    new_sources=[r['id'] for r in inventory['targets'] if r.get('kind')=='component' and r['id'] not in set(active.values())]
+    for source in new_sources:
+        for _ in range(1024):
+            key='cmp_'+token()
+            if not re.fullmatch('cmp_[a-f0-9]{6}',key): raise ValueError('Invalid random allocation')
+            if key not in used: break
+        else: raise ValueError('Collision retry limit reached')
+        used.add(key);active[key]=source
+    result=active; history=list(retired)+list(retire)
+    validate(result,inventory,history)
+    return result,history
+
+
+def difference(inventory, previous):
+    current=source_ids(inventory)
+    active=validate(previous) if previous else {}
+    old=set(active.values())
+    return {'addedSourceIds':sorted(current-old),'removedSourceIds':sorted(old-current),
+            'unchangedSourceIds':sorted(current&old)}
+
+
+
+def registry_text(value):
+    """One active mapping or retired ID per line; deterministic Git-friendly JSON."""
+    if isinstance(value,dict):
+        validate(value)
+    elif isinstance(value,list):
+        validate({},retired=value)
+    else: raise ValueError('Registry object or retired list required')
+    dump=lambda x:json.dumps(x,ensure_ascii=False)
+    if isinstance(value,dict):
+        lines=['  '+dump(k)+': '+dump(v)+',' for k,v in value.items()]
+        return '{\n'+'\n'.join(lines)+('\n' if lines else '')+'\n}\n'
+    lines=['  '+dump(k)+',' for k in value]
+    return '[\n'+'\n'.join(lines)+('\n' if lines else '')+'\n]\n'
+
+
+
+def parse_registry(text):
+    """Read the canonical one-entry-per-line JSONC registry subset, no comments."""
+    lines=text.splitlines()
+    if len(lines)<3 or (lines[0],lines[-1]) not in (('{','}'),('[',']')):
+        raise ValueError('Invalid registry JSONC framing')
+    obj=lines[0]=='{'; result={} if obj else []
+    for line in lines[1:-1]:
+        if not line.strip(): continue
+        if not line.endswith(','): raise ValueError('Registry entries require trailing comma')
+        raw=line[:-1]
+        if obj:
+            def unique(pairs):
+                result={}
+                for key,value in pairs:
+                    if key in result: raise ValueError('Duplicate allocated ID')
+                    result[key]=value
+                return result
+            row=json.loads('{'+raw+'}',object_pairs_hook=unique)
+            if len(row)!=1: raise ValueError('Exactly one mapping per line required')
+            key=next(iter(row))
+            if key in result: raise ValueError('Duplicate allocated ID')
+            result.update(row)
+        else: result.append(json.loads(raw))
+    if text!=registry_text(result): raise ValueError('Noncanonical registry formatting')
+    return result
+
+
+def main(argv, identity):
+    import argparse
+    from pathlib import Path
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('operation',choices=['reconcile','verify','diff','resolve'])
+    parser.add_argument('--inventory',type=Path,required=True)
+    parser.add_argument('--inventory-sha256',required=True)
+    parser.add_argument('--index',type=Path)
+    parser.add_argument('--index-sha256')
+    parser.add_argument('--retired',type=Path)
+    parser.add_argument('--retired-sha256')
+    parser.add_argument('--changes',type=Path)
+    parser.add_argument('--source-id')
+    parser.add_argument('--output',type=Path)
+    args=parser.parse_args(argv)
+    def read(path,sha,registry=False):
+        raw=path.read_bytes()
+        if hashlib.sha256(raw).hexdigest()!=sha: raise ValueError('Input hash mismatch: '+str(path))
+        return parse_registry(raw.decode()) if registry else json.loads(raw)
+    inventory=read(args.inventory,args.inventory_sha256)
+    if bool(args.index)!=bool(args.index_sha256): raise ValueError('Index path and hash required together')
+    previous=read(args.index,args.index_sha256,True) if args.index else None
+    if bool(args.retired)!=bool(args.retired_sha256): raise ValueError('Retired path and hash required together')
+    if bool(args.index)!=bool(args.retired): raise ValueError('Existing registry requires both files')
+    retired=read(args.retired,args.retired_sha256,True) if args.retired else []
+    if previous is not None:
+        validate(previous,retired=retired)
+        for file,value in [(args.index,previous),(args.retired,retired)]:
+            if file.read_bytes()!=registry_text(value).encode('utf-8'):
+                raise ValueError('Noncanonical registry formatting: '+str(file))
+    if args.operation=='resolve':
+        if previous is None or not args.source_id or args.changes or args.output:
+            raise ValueError('Resolve requires registry and exact source ID, no changes/output')
+        validate(previous,inventory,retired)
+        reverse={value:key for key,value in previous.items()}
+        if args.source_id in reverse:
+            result={'component':reverse[args.source_id],'sourceId':args.source_id,'observed':False}
+        else:
+            from tools.adapters.islands.component_reference import resolve_branch
+            result=resolve_branch(inventory,previous,retired,args.source_id)
+        print(json.dumps(result,ensure_ascii=False))
+        return 0
+    if args.source_id is not None:
+        raise ValueError('Source ID is only accepted by resolve')
+    if args.operation=='verify':
+        if previous is None or args.changes or args.output: raise ValueError('Verify requires index, no changes or output')
+        print(json.dumps({'passed':True,'activeComponents':len(validate(previous,inventory,retired))}))
+        return 0
+    if args.operation=='diff':
+        if args.changes or args.output: raise ValueError('Diff does not accept changes or output')
+        print(json.dumps(difference(inventory,previous),ensure_ascii=False))
+        return 0
+    if not args.output: raise ValueError('New output path required')
+    changes=json.loads(args.changes.read_text()) if args.changes else {}
+    if not isinstance(changes,dict) or set(changes)-{'remap','retire'}: raise ValueError('Unknown change fields')
+    result,history=reconcile(inventory,previous,changes.get('remap'),changes.get('retire',[]),retired=retired)
+    # A new staging directory prevents partially overwriting the live pair.
+    # Consumers accept both files in one Git commit after verification.
+    args.output.mkdir(parents=True,exist_ok=False)
+    for name,value in [('anchors.jsonc',result),('anchors-retired.jsonc',history)]:
+        with (args.output/name).open('x') as stream:
+            stream.write(registry_text(value))
+    print(json.dumps({'output':str(args.output),'activeComponents':len(result),
+                      'toolCommit':identity['commit']},ensure_ascii=False))
+    return 0

package/tools/modules/minifish/component_index_bridge.py

@@ -0,0 +1,28 @@
+"""Internal Node compiler bridge to the single registry parser/validator."""
+import json
+from pathlib import Path
+import sys
+sys.dont_write_bytecode = True
+sys.path.insert(0,str(Path(__file__).resolve().parents[3]))
+from tools.modules.minifish.component_index import parse_registry,validate
+
+if __name__=='__main__':
+    request=json.load(sys.stdin)
+    active=parse_registry(request['active'])
+    retired=parse_registry(request['retired'])
+    validate(active,request['inventory'],retired)
+    if request.get('withStates'):
+        from tools.adapters.islands.component_reference import resolve_branch
+        states={}
+        branches={}
+        for row in request['inventory']['targets']:
+            if row.get('kind')!='branch':
+                continue
+            resolved=resolve_branch(request['inventory'],active,retired,row['id'])
+            branches[row['id']]=resolved
+            values=states.setdefault(resolved['component'],[])
+            if resolved['state'] not in values:
+                values.append(resolved['state'])
+        print(json.dumps({'activeComponentIds':list(active),'componentStates':states,'branches':branches}))
+    else:
+        print(json.dumps(list(active)))

package/tools/modules/minifish/harness/browser.mjs

@@ -1,3 +1,4 @@
+import {adaptOfficialBridgeDispatch} from './official-bridge-dispatch.mjs';
 import {installHostDeviceFixtureEvidence} from './host-device-fixture.mjs';
 import {nativeUiResultPath} from './native-ui-contract.mjs';
 import {observeLocalNavigationCandidate,localNavigationEvidence,delegateLocalNavigation,assertLocalNavigationComplete} from './local-navigation-evidence.mjs';
@@ -9,7 +10,7 @@ import {pluginPackagePlan} from './plugin-package.mjs';
 import {installHostLanguage} from './host-language.mjs';
 import {installResponseConsumption} from './response-consumption.mjs';
 import { fulfillRpc } from './rpc-wire.mjs';
-import { bridgePath, jsapiPath, jsapiDeliveryPath, acknowledgeJsapiDelivery, bridgeScript, fulfillJsapi, businessJsapiOption } from './jsapi.mjs';
+import { bridgePath, jsapiPath, jsapiDeliveryPath, acknowledgeJsapiDelivery, bridgeScript, managedMockApis, fulfillJsapi, businessJsapiOption } from './jsapi.mjs';
 
 // Official Lyra keeps earlier pages painted in the same simulator stack.
 // The last non-exiting sibling is the active shell; route name alone is ambiguous.
@@ -42,7 +43,7 @@ export async function openMinifish({ page, plan, query, simulatorUrl, pageRoute,
   const hostDeviceEvidence=await installHostDeviceFixtureEvidence(page);
   const loadingObservation=await installLoadingObservation(page);
   await prepareIPhone16ProDevice(page,url);
-  const faults = [], blocked = [], materials = [];
+  const faults = [], blocked = [], materials = [], bridgeDispatchAdapters = [];
   const officialUi=[...new Set(plan.evidence().expectations.filter(r=>r.execution==='official-ui').map(r=>r.request.operation.slice(6)))];
   const pluginPlan=plugin?pluginPackagePlan({appAddress:url.searchParams.get('appAddress'),appId:url.searchParams.get('appId'),...plugin}):null;
   const pluginEvents=plugin?.events?pluginEventLedger(plugin.events,validatePluginEvents):null;
@@ -53,6 +54,14 @@ export async function openMinifish({ page, plan, query, simulatorUrl, pageRoute,
   const handler = async (route) => {
     const request = route.request(), target = new URL(request.url());
     try {
+      if(target.origin===url.origin&&target.pathname==='/lyra/runtime.bundle.js'){
+        assert.equal(request.method(),'GET');
+        const response=await route.fetch();
+        assert(response.ok(),'Official bridge runtime fetch failed');
+        const adapted=adaptOfficialBridgeDispatch(await response.text(),{managed:managedMockApis(nativeApis),officialUi});
+        bridgeDispatchAdapters.push(adapted.evidence);
+        return await route.fulfill({response,body:adapted.body});
+      }
       if (target.origin === url.origin && target.pathname === bridgePath) return await route.fulfill({contentType:'application/javascript',body:bridgeScript(url.origin,nativeApis,Boolean(process.env.MINIFISH_LOADING_DIAGNOSTICS_DIR),officialUi,process.env.MINIFISH_CALLBACK_CORRELATION==='1')});
       if(target.origin===url.origin&&target.pathname===jsapiDeliveryPath)return await acknowledgeJsapiDelivery(route,plan);
       if (target.origin === url.origin && target.pathname === jsapiPath) {const wire=request.postDataJSON();callbackCorrelation?.transport(wire,request.frame());observeLocalNavigationCandidate(page,wire);if(officialUi.includes(wire.api)){plan.recordNativeUiRequest('jsapi:'+wire.api,businessJsapiOption(wire.option),wire);return await route.fulfill({status:204});}if(delegateLocalNavigation(page,wire))return await route.fulfill({status:204});return await fulfillJsapi(route, plan);}
@@ -115,6 +124,7 @@ export async function openMinifish({ page, plan, query, simulatorUrl, pageRoute,
     capturePayGuide:(stage)=>guideDiagnostic?.capture(stage),
     flushPayGuide:()=>guideDiagnostic?.flush(),
     assertComplete() {
+      assert(bridgeDispatchAdapters.length>0,'Official bridge compatibility adapter was not observed');
       assertLocalNavigationComplete(page,plan.evidence(),queryExpectations);
       assert.deepEqual(faults, [], 'Network violations remain failures even when caught by product');
       plan.assertComplete();
@@ -123,8 +133,9 @@ export async function openMinifish({ page, plan, query, simulatorUrl, pageRoute,
       if(requireHostLanguage)host.assertObserved();
       if(hostSystemPlan)host.assertSystemPlan(hostSystemPlan);
     },
-    evidence() { return { ...plan.evidence(), hostDeviceFixture:hostDeviceEvidence.evidence(), callbackCorrelation:callbackCorrelation?.evidence()??[], payGuideDiagnostics:guideDiagnostic?.evidence()??[], hostLanguage:host.evidence(), localNavigation:localNavigationEvidence(page), networkViolations: [...faults], blocked: [...blocked], materials: [...materials], plugin:pluginPlan?.evidence()??null, pluginEvents:pluginEvents?.evidence()??null }; },
+    evidence() { return { ...plan.evidence(), bridgeDispatchAdapters:[...bridgeDispatchAdapters], hostDeviceFixture:hostDeviceEvidence.evidence(), callbackCorrelation:callbackCorrelation?.evidence()??[], payGuideDiagnostics:guideDiagnostic?.evidence()??[], hostLanguage:host.evidence(), localNavigation:localNavigationEvidence(page), networkViolations: [...faults], blocked: [...blocked], materials: [...materials], plugin:pluginPlan?.evidence()??null, pluginEvents:pluginEvents?.evidence()??null }; },
     assertArtifactComplete(skipped){
+      assert(bridgeDispatchAdapters.length>0,'Official bridge compatibility adapter was not observed');
       assertLocalNavigationComplete(page,plan.evidence(),queryExpectations);
       assert.deepEqual(faults, [], 'Artifact network violations remain failures');
       const audit=plan.assertArtifactComplete(skipped);

package/tools/modules/minifish/harness/component-membership.mjs

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+
+// Serialized into the business frame or invoked inside the single held snapshot.
+// Dataset is authoritative during AppX updates; synchronized DOM may lag.
+export function sampleDeclaredComponents(root){
+ const declarations=[];
+ for(const node of root.ownerDocument.querySelectorAll('*')){
+  const native=Object.prototype.hasOwnProperty.call(node,'$$dataset');
+  const data=node.$$dataset;
+  const declared=native?!!data&&Object.prototype.hasOwnProperty.call(data,'anchorId'):node.hasAttribute('data-anchor-id');
+  if(!declared)continue;
+  const value=native?data.anchorId:node.getAttribute('data-anchor-id');
+  declarations.push({id:typeof value==='string'?value:null,valid:typeof value==='string'&&value.length>0});
+ }
+ return {declarations};
+}
+
+export function validateComponentMembership(snapshot,active){
+ assert(Array.isArray(active)&&active.length>0,'Frozen active component set required');
+ assert(active.every(x=>typeof x==='string'&&/^cmp_[a-f0-9]{6}$/.test(x)),'Invalid active component ID');
+ const allowed=new Set(active);assert.equal(allowed.size,active.length,'Duplicate active component ID');
+ assert(snapshot&&Array.isArray(snapshot.declarations),'Component membership snapshot required');
+ const unknown=new Set();
+ for(const row of snapshot.declarations){
+  assert(row&&row.valid===true&&typeof row.id==='string'&&row.id.length>0,'Invalid declared component identity');
+  if(!allowed.has(row.id))unknown.add(row.id);
+ }
+ assert.equal(unknown.size,0,'Unexpected component declarations: '+JSON.stringify([...unknown]));
+ return {check:'declared-components-are-active',count:snapshot.declarations.length,
+  observedComponentIds:[...new Set(snapshot.declarations.map(x=>x.id))],
+  limitation:'Unannotated nodes and incorrect reuse of a valid component ID are not proven absent'};
+}

package/tools/modules/minifish/harness/component-state.mjs

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+
+// Serialized independently; the product declaration is observed, never inferred
+// from the expected branch or treated as proof of its content/style obligations.
+export function sampleComponentState(node){
+ const native=Object.prototype.hasOwnProperty.call(node,'$$dataset');
+ const value=native?node.$$dataset?.anchorState:node.getAttribute('data-anchor-state');
+ return {value:typeof value==='string'?value:null,valid:typeof value==='string'&&value.length>0};
+}
+export function assertComponentState(actual,expected){
+ assert(typeof expected==='string'&&expected.length>0,'Nonempty source component state required');
+ assert(actual?.valid===true,'Component state declaration missing or invalid');
+ assert.equal(actual.value,expected,'Observed component state differs from source expectation');
+ return {expected,actual:actual.value};
+}
+export function validateComponentStates(plan,contract){
+ const active=new Set(contract?.activeComponentIds??[]);
+ const reference=ref=>{if(ref?.target!==undefined)assert(active.has(ref.target),'Reference must belong to the frozen active component set');};
+ for(const actions of [plan.actions,plan.beforeTarget,plan.afterTarget,plan.completion])for(const action of actions??[])reference(action);
+ for(const a of plan.assertions??[]){
+  reference(a);
+  for(const ref of [...(a.spatial?.absent??[]),...(a.spatial?.order??[]).flatMap(pair=>[pair.above,pair.below])])reference(ref);
+  if(a.kind==='component-state')assert(a.componentState!==undefined,'Branch state required');
+  if(a.componentState===undefined)continue;
+  assert(typeof a.componentState==='string'&&a.componentState.length>0,'Nonempty componentState required');
+  assert(/^cmp_[a-f0-9]{6}$/.test(a.target??''),'Component state requires a component target');
+  assert(contract.componentStates?.[a.target]?.includes(a.componentState),'Component state must belong to its frozen source component');
+  if(a.kind==='component-state')assert(typeof a.present==='boolean','Branch presence requires an explicit boolean');
+  else assert(a.present===undefined,'present is only accepted for component-state');
+  assert(a.kind!=='hidden'&&a.count!==0,'State observation requires an existing component');
+ }
+}
+
+export function assertComponentBranch(snapshot,expected,present,allowed){
+ assert(typeof present==='boolean','Explicit branch presence required');
+ assert(Array.isArray(allowed)&&allowed.includes(expected),'Frozen component states required');
+ assert(snapshot&&Number.isInteger(snapshot.count)&&snapshot.count>=0&&snapshot.count<=1,'Unique component owner required');
+ assert(Array.isArray(snapshot.members)&&snapshot.members.length===snapshot.count,'Complete branch observation required');
+ for(const member of snapshot.members){assert(member.componentState?.valid===true,'Component state declaration missing or invalid');assert(allowed.includes(member.componentState.value),'Observed component state absent from frozen source');}
+ const observed=snapshot.members.some(member=>member.componentState.value===expected&&member.visible===true);
+ assert.equal(observed,present,'Observed branch presence differs from source expectation');
+ return {expected,present,observed,members:snapshot.members};
+}

package/tools/modules/minifish/harness/held-snapshot.mjs

@@ -1,3 +1,8 @@
+import {spatialTarget} from './spatial-contract.mjs';
+import {resolveVisualCarrier} from './visual-carrier.mjs';
+import {sampleComponentState,assertComponentState,assertComponentBranch} from './component-state.mjs';
+import {sampleDeclaredComponents,validateComponentMembership} from './component-membership.mjs';
+import {validateFrozenSpatial} from './held-spatial.mjs';
 import {assertVisualMetrics} from './visual-expectation.mjs';
 import assert from 'node:assert/strict';
 import {sampleNativeMetrics,sampleNativeTextVisibility,sampleNativeStyle,sampleNativePressed,sampleHeldNativeState} from './native-dom-sampling.mjs';
@@ -32,10 +37,10 @@ export async function captureHeldSnapshot(root,spec){
   const timeline=root.ownerDocument.defaultView.__seeleHeldTimelineV1;if(!timeline)throw Error('Held timeline must be installed before pressing');
   const now=()=>performance.timeOrigin+performance.now();const start=timeline.events.find(e=>e.type==='touchstart')??timeline.events.find(e=>e.type==='mousedown');if(!start)throw Error('No actual native down event');
   let groups;while(true){const elements=[...root.ownerDocument.querySelectorAll('*')];groups=spec.targets.map(target=>({target,nodes:elements.filter(node=>{const id=identity(node);return matches(id,target.target,target.instance);})}));
-   if(groups.every(g=>g.nodes.length)||now()-start.time>=350)break;
+   if(groups.every(g=>g.target.waitForPresence===false||g.nodes.length)||now()-start.time>=350)break;
    await new Promise(resolve=>{const timer=setTimeout(resolve,Math.max(0,350-(now()-start.time)));requestAnimationFrame(()=>{clearTimeout(timer);resolve();});});
   }
-  const captureStartedAt=now();const result={version:spec.version,captureStartedAt,pressAt:start.time,timedOut:groups.some(g=>!g.nodes.length),groups:groups.map(g=>({key:g.target.key,target:g.target.target,instance:g.target.instance,count:g.nodes.length,members:g.nodes.map(node=>{const m=metrics(node);m.frameId=spec.frameId;for(const p of [...m.imagePaints,...m.imagePaintInventory])p.frameId=spec.frameId;m.text=node.textContent.trim();m.styles={...m.styles,...style(node,{keys:g.target.styleKeys})};return {identity:identity(node),state:state(node),active:pressed(node),metrics:m,textPaint:paint(node)};})})),eventsAtSnapshot:timeline.events.slice()};result.snapshotAt=now();return result;
+  const captureStartedAt=now();const membership=spec.componentContract?(${sampleDeclaredComponents.toString()})(root):undefined;const result={version:spec.version,...(membership?{componentMembership:membership}:{}),captureStartedAt,pressAt:start.time,timedOut:groups.some(g=>g.target.waitForPresence!==false&&!g.nodes.length),groups:groups.map(g=>({key:g.target.key,target:g.target.target,instance:g.target.instance,count:g.nodes.length,members:g.nodes.map(node=>{const selected=(${resolveVisualCarrier.toString()})(node,g.target.carrier??'semantic-root');const m=metrics(selected);m.frameId=spec.frameId;for(const p of [...m.imagePaints,...m.imagePaintInventory])p.frameId=spec.frameId;m.text=node.textContent.trim();m.styles={...m.styles,...style(node,{keys:g.target.styleKeys})};return {identity:identity(node),componentState:(${sampleComponentState.toString()})(node),state:state(node),active:pressed(node),metrics:m,textPaint:paint(node)};})})),eventsAtSnapshot:timeline.events.slice()};result.snapshotAt=now();return result;
  }`;
  return freezeHeldSnapshot(await root.locator(':root').evaluate(Function('return ('+body+')')(),spec));
 }
@@ -47,23 +52,35 @@ export function validateHeldInputTiming(snapshot,events){
  assert(snapshot&&!snapshot.timedOut&&snapshot.pressAt===down.time&&snapshot.snapshotAt>=down.time&&snapshot.snapshotAt<=up.time,'Only actual held-time snapshot allowed');
  assert(!events.some(e=>['touchcancel','pointercancel','scroll'].includes(e.type)),'Native held input cancelled or scrolled');return {eligible:true,holdMs:duration,pressAt:down.time,snapshotAt:snapshot.snapshotAt,releaseAt:up.time,events};
 }
-export function validateFrozenHeldAssertion(snapshot,a,validators){
+export function validateFrozenHeldAssertion(snapshot,a,validators,contract){
  const group=snapshot.groups.find(g=>g.key===heldSnapshotTargetKey(a.target,a.instance));assert(group,'Original semantic snapshot required');
+ if(a.kind==='component-state')return assertComponentBranch({count:group.count,members:group.members.map(m=>({componentState:m.componentState,visible:m.state.visible}))},a.componentState,a.present,contract?.componentStates?.[a.target]);
  validators.validateState({count:group.count,visible:group.members.map(m=>m.state.visible)},a);
  const observations=[];
  for(const member of group.members){assert(matchesNativeSemanticIdentity(member.identity,a.target,a.instance),'Original semantic identity and optional instance must match');// Preserve measured :active; declared assertions do not require CSS :active.
 
+  if(a.componentState!==undefined)assertComponentState(member.componentState,a.componentState);
   if(a.enabled)assert.equal(member.state.enabled,true,'Original native enabled obligation');validators.validateObservation(member.metrics,a);
-  if(a.kind==='region'&&a.check==='visual'){assert(!a.visual.carrier||a.visual.carrier==='semantic-root','Held visual carrier not captured');assertVisualMetrics(member.metrics,a.visual);}
+  if(a.kind==='region'&&a.check==='visual'){
+   let visualMetrics=member.metrics;
+   if(a.visual.carrier==='exclusive-parent'){
+    const key=spatialTarget({target:a.target,instance:a.instance,carrier:'exclusive-parent'}).key;
+    const carrier=snapshot.groups.find(g=>g.key===key);assert(carrier?.count===1&&carrier.members.length===1,'Unique frozen visual carrier required');
+    visualMetrics=carrier.members[0].metrics;
+   }else assert(!a.visual.carrier||a.visual.carrier==='semantic-root','Held visual carrier not captured');
+   assertVisualMetrics(visualMetrics,a.visual);
+  }
   if(a.textFits)validateNativeTextVisibility(member.textPaint,{selfOverflow:'contain'});observations.push({...member.metrics,...(a.textFits?{textPaint:member.textPaint}:{})});
  }
- return {count:group.count,visible:group.members.map(m=>m.state.visible),observations,snapshotVersion:snapshot.version,snapshotAt:snapshot.snapshotAt};
+ const spatial=a.spatial?validateFrozenSpatial(snapshot,a.spatial):undefined;
+ return {...(spatial?{spatial}:{}),count:group.count,visible:group.members.map(m=>m.state.visible),observations,snapshotVersion:snapshot.version,snapshotAt:snapshot.snapshotAt};
 }
 // The release happens in finally before any Node validator or boundary wait.
 export async function executeHeldSnapshot({root,spec,release,validators,capture=captureHeldSnapshot,readEvents=readReleasedTimeline}){
  let snapshot,error,releaseReceipt;try{snapshot=await capture(root,spec);}catch(e){error=e;}finally{releaseReceipt=await release(spec.release);}
  const events=await readEvents(root);let timing;
  try{if(error)throw error;timing=validateHeldInputTiming(snapshot,events);}catch(e){return {snapshot,releaseReceipt,timing:{eligible:false,reason:e.message,events},assertions:spec.assertions.map(a=>({id:a.id,sourceCaseIds:a.sourceCaseIds,status:'invalidated',error:e.message})),observations:{}};}
- const assertions=[],observations={};for(const a of spec.assertions){try{observations[a.id]=validateFrozenHeldAssertion(snapshot,a,validators);assertions.push({id:a.id,sourceCaseIds:a.sourceCaseIds,status:'passed'});}catch(e){assertions.push({id:a.id,sourceCaseIds:a.sourceCaseIds,status:'failed',error:e.message});}}
+ let membership,membershipError;try{if(spec.componentContract)membership=validateComponentMembership(snapshot.componentMembership,spec.componentContract.activeComponentIds);}catch(e){membershipError=e;}
+ const assertions=[],observations={};if(membership)observations.componentMembership=membership;for(const a of spec.assertions){try{if(membershipError)throw membershipError;observations[a.id]=validateFrozenHeldAssertion(snapshot,a,validators,spec.componentContract);assertions.push({id:a.id,sourceCaseIds:a.sourceCaseIds,status:'passed'});}catch(e){assertions.push({id:a.id,sourceCaseIds:a.sourceCaseIds,status:'failed',error:e.message});}}
  return {snapshot,releaseReceipt,timing,assertions,observations};
 }

package/tools/modules/minifish/harness/held-spatial.mjs

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict';
+import {validateRegionOrder} from './region-order.mjs';
+import {validateSpatial,spatialTarget as target} from './spatial-contract.mjs';
+export {validateSpatial} from './spatial-contract.mjs';
+export function prepareHeldWithSpatial(plan,prepareProject){
+ const clean=structuredClone(plan);
+ for(const a of clean.assertions){if(a.spatial!==undefined)validateSpatial(a.spatial);delete a.spatial;delete a.componentState;}
+ const result=prepareProject(clean);
+ result.assertions=structuredClone(plan.assertions);
+ for(const a of plan.assertions){
+  if(a.visual?.carrier==='exclusive-parent'){const t=target({target:a.target,instance:a.instance,carrier:'exclusive-parent'});if(!result.targets.some(existing=>existing.key===t.key))result.targets.push(t);}
+  if(!a.spatial)continue;
+  const refs=[...(a.spatial.absent??[]),...(a.spatial.order??[]).flatMap(p=>[p.above,p.below])];
+  for(const ref of refs){const t=target(ref);if(!result.targets.some(existing=>existing.key===t.key))result.targets.push(t);}
+ }
+ return result;
+}
+export function validateFrozenSpatial(snapshot,spec){
+ validateSpatial(spec);
+ const group=ref=>{const t=target(ref),g=snapshot.groups.find(g=>g.key===t.key);assert(g,'Missing frozen spatial observation');return g;};
+ const box=ref=>{const g=group(ref);assert.equal(g.count,1,'Spatial target must be unique');assert.equal(g.members.length,1);const m=g.members[0];assert(m.state.visible,'Spatial target must be visible');return m.metrics.box;};
+ const order=(spec.order??[]).map(pair=>validateRegionOrder(box(pair.above),box(pair.below)));
+ const absent=(spec.absent??[]).map(ref=>{const g=group(ref);assert.equal(g.count,0,'Forbidden component exists');assert.equal(g.members.length,0);return ref;});
+ return {order,absent,snapshotAt:snapshot.snapshotAt};
+}

package/tools/modules/minifish/harness/independent-case-runner.mjs

@@ -1,3 +1,6 @@
+import {sampleComponentState,assertComponentState,assertComponentBranch,validateComponentStates} from './component-state.mjs';
+import {sampleDeclaredComponents,validateComponentMembership} from './component-membership.mjs';
+import {prepareHeldWithSpatial} from './held-spatial.mjs';
 import {validateRegionVisualAssertions,assertVisualMetrics} from './visual-expectation.mjs';
 import {hostPolicy} from '@minifish/project-host';
 import {prepareHeldNativeInput,executeHeldSnapshot} from './held-snapshot.mjs';
@@ -28,6 +31,9 @@ function target(root, name) { return semanticLocator(root, name); }
 
 export async function runMiniappCase({page, plan, testInfo}) {
   validateRegionVisualAssertions(plan.assertions);
+  validateComponentStates(plan,plan.componentContract);
+  assert(plan.componentContract?.schemaVersion===1,'Compiler-bound component membership contract required');
+  validateComponentMembership({declarations:[]},plan.componentContract.activeComponentIds);
   assert.equal(plan.resources.length, 0, 'resource handling is not implemented in this runner yet');
   const boundary = plan.boundaries.length ? independentBoundary(plan.boundaries) : zeroBusinessPlan();
   const images = installRendererImageEvidence(page);
@@ -56,7 +62,9 @@ export async function runMiniappCase({page, plan, testInfo}) {
   const locate=(root,name,options)=>locateProject(root,name,options,observation);
   try {
     result.preparation = 'running';
-    if(!artifactOnly&&(plan.beforeTarget??[]).some(a=>a.kind==='press'))heldSpec=prepareHeldSnapshot(plan);
+    if(!artifactOnly&&plan.assertions.some(a=>a.spatial!==undefined))assert((plan.beforeTarget??[]).some(a=>a.kind==='press'),'Spatial snapshot requires held input');
+    if(!artifactOnly&&(plan.beforeTarget??[]).some(a=>a.kind==='press'))heldSpec=prepareHeldWithSpatial(plan,prepareHeldSnapshot);
+    if(heldSpec)heldSpec.componentContract=plan.componentContract;
     if(plan.plugin){
       assert(process.env.MINIFISH_PLUGIN_PACKAGE_URL&&process.env.MINIFISH_PLUGIN_ARTIFACT_MANIFEST,'Explicit compiled plugin artifact required');
       const artifact=JSON.parse(await readFile(process.env.MINIFISH_PLUGIN_ARTIFACT_MANIFEST,'utf8'));
@@ -94,7 +102,7 @@ export async function runMiniappCase({page, plan, testInfo}) {
     assert(app, 'missing real page opening');
     await trace?.attach();
     input=targetActions({page,locate:(name,instance)=>locate(app.root,name,{instance}),synchronize:()=>synchronizeAnchors(app.root),boundary,receipts:result.actions,beforePress:async()=>{if(artifactOnly)capturePreparation=await prepareMiniappCapture(page);},observeInput:async(stage,action)=>trace?.sample(stage,app.root,boundary.evidence(),action)});
-    if(heldSpec)for(const a of plan.assertions)if(a.kind==='region'&&a.check==='visual')assert(!a.visual.carrier||a.visual.carrier==='semantic-root','Held visual carrier requires a supported frozen snapshot contract');
+    if(heldSpec)for(const a of plan.assertions)if(a.kind==='region'&&a.check==='visual')assert(!a.visual.carrier||['semantic-root','exclusive-parent'].includes(a.visual.carrier),'Held visual carrier requires a supported frozen snapshot contract');
     if(heldSpec)await prepareHeldNativeInput(app.root,heldSpec,locate(app.root,heldSpec.press.target,{instance:heldSpec.press.instance}));
     for(const action of plan.beforeTarget??[]){
       if(action.kind==='leave-return'){
@@ -114,7 +122,13 @@ export async function runMiniappCase({page, plan, testInfo}) {
       await synchronizeAnchors(app.root);
       const locator=assertion.kind==='host-navigation'?undefined:locate(app.root, assertion.target,{instance:assertion.instance});
       try {
-        if(assertion.kind==='host-native-ui'){result.observations[assertion.id]=await assertHostNativeUi(page,app,assertion);
+        result.observations.componentMembership=validateComponentMembership(await app.root.locator(':root').evaluate(sampleDeclaredComponents),plan.componentContract.activeComponentIds);
+        if(assertion.componentState!==undefined&&assertion.kind!=='component-state'){await expect(locator).toHaveCount(1);await expect(locator).toBeVisible();result.observations[assertion.id+':componentState']=assertComponentState(await locator.evaluate(sampleComponentState),assertion.componentState);}
+        if(assertion.kind==='component-state'){
+          const count=await locator.count(),members=[];assert(count<=1,'Unique branch owner required');
+          if(count)members.push({componentState:await locator.evaluate(sampleComponentState),visible:await locator.isVisible()});
+          result.observations[assertion.id]=assertComponentBranch({count,members},assertion.componentState,assertion.present,plan.componentContract.componentStates[assertion.target]);
+        }else if(assertion.kind==='host-native-ui'){result.observations[assertion.id]=await assertHostNativeUi(page,app,assertion);
         }else if(assertion.kind==='carousel-frame'){result.observations[assertion.id]=await observeCarousel(app.root,assertion.contract,{urls:assertion.images,records:images.records});
         }else if(assertion.kind==='host-navigation'){result.observations[assertion.id]=await assertHostNavigation(page,app,assertion,plan.hostSystemPlan);
         }else if(assertion.kind==='region'){

package/tools/modules/minifish/harness/jsapi.mjs

@@ -9,10 +9,13 @@ export const jsapiPath = '/__bill_tests__/jsapi';
 export const jsapiDeliveryPath = '/__bill_tests__/jsapi-delivery';
 const deliveryPlans = new WeakMap();
 const deliveryHeader = 'x-minifish-response-id';
+export function managedMockApis(additionalApis=[]){
+  return ['makePhoneCall','tradePay','getAuthCode','startApp','exitMiniProgram','exitApp',...additionalApis,...(additionalApis.includes('getStorage')?['getTinyLocalStorage']:[]),...(additionalApis.includes('setStorage')?['setTinyLocalStorage']:[])];
+}
 export function bridgeScript(origin, additionalApis = [], observeLoading = false, officialUi = [], observeCorrelation = false) {
   assert(!additionalApis.includes('pageScrollTo'),'Official scroll cannot enter renderer Mock list');
   assert(officialUi.every(api=>nativeUiApis.includes(api)),'Finite official UI delegation list');
-  const mockedApis = ['makePhoneCall','tradePay','getAuthCode','startApp','exitMiniProgram','exitApp', ...additionalApis,...(additionalApis.includes('getStorage')?['getTinyLocalStorage']:[]),...(additionalApis.includes('setStorage')?['setTinyLocalStorage']:[])];
+  const mockedApis = managedMockApis(additionalApis);
   return `window.lyraRendererExtendBridge.beforeMount(params => {
     const hostFixture=${JSON.stringify(hostDeviceFixture)};
     const mounted=(${configureHostDeviceMount.toString()})(params,hostFixture);