@antprofuse/saddle-islands-tools 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antprofuse/saddle-islands-tools",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Independent Saddle–Islands engineering tools",
   "files": [
     "tools"

package/tools/docs/minifish-testing.md

@@ -87,6 +87,16 @@ MT使用 `iteration stage-gate` 时必须提供 `--compile-result NEW_EXTERNAL_D
 
 按压region断言可声明公共 `spatial`：`order: [{above: {target, instance?}, below: {target, instance?}}]` 与 `absent: [{target, instance?}]`。目标使用cmp引用。该版本只支持按压region，其他用法在静态编译及运行输入前拒绝。原有普通区域顺序公共接口保持独立，不静默解释该字段。
 
+`spatial.ownership: [{parent: {target, instance?, carrier?}, child: {target, instance?, carrier?}}]` 要求实际选中父载体严格包含子载体，不能用坐标包含替代原生归属。每个载体必须唯一可见；循环实例必须明确选择。`spatial.align` 是相对几何关系数组，每项固定字段如下：
+
+```json
+{"subject":{"target":"cmp_123abc","instance":0},"reference":{"target":"cmp_456def","instance":0},"axis":"x","subjectEdge":"end","referenceEdge":"end","offset":0,"designWidth":375}
+```
+
+`axis` 取 `x/y`，两边的 edge 取 `start/center/end`；工具比较 subject 边位置减 reference 边位置是否等于源 offset × viewportWidth / designWidth，容差固定0.5实际CSS像素。offset与designWidth必须显式提供，不从产品反推期望。右齐可用x/end/end，垂直居中可用y/center/center。`subjectMeasure` 默认 `box`；取 `text` 时比较语义组件自己拥有的实际可见文字Range并集，拒绝空、隐藏、被裁切或属于其他子组件的文字；reference仍是组件盒。文字中心可对同一组件盒检查；同盒对自身的空洞对齐声明拒绝。尺寸、颜色等仍使用原visual合同，归属与对齐各自声明，互不推断。
+
+这些关系由公共准备统一收集目标，在原held单次采样中同时记录真实contains、原生几何与文字证据，立即释放后纯判定。未知字段及非活动组件引用在编译时拒绝。不要将业务layoutContext/layoutBasis作为公共接口；测试按源义务声明公开spatial，不扩大项目白名单来忽略义务。
+
 公共准备将该字段与项目核心按压合同分开校验；一次held快照同时记录原目标、关系目标的几何及排除目标的计数。补充目标不触发等待出现；释放后只判定冻结观察，错误时仍释放。输入350ms限制不变。关系要求两个唯一可见、非重叠且上方在前的真实载体；排除要求零匹配。缺观察、重复身份、隐藏关系目标及未知声明失败。本控制经过真实浏览器单快照验证，不等同于每个业务小程序已经验收。
 
 
@@ -118,3 +128,15 @@ Owner在项目配置填写 `pageSourceId`，精确引用冻结 `anchorInventory`
 接口要求原始内容精确为空，拒绝空白/非空、缺失/重复、隐藏或透明祖先；允许空字形及零几何，但仍检查有限几何、祖先/视口裁剪。样式取真实内容叶而非外包装；用既有 `validateNativeTextStyles(e.leafStyles, expected, scale)` 比较源期望。采到样式本身不代表样式正确。
 
 业务行、兄弟组件、实例顺序、布局和源允许为空的条件仍由项目测试依据Spec声明，通过公开语义集合与所有权接口检查；不从cmp字符串推断业务路径，不把允许空字形扩展成普通文字可隐藏。MT只做静态及合成设施检查，MP负责实际产品运行。
+
+### 非视觉输入与事务组件
+
+源组件身份仍保留在统一活动索引中。非视觉输入、事务端口不需要伪造DOM；以冻结的生成端口及真实公开行为校验。该能力目前支持插件事件驱动的输入/事务，不能任意把视觉组件声明成非视觉免检项。
+
+Owner准备 `componentPorts: {path, sha256}` 配置，指向测试目录内的冻结清单。清单为 `{schemaVersion:1, inventorySha256, bindings:[...]}`；每项包含 `componentId`、准确的 `sourceId`、`ownerSourceId`、`portName`、`generated:{path,sha256}` 及产品 `implementation:{chain:[{template,tag},...]}`。generated.path相对测试目录；chain.template相对Git根，首项为宿主模板，后项须沿实际usingComponents逐级到生成端口组件。清单和生成源必须已提交、干净、无符号链接且摘要匹配；组件归属按官方完整位置验证，不按末级名称猜测。此输入由Owner冻结维护，执行者不自行增添免检名单。
+
+测试在已有case中添加 `kind:"component-port"` 显式断言：`target` 为稳定cmp ID，`plugin` 指定 `instanceId/eventId/name/payload`，`boundaries` 指定实际产品边界的 `id/operation/times/fields`。fields每项为 `{path:["字段", "子字段"], equals:期望值}`。编译核对冻结端口、插件计划和必填期望；运行要求真实挂载、事件及回调收据，与实际产品请求字段、交付和消费次数分别相符。预设Mock参数不作为实际请求证据；仅准备事件或引用字符串不计覆盖。这里证明公开回调与外部产品效果，不宣称观察了私有输入存储或严格因果。业务字段期望仍由测试按Spec确定。
+
+该断言不支持按住快照、视觉或componentState属性；这些义务仍由相应组件断言承担。
+
+产品 `anchor-check` 同时提供 `--port-manifest`（Git相对路径）和 `--port-manifest-sha256` 时，核同业务冻结清单、生成源、AXML回调属性、usingComponents链及实际Page/Component注册函数；视觉声明与通过接线校验的端口集合共同对齐源组件全集。重复视觉/非视觉声明、悬空回调、错分支借用、动态无法判定的注册均拒绝。静态接线通过不证明业务数据流、条件可达性或处理结果，后者由运行断言保障。

package/tools/modules/minifish/anchor_check.py

@@ -21,7 +21,7 @@ def git(repo, *args):
     return subprocess.check_output(['git', '-C', str(repo), *args])
 
 
-def check(repo, product, head, inventory, parser, index, retired):
+def check(repo, product, head, inventory, parser, index, retired, port_components=None):
     if not re.fullmatch('[a-f0-9]{40}', head): raise ValueError('Full candidate commit required')
     if not product or product.startswith('/') or any(p in ('', '.', '..') for p in product.split('/')):
         raise ValueError('Repository-relative product directory required')
@@ -52,6 +52,11 @@ def check(repo, product, head, inventory, parser, index, retired):
         declared.update(values['values'])
         unknown = sorted(set(values['values'])-allowed)
         if unknown: issues.append({**row,'kind':'unknown','values':unknown,'precision':values['precision']})
+    ports = port_components or {}
+    if set(ports)-allowed: raise ValueError('Unknown nonvisual component binding')
+    overlap = set(ports)&declared
+    if overlap: issues.append({'kind':'conflicting-visual-port-declarations','values':sorted(overlap)})
+    declared.update(ports)
     missing = sorted(allowed-declared)
     if missing: issues.append({'kind':'missing-components','values':missing})
     if git(repo,'rev-parse','HEAD').decode().strip()!=head or git(repo,'status','--porcelain','--untracked-files=all','--',product).strip():
@@ -59,7 +64,7 @@ def check(repo, product, head, inventory, parser, index, retired):
     return {'schemaVersion':1,'check':'component-anchor-set-equality','candidate':head,'productDirectory':product,
             'sourceSnapshot':inventory['snapshotId'],'sourceQuerySha256':inventory['querySha256'],
             'identityContract':'allocated-component-id','sourceComponentIds':sorted(active.values()),'activeComponentIds':sorted(allowed),'declaredComponentIds':sorted(declared),
-            'templateFiles':files,'declarations':len(rows),'issues':issues,'passed':not issues,
+            'portBindings':ports,'templateFiles':files,'declarations':len(rows),'issues':issues,'passed':not issues,
             'limitations':['Does not prove all business components are annotated','Does not prove anchor carrier semantics or scenario visibility','Dynamic conditional results are conservative, not a reachability proof']}
 
 
@@ -72,6 +77,8 @@ def main(argv, identity):
     parser.add_argument('--inventory-sha256',required=True)
     parser.add_argument('--registry-directory',required=True,help='Git-relative code/.registry directory')
     parser.add_argument('--tool-node-modules',type=Path,required=True)
+    parser.add_argument('--port-manifest',help='Optional Git-relative frozen component port manifest')
+    parser.add_argument('--port-manifest-sha256')
     parser.add_argument('--output',type=Path,required=True)
     args=parser.parse_args(argv)
     data=args.inventory.read_bytes()
@@ -98,7 +105,47 @@ def main(argv, identity):
         raw=git(repo,'show',args.head+':'+file)
         bindings[name]={'path':file,'sha256':digest(raw)}
         values.append(parse_registry(raw.decode()))
-    result=check(repo,args.product_directory,args.head,json.loads(data),resolve,*values)
+    ports={}
+    if args.port_manifest:
+        from tools.modules.minifish.port_wiring import inspect_chain
+        base=reg[:-len('.registry')]+'minifish-tests/'
+        checked={}
+        def committed(name):
+            if not isinstance(name,str) or name.startswith('/') or any(p in ('','.','..') for p in name.split('/')):raise ValueError('Git-relative regular port input required')
+            parts=git(repo,'ls-tree',args.head,'--',name).decode().split()
+            if not parts:raise FileNotFoundError(name)
+            if parts[0]!='100644' or (repo/name).resolve()!=repo/name:raise ValueError('Regular non-symlink port input required')
+            if git(repo,'status','--porcelain','--untracked-files=all','--',name).strip():raise ValueError('Port input must be clean')
+            raw=git(repo,'show',args.head+':'+name)
+            if (repo/name).read_bytes()!=raw:raise ValueError('Port input differs from candidate')
+            checked[name]=digest(raw);return raw
+        if not args.port_manifest.startswith(base):raise ValueError('Port manifest must belong to same business test inputs')
+        raw=committed(args.port_manifest)
+        if digest(raw)!=args.port_manifest_sha256:raise ValueError('Port manifest digest mismatch')
+        manifest=json.loads(raw)
+        if manifest.get('schemaVersion')!=1 or manifest.get('inventorySha256')!=digest(data):raise ValueError('Port source inventory mismatch')
+        entries=manifest.get('bindings')
+        if not isinstance(entries,list) or not entries:raise ValueError('Nonempty source port bindings required')
+        active=validate(values[0],json.loads(data),values[1])
+        def inspect(payload):
+            proc=subprocess.run(['node',str(Path(__file__).parent/'compiler/port-wiring-cli.mjs'),str(args.tool_node_modules.resolve())],input=json.dumps(payload),text=True,capture_output=True,check=True)
+            return json.loads(proc.stdout)
+        for entry in entries:
+            cmp=entry['componentId']
+            if cmp in ports or active.get(cmp)!=entry['sourceId']:raise ValueError('Unknown or duplicate component port binding')
+            name=entry['generated']['path']
+            if name.startswith('/') or any(p in ('','.','..') for p in name.split('/')):raise ValueError('Frozen generated source must be test-relative')
+            frozen=committed(base+name)
+            if digest(frozen)!=entry['generated']['sha256']:raise ValueError('Generated source digest mismatch')
+            payload={'inventory':json.loads(data),'binding':entry,'frozenSource':frozen.decode()}
+            expected=inspect({**payload,'mode':'source'})
+            wire=inspect_chain(committed,args.product_directory+'/src',entry['implementation']['chain'],expected['publication']['callback'])
+            observed=inspect({**payload,'productSource':wire['productSource'],'hostSource':wire['hostSource'],'handler':wire['handler']})
+            ports[cmp]={**observed,'handler':wire['handler'],'generatedFile':wire['generatedFile'],'files':{name:digest(raw) for name,raw in wire['files'].items()}}
+        for name,expected in checked.items():
+            if digest(committed(name))!=expected:raise ValueError('Port input changed during inspection')
+    elif args.port_manifest_sha256:raise ValueError('Port manifest required with digest')
+    result=check(repo,args.product_directory,args.head,json.loads(data),resolve,*values,port_components=ports)
     if git(repo,'status','--porcelain','--untracked-files=all','--',reg).strip(): raise ValueError('Registry changed during inspection')
     result['registry']=bindings
     result.update(sourceInventorySha256=digest(data),tool={'commit':identity['commit'],'version':identity['version']})

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

@@ -11,3 +11,36 @@ test('duplicate, absent request, and callback type mismatch are rejected',async(
 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/);});
+
+// Preserve raw observations separately from expected fixtures and comparison normalization.
+test('actual requests are bound to the selected row, immutable, and not fabricated by fixture fields',async()=>{
+ const first=row(), second={...row(),id:'second',request:{operation:'sample.service.read',params:{key:'second'}}};
+ first.actualRequests=[{request:{forged:true}}];
+ const guard=createBoundary([first,second],{...policy,comparison:(op,v)=>({key:v.key})});
+ assert.deepEqual(guard.evidence().expectations.map(r=>r.actualRequests),[[],[]]);
+ const request={key:'second',actualExtra:7},wire={frame:'actual-frame'};
+ await guard.receive(second.request.operation,request,wire);
+ request.actualExtra=99;wire.frame='changed';
+ const evidence=guard.evidence();
+ assert.deepEqual(evidence.expectations[0].actualRequests,[]);
+ assert.deepEqual(evidence.expectations[1].actualRequests,[{operation:second.request.operation,request:{key:'second',actualExtra:7},wire:{frame:'actual-frame'}}]);
+ evidence.expectations[1].actualRequests[0].request.actualExtra=0;
+ assert.equal(guard.evidence().expectations[1].actualRequests[0].request.actualExtra,7);
+ assert.equal(guard.evidence().expectations[1].delivered,0);
+ assert.equal(guard.evidence().expectations[1].consumed,0);
+});
+test('rejected requests remain violations, not matched component evidence',async()=>{
+ const guard=createBoundary([row()],policy);
+ await assert.rejects(guard.receive('wrong.operation',{key:'alternate'}));
+ assert.deepEqual(guard.evidence().expectations[0].actualRequests,[]);
+ assert.equal(guard.evidence().attempts.length,1);
+ assert.throws(()=>guard.assertComplete());
+});
+test('official scroll records actual request without fabricating callback completion',()=>{
+ const r={...row(),execution:'official-scroll'},guard=createBoundary([r],policy);
+ guard.recordOfficialRequest(r.request.operation,r.request.params);
+ assert.deepEqual(guard.evidence().expectations[0].actualRequests,[{operation:r.request.operation,request:r.request.params,execution:'official-scroll'}]);
+ assert.equal(guard.evidence().expectations[0].consumed,0);
+ guard.recordOfficialCallback(r.request.operation,r.request.params,{kind:'success',value:r.outcome.value});
+ guard.assertComplete();
+});

package/tools/modules/minifish/compiler/anchor-coverage.mjs

@@ -1,3 +1,4 @@
+import {validateComponentPort} from '../harness/component-port.mjs';
 import {validatePageVisual} from '../harness/page-visual.mjs';
 import {validateSpatial} from '../harness/spatial-contract.mjs';
 import assert from 'node:assert/strict';
@@ -12,11 +13,12 @@ export function sourceComponents(inventory,active,retired){
 // Only actual target assertions count. Actions, sourceTarget, basis and nested
 // strings are never recursively treated as evidence of an executed assertion.
 const kinds=new Set(['component-state','region','hidden','visible','text','image','text-visual','button-visual','host-navigation','host-native-ui','carousel-frame']);
-export function assertionComponents(plan){
+export function assertionComponents(plan,contract){
  assert(Array.isArray(plan?.assertions)&&plan.assertions.length,'Compiled target assertions required');
  const seen=new Set(),components=new Set();
  for(const a of plan.assertions){
   assert(a&&typeof a.id==='string'&&a.id&&!seen.has(a.id),'Unique assertion identity required');seen.add(a.id);
+  if(a.kind==='component-port'){validateComponentPort(a,contract);components.add(a.target);continue;}
   if(a.kind==='page-visual'){validatePageVisual(a);assert(!(plan.beforeTarget??[]).some(x=>x.kind==='press'),'Page visual is not supported during held input');continue;}
   if(a.spatial!==undefined){
    assert(a.kind==='region'&&(plan.beforeTarget??[]).some(x=>x.kind==='press'),'Spatial snapshot currently requires held region assertion');

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

@@ -1,3 +1,4 @@
+import {validateComponentPorts} from '../harness/component-port.mjs';
 import {validateComponentStates} from '../harness/component-state.mjs';
 import {loadComponentContract} from './component-contract.mjs';
 import assert from 'node:assert/strict';
@@ -27,7 +28,7 @@ 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);
  assert(plan.componentContract===undefined,'Project must not override compiler component contract');
  plan={...plan,componentContract:await loadComponentContract(project)};
- validateComponentStates(plan,plan.componentContract);
+ validateComponentStates(plan,plan.componentContract);validateComponentPorts(plan,plan.componentContract);
  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`;

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

@@ -1,3 +1,4 @@
+import {validateComponentPorts} from '../harness/component-port.mjs';
 import {validateComponentStates} from '../harness/component-state.mjs';
 import {loadComponentContract} from './component-contract.mjs';
 import {assertionComponents,compareCoverage} from './anchor-coverage.mjs';
@@ -59,8 +60,8 @@ export async function compileCheck(options){
    assert.deepEqual(definition.ancestors,fragments.map(f=>f.id),'Preparation ancestry mismatch');
    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);
+   validateComponentStates(plan,componentContract);validateComponentPorts(plan,componentContract);
+   const componentIds=assertionComponents(plan,componentContract);
    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});}
  }

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

@@ -36,8 +36,29 @@ export async function loadComponentContract(project){
   assert(typeof config.pageRoute==='string'&&config.pageRoute,'Configured product route required');
   page={sourceId:config.pageSourceId,route:config.pageRoute};
  }
- 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'}}));
+ const {activeComponentIds,componentSources,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'}}));
+ const ports={},portInputs=[];
+ if(config.componentPorts!==undefined){
+  const {readGeneratedPorts,bindSourcePort}=await import('./generated-ports.mjs');
+  const entry=config.componentPorts;
+  assert(entry?.path&&/^[a-f0-9]{64}$/.test(entry.sha256??''),'Frozen component port manifest required');
+  const file=path.resolve(root,entry.path);assert(file.startsWith(root+path.sep),'Port manifest escaped test inputs');
+  const manifest=await read(file);assert.equal(manifest.sha256,entry.sha256,'Port manifest digest mismatch');
+  const data=JSON.parse(manifest.bytes);
+  assert.equal(data.schemaVersion,1,'Unsupported port manifest');
+  assert.equal(data.inventorySha256,inventory.sha256,'Port manifest source inventory mismatch');
+  assert(Array.isArray(data.bindings)&&data.bindings.length,'Explicit source port bindings required');
+  portInputs.push({path:manifest.path,sha256:manifest.sha256});
+  for(const b of data.bindings){
+   assert(componentSources[b.componentId]===b.sourceId&&!Object.hasOwn(ports,b.componentId),'Unknown or duplicate port component binding');
+   assert(typeof b.generated?.path==='string'&&/^[a-f0-9]{64}$/.test(b.generated.sha256??''),'Frozen generated source required');
+   const file=path.resolve(root,b.generated.path);assert(file.startsWith(root+path.sep),'Generated source escaped test inputs');
+   const source=await read(file);assert.equal(source.sha256,b.generated.sha256,'Generated source digest mismatch');
+   ports[b.componentId]=bindSourcePort(parsedInventory,b,readGeneratedPorts(source.bytes.toString()));
+   portInputs.push({path:source.path,sha256:source.sha256});
+  }
+ }
  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,...(page?{page}:{}),config:binding(configInput),inventory:binding(inventory),registry:{active:binding(active),retired:binding(retired)}};
+ return {schemaVersion:1,head,activeComponentIds,componentStates,branches,...(portInputs.length?{ports,portInputs}:{}),...(page?{page}:{}),config:binding(configInput),inventory:binding(inventory),registry:{active:binding(active),retired:binding(retired)}};
 }

package/tools/modules/minifish/compiler/generated-ports.mjs

@@ -0,0 +1,67 @@
+/** Inspect generated port metadata without importing or executing product code.
+ * This proves a declaration, not runtime reachability or business correctness.
+ */
+import assert from 'node:assert/strict';
+import ts from 'typescript';
+
+export function readGeneratedPorts(source) {
+ const file=ts.createSourceFile('generated.js',source,ts.ScriptTarget.Latest,true,ts.ScriptKind.JS);
+ assert.equal(file.parseDiagnostics.length,0,'Invalid generated port source');
+ const declarations=[];
+ function walk(node){if(ts.isVariableDeclaration(node)&&ts.isIdentifier(node.name)&&node.name.text==='ports')declarations.push(node);ts.forEachChild(node,walk);}
+ walk(file);assert.equal(declarations.length,1,'Unique generated ports declaration required');
+ function literal(node){
+  assert(node,'Missing generated port initializer');
+  if(ts.isStringLiteral(node))return node.text;
+  if(ts.isArrayLiteralExpression(node))return node.elements.map(literal);
+  if(ts.isObjectLiteralExpression(node)){
+   const out=Object.create(null);
+   for(const item of node.properties){
+    assert(ts.isPropertyAssignment(item)&&(ts.isIdentifier(item.name)||ts.isStringLiteral(item.name)),'Literal generated port properties required');
+    const key=item.name.text;assert(!Object.hasOwn(out,key),'Duplicate generated port property');out[key]=literal(item.initializer);
+   }return out;
+  }
+  throw Error('Generated port metadata must be literal, not executable');
+ }
+ const ports=literal(declarations[0].initializer);
+ assert(Array.isArray(ports)&&ports.length,'Nonempty generated ports required');
+ const names=new Set(),callbacks=new Set(),physical=new Set();
+ for(const port of ports){
+  assert.deepEqual(Object.keys(port).sort(),['kind','name','publication','requiredInputs'],'Unexpected generated port fields');
+  assert(typeof port.name==='string'&&port.name&&!names.has(port.name),'Unique port name required');names.add(port.name);
+  assert(['input','interaction'].includes(port.kind),'Unsupported port kind');
+  assert(Array.isArray(port.requiredInputs),'Explicit port inputs required');
+  assert(port.publication&&typeof port.publication.name==='string'&&port.publication.name&&typeof port.publication.callback==='string'&&port.publication.callback,'Published port callback required');
+  assert.deepEqual(Object.keys(port.publication).sort(),['callback','name'],'Unexpected publication fields');
+  assert(!callbacks.has(port.publication.callback)&&!physical.has(port.publication.name),'Duplicate port publication');callbacks.add(port.publication.callback);physical.add(port.publication.name);
+  if(port.kind==='input')assert.equal(port.requiredInputs.length,0,'Input port cannot depend on other inputs');
+ }
+ for(const port of ports){
+  const inputs=new Set();
+  for(const input of port.requiredInputs){
+   assert.deepEqual(Object.keys(input).sort(),['name','physicalName','type'],'Unexpected input fields');
+   const source=ports.find(p=>p.name===input.name&&p.kind==='input');
+   assert(source,'Required input port not declared');
+   assert.equal(input.physicalName,source.publication.name,'Required input publication mismatch');
+   assert(typeof input.type==='string'&&input.type&&!inputs.has(input.name),'Unique typed required inputs needed');inputs.add(input.name);
+  }
+ }
+ return JSON.parse(JSON.stringify(ports));
+}
+
+export function bindSourcePort(inventory,{sourceId,ownerSourceId,portName},ports){
+ const unique=id=>{const rows=inventory.targets.filter(t=>t.id===id&&t.kind==='component');assert.equal(rows.length,1,'Exact source component required');return rows[0];};
+ const child=unique(sourceId),owner=unique(ownerSourceId);
+ assert(typeof child.source?.file==='string'&&child.source.file,'Source file required');
+ assert.equal(child.source?.file,owner.source?.file,'Port and owner source files differ');
+ const location=row=>{const found=row.locations.filter(l=>l.kind==='visualComponent');assert.equal(found.length,1,'Unique component source location required');return found[0];};
+ const c=location(child),p=location(owner);
+ const path=l=>l.componentPath??[{component:l.component}];
+ assert.equal(c.page,p.page,'Port owner page mismatch');
+ assert.deepEqual(path(c).slice(0,-1),path(p),'Port must be a direct source child of its physical owner');
+ assert.equal(path(c).at(-1).component,portName,'Port source component name mismatch');
+ assert(!path(c).at(-1).branch,'Branch is not a port identity');
+ const candidates=ports.filter(port=>port.name===portName);assert.equal(candidates.length,1,'Unique generated source port required');
+ const {name,kind,requiredInputs,publication}=candidates[0];
+ return {sourceId,ownerSourceId,name,kind,requiredInputs:structuredClone(requiredInputs),publication:structuredClone(publication)};
+}

package/tools/modules/minifish/compiler/port-wiring-cli.mjs

@@ -0,0 +1,17 @@
+import {createRequire, registerHooks} from 'node:module';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+const modules = process.argv[2];
+if (modules) {
+ const require = createRequire(path.resolve(modules,'../package.json'));
+ registerHooks({resolve(specifier, context, next) {
+  if(specifier === 'typescript')return {url:pathToFileURL(require.resolve(specifier)).href,shortCircuit:true};
+  return next(specifier,context);
+ }});
+}
+const {readGeneratedPorts,bindSourcePort}=await import('./generated-ports.mjs');
+const {validatePortInspection}=await import('./port-wiring.mjs');
+let data='';for await(const part of process.stdin)data+=part;
+const request=JSON.parse(data);
+const result=request.mode==='source'?bindSourcePort(request.inventory,request.binding,readGeneratedPorts(request.frozenSource)):validatePortInspection(request);
+console.log(JSON.stringify(result));

package/tools/modules/minifish/compiler/port-wiring.mjs

@@ -0,0 +1,36 @@
+import assert from 'node:assert/strict';
+import ts from 'typescript';
+import {readGeneratedPorts,bindSourcePort} from './generated-ports.mjs';
+
+export function registeredHandler(source,name){
+ const file=ts.createSourceFile('host.ts',source,ts.ScriptTarget.Latest,true,ts.ScriptKind.TS);
+ assert.equal(file.parseDiagnostics.length,0,'Invalid host source');
+ const registrations=[];
+ function walk(node){
+  if(ts.isCallExpression(node)&&ts.isIdentifier(node.expression)&&['Page','Component'].includes(node.expression.text))registrations.push(node);
+  ts.forEachChild(node,walk);
+ }
+ walk(file);assert.equal(registrations.length,1,'Unique literal host registration required');
+ const call=registrations[0],object=call.arguments[0];
+ assert(ts.isObjectLiteralExpression(object),'Literal host registration required');
+ let properties=object.properties;
+ if(call.expression.text==='Component'){
+  const methods=properties.filter(p=>p.name&&(ts.isIdentifier(p.name)||ts.isStringLiteral(p.name))&&p.name.text==='methods');
+  assert.equal(methods.length,1,'Unique component methods required');assert(ts.isPropertyAssignment(methods[0])&&ts.isObjectLiteralExpression(methods[0].initializer),'Literal component methods required');properties=methods[0].initializer.properties;
+ }
+ assert(!properties.some(p=>ts.isSpreadAssignment(p)||p.name&&ts.isComputedPropertyName(p.name)),'Dynamic host properties prevent binding verification');
+ const candidates=properties.filter(p=>p.name&&(ts.isIdentifier(p.name)||ts.isStringLiteral(p.name))&&p.name.text===name);
+ assert.equal(candidates.length,1,'Published callback handler missing or duplicate');
+ const p=candidates[0],fn=ts.isMethodDeclaration(p)?p:ts.isPropertyAssignment(p)?p.initializer:null;
+ assert(fn&&(ts.isMethodDeclaration(fn)||ts.isFunctionExpression(fn)||ts.isArrowFunction(fn)),'Handler must be a declared function');
+ assert(fn.parameters.length>0&&fn.body,'Handler must accept the published value');
+ assert(!ts.isBlock(fn.body)||fn.body.statements.length>0,'Empty callback handler');
+ return {name,observation:'registered-handler-declaration'};
+}
+export function validatePortInspection({inventory,binding,frozenSource,productSource,hostSource,handler}){
+ const frozen=readGeneratedPorts(frozenSource),actual=readGeneratedPorts(productSource);
+ const expected=bindSourcePort(inventory,binding,frozen),observed=bindSourcePort(inventory,binding,actual);
+ assert.deepEqual(observed,expected,'Product port metadata differs from frozen source');
+ registeredHandler(hostSource,handler);
+ return expected;
+}

package/tools/modules/minifish/component_index_bridge.py

@@ -23,6 +23,6 @@ if __name__=='__main__':
             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}))
+        print(json.dumps({'activeComponentIds':list(active),'componentSources':active,'componentStates':states,'branches':branches}))
     else:
         print(json.dumps(list(active)))

package/tools/modules/minifish/harness/boundary-observation.mjs

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+
+// Read observed requests, never the fixture's request.params. This proves an
+// external boundary result, not an internal write or causality from an event.
+export function observeCompletedBoundary(evidence, specification) {
+  assert(evidence && Array.isArray(evidence.expectations) && Array.isArray(evidence.violations), 'Boundary ledger required');
+  assert.deepEqual(evidence.violations, [], 'Boundary violations invalidate observations');
+  assert(specification && typeof specification.id === 'string' && specification.id, 'Boundary id required');
+  assert(Number.isSafeInteger(specification.times) && specification.times > 0, 'Exact positive observation count required');
+  assert(Array.isArray(specification.fields) && specification.fields.length, 'Explicit actual request fields required');
+  const rows = evidence.expectations.filter(row => row.id === specification.id);
+  assert.equal(rows.length, 1, 'Unique observed boundary required');
+  const row = rows[0];
+  assert.equal(row.request?.operation, specification.operation, 'Boundary operation mismatch');
+  for (const key of ['times', 'received', 'delivered', 'consumed']) assert.equal(row[key], specification.times, 'Incomplete boundary ' + key);
+  assert.equal(row.cancelled, 0, 'Cancelled boundary cannot provide completion evidence');
+  assert.equal(row.actualRequests?.length, specification.times, 'Actual matched request evidence required');
+  assert.equal(row.callbacks?.length, specification.times, 'Actual callback evidence required');
+  const paths = new Set();
+  for (const field of specification.fields) {
+    assert(Array.isArray(field.path) && field.path.length && field.path.every(key => typeof key === 'string' && key.length && !['__proto__', 'prototype', 'constructor'].includes(key)), 'Explicit safe field path required');
+    assert(Object.hasOwn(field, 'equals') && field.equals !== undefined, 'Explicit field expectation required');
+    const identity = JSON.stringify(field.path);
+    assert(!paths.has(identity), 'Duplicate field expectation'); paths.add(identity);
+  }
+  const observations = row.actualRequests.map(receipt => {
+    assert.equal(receipt.operation, specification.operation, 'Actual operation mismatch');
+    const fields = specification.fields.map(field => {
+      let value = receipt.request;
+      for (const key of field.path) {
+        assert(value !== null && typeof value === 'object' && Object.hasOwn(value, key), 'Missing actual field ' + field.path.join('.'));
+        value = value[key];
+      }
+      assert.deepEqual(value, field.equals, 'Actual request field mismatch: ' + field.path.join('.'));
+      return {path: [...field.path], value: structuredClone(value)};
+    });
+    return {operation: receipt.operation, fields};
+  });
+  return {boundaryId: row.id, observations, callbacks: structuredClone(row.callbacks)};
+}

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

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import {observeCompletedBoundary} from './boundary-observation.mjs';
+
+export function validateComponentPort(assertion, contract){
+ assert(assertion?.kind==='component-port','Component port assertion required');
+ assert(/^cmp_[a-f0-9]{6}$/.test(assertion.target??''),'Allocated component target required');
+ const binding=contract?.ports?.[assertion.target];
+ assert(binding&&['input','interaction'].includes(binding.kind),'Frozen source port binding required');
+ assert(assertion.plugin&&typeof assertion.plugin.instanceId==='string'&&assertion.plugin.instanceId&&typeof assertion.plugin.eventId==='string'&&assertion.plugin.eventId&&typeof assertion.plugin.name==='string'&&assertion.plugin.name,'Explicit plugin event identity required');
+ assert(Object.hasOwn(assertion.plugin,'payload')&&assertion.plugin.payload!==undefined,'Explicit event payload expectation required');
+ assert(assertion.componentState===undefined&&assertion.visual===undefined&&assertion.spatial===undefined,'Port assertions do not support visual or state observations');
+ assert(Array.isArray(assertion.boundaries)&&assertion.boundaries.length,'Observed product effects required');
+ const seen=new Set();
+ for(const b of assertion.boundaries){
+  assert(typeof b.id==='string'&&b.id&&!seen.has(b.id),'Unique boundary identity required');seen.add(b.id);
+  assert(typeof b.operation==='string'&&b.operation&&Number.isSafeInteger(b.times)&&b.times>0,'Exact boundary operation and count required');
+  assert(Array.isArray(b.fields)&&b.fields.length,'Actual field assertions required');
+  for(const f of b.fields)assert(Array.isArray(f.path)&&f.path.length&&f.path.every(x=>typeof x==='string'&&x&&!['__proto__','constructor','prototype'].includes(x))&&Object.hasOwn(f,'equals')&&f.equals!==undefined,'Explicit actual field expectation required');
+ }
+ return binding;
+}
+
+// Mount/event/callback observations plus external effects are independently
+// checked. This does not claim observation of private input storage or causality.
+export function observeComponentPort(assertion, contract, evidence){
+ const binding=validateComponentPort(assertion,contract),p=assertion.plugin,ledger=evidence?.pluginEvents;
+ assert(ledger&&Array.isArray(ledger.rows),'Actual plugin event ledger required');
+ assert.deepEqual(ledger.violations,[],'Plugin violations invalidate port evidence');
+ const select=kind=>ledger.rows.filter(r=>r.instanceId===p.instanceId&&r.kind===kind&&(kind==='mounted'||r.eventId===p.eventId));
+ const mount=select('mounted');assert.equal(mount.length,1,'Unique actual plugin mount required');
+ const event=select('event'),callback=select('callback');
+ assert.equal(event.length,1,'Unique actual plugin event required');assert.equal(callback.length,1,'Actual plugin callback completion required');
+ for(const row of [event[0],callback[0]]){
+  assert.equal(row.name,p.name,'Actual plugin event name mismatch');assert.deepEqual(row.payload,p.payload,'Actual plugin payload mismatch');
+  assert.deepEqual(row.props,mount[0].props,'Plugin instance props mismatch');
+ }
+ assert(ledger.rows.indexOf(mount[0])<ledger.rows.indexOf(event[0])&&ledger.rows.indexOf(event[0])<ledger.rows.indexOf(callback[0]),'Plugin lifecycle order mismatch');
+ const boundaries=assertion.boundaries.map(b=>observeCompletedBoundary(evidence,b));
+ return {componentId:assertion.target,sourceId:binding.sourceId,port:binding.name,kind:binding.kind,
+  plugin:{instanceId:p.instanceId,eventId:p.eventId,name:p.name,payload:structuredClone(event[0].payload)},boundaries,
+  observation:'public-plugin-callback-and-external-product-effects'};
+}
+
+export function validateComponentPorts(plan,contract){
+ for(const a of plan.assertions??[])if(a.kind==='component-port'){
+  validateComponentPort(a,contract);
+  assert(!(plan.beforeTarget??[]).some(x=>x.kind==='press'),'Component port assertions are not supported in held snapshots');
+  const instance=plan.plugin?.events?.instances?.filter(x=>x.id===a.plugin.instanceId)??[];
+  assert.equal(instance.length,1,'Declared unique plugin instance required');
+  const events=instance[0].events.filter(x=>x.id===a.plugin.eventId);
+  assert.equal(events.length,1,'Declared unique plugin event required');
+  assert.equal(events[0].name,a.plugin.name,'Plugin event declaration mismatch');
+  assert.deepEqual(events[0].payload,a.plugin.payload,'Plugin payload declaration mismatch');
+ }
+}

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

@@ -1,3 +1,4 @@
+import {spatialReferences} from './spatial-contract.mjs';
 import {validatePageVisual} from './page-visual.mjs';
 import assert from 'node:assert/strict';
 
@@ -21,7 +22,7 @@ export function validateComponentStates(plan,contract){
  for(const a of plan.assertions??[]){
   if(a.kind==='page-visual'){validatePageVisual(a);assert(contract.page?.sourceId&&contract.page.route,'Compiler-bound page required');assert(!(plan.beforeTarget??[]).some(x=>x.kind==='press'),'Page visual is not supported during held input');continue;}
   reference(a);
-  for(const ref of [...(a.spatial?.absent??[]),...(a.spatial?.order??[]).flatMap(pair=>[pair.above,pair.below])])reference(ref);
+  for(const ref of (a.spatial?spatialReferences(a.spatial):[]))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');

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

@@ -40,7 +40,13 @@ export async function captureHeldSnapshot(root,spec){
    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 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;
+  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.spatialOwnership=(spec.spatialOwnership??[]).map(pair=>{
+   const parents=groups.find(g=>g.target.key===pair.parentKey),children=groups.find(g=>g.target.key===pair.childKey);
+   if(!parents||!children)throw Error('Missing held ownership targets');
+   const p=parents.nodes.length===1?(${resolveVisualCarrier.toString()})(parents.nodes[0],parents.target.carrier??'semantic-root'):null;
+   const c=children.nodes.length===1?(${resolveVisualCarrier.toString()})(children.nodes[0],children.target.carrier??'semantic-root'):null;
+   return {...pair,contains:!!(p&&c&&p!==c&&p.contains(c))};
+  });result.snapshotAt=now();return result;
  }`;
  return freezeHeldSnapshot(await root.locator(':root').evaluate(Function('return ('+body+')')(),spec));
 }

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

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import {validateRegionOrder} from './region-order.mjs';
-import {validateSpatial,spatialTarget as target} from './spatial-contract.mjs';
+import {validateSpatial,spatialReferences,spatialTarget as target} from './spatial-contract.mjs';
 export {validateSpatial} from './spatial-contract.mjs';
 export function prepareHeldWithSpatial(plan,prepareProject){
  const clean=structuredClone(plan);
@@ -10,9 +10,10 @@ export function prepareHeldWithSpatial(plan,prepareProject){
  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])];
+  const refs=spatialReferences(a.spatial);
   for(const ref of refs){const t=target(ref);if(!result.targets.some(existing=>existing.key===t.key))result.targets.push(t);}
  }
+ result.spatialOwnership=plan.assertions.flatMap(a=>(a.spatial?.ownership??[]).map(p=>({parentKey:target(p.parent).key,childKey:target(p.child).key})));
  return result;
 }
 export function validateFrozenSpatial(snapshot,spec){
@@ -21,5 +22,39 @@ export function validateFrozenSpatial(snapshot,spec){
  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};
+ const member=ref=>{box(ref);return group(ref).members[0];};
+ const ownership=(spec.ownership??[]).map(pair=>{
+  member(pair.parent);member(pair.child);
+  const actual=snapshot.spatialOwnership?.find(p=>p.parentKey===target(pair.parent).key&&p.childKey===target(pair.child).key);
+  assert(actual?.contains===true,'Actual frozen native ownership required');return actual;
+ });
+ const align=(spec.align??[]).map(item=>{
+  const subject=member(item.subject),reference=member(item.reference);
+  assert(subject.metrics.frameId&&subject.metrics.frameId===reference.metrics.frameId,'Same native frame required for alignment');
+  const width=reference.metrics.viewport?.width;
+  assert(Number.isFinite(width)&&width>0&&subject.metrics.viewport?.width===width,'Same viewport required for alignment');
+  let measured=subject.metrics.box;
+  if(item.subjectMeasure==='text'){
+   const paint=subject.textPaint;assert(paint?.entries?.length,'Actual owned text paint required');
+   for(const entry of paint.entries){
+    assert(entry.owned&&entry.visible&&entry.opacity>0,'Owned visible text paint required');
+    const r=entry.range;
+    for(const bound of [...entry.clips,{...paint.viewport,clipX:true,clipY:true},{...paint.box,clipX:true,clipY:true}]){
+     if(bound.clipX)assert(r.x>=bound.x-.5&&r.x+r.width<=bound.x+bound.width+.5,'Alignment text is horizontally clipped');
+     if(bound.clipY)assert(r.y>=bound.y-.5&&r.y+r.height<=bound.y+bound.height+.5,'Alignment text is vertically clipped');
+    }
+   }
+   const rects=paint.entries.map(e=>e.range),x=Math.min(...rects.map(r=>r.x)),y=Math.min(...rects.map(r=>r.y));
+   measured={x,y,width:Math.max(...rects.map(r=>r.x+r.width))-x,height:Math.max(...rects.map(r=>r.y+r.height))-y};
+  }
+  const coordinate=(rect,edge)=>{
+   for(const field of ['x','y','width','height'])assert(Number.isFinite(rect[field]),'Finite native geometry required');
+   assert(rect.width>0&&rect.height>0,'Nonempty native geometry required');
+   return rect[item.axis]+rect[item.axis==='x'?'width':'height']*({start:0,center:.5,end:1}[edge]);
+  };
+  const actual=coordinate(measured,item.subjectEdge)-coordinate(reference.metrics.box,item.referenceEdge),expected=item.offset*width/item.designWidth;
+  assert(Math.abs(actual-expected)<=.5,`Frozen relative alignment differs: ${actual} != ${expected}`);
+  return {actual,expected,axis:item.axis,subjectMeasure:item.subjectMeasure??'box'};
+ });
+ return {order,absent,ownership,align,snapshotAt:snapshot.snapshotAt};
 }

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

@@ -1,3 +1,4 @@
+import {validateComponentPorts,observeComponentPort} from './component-port.mjs';
 import {observePageVisual,assertPageRoute} from './page-visual.mjs';
 import {sampleComponentState,assertComponentState,assertComponentBranch,validateComponentStates} from './component-state.mjs';
 import {sampleDeclaredComponents,validateComponentMembership} from './component-membership.mjs';
@@ -32,7 +33,7 @@ function target(root, name) { return semanticLocator(root, name); }
 
 export async function runMiniappCase({page, plan, testInfo}) {
   validateRegionVisualAssertions(plan.assertions);
-  validateComponentStates(plan,plan.componentContract);
+  validateComponentStates(plan,plan.componentContract);validateComponentPorts(plan,plan.componentContract);
   if(plan.assertions.some(a=>a.kind==='page-visual'))assertPageRoute(plan.componentContract.page,process.env.MINIFISH_PAGE_ROUTE);
   assert(plan.componentContract?.schemaVersion===1,'Compiler-bound component membership contract required');
   validateComponentMembership({declarations:[]},plan.componentContract.activeComponentIds);
@@ -122,11 +123,12 @@ export async function runMiniappCase({page, plan, testInfo}) {
       if(!held.timing.eligible){result.inputValidity='invalid';result.target='invalidated';}
     }else for (const assertion of plan.assertions) {
       await synchronizeAnchors(app.root);
-      const locator=['host-navigation','page-visual'].includes(assertion.kind)?undefined:locate(app.root, assertion.target,{instance:assertion.instance});
+      const locator=['host-navigation','page-visual','component-port'].includes(assertion.kind)?undefined:locate(app.root, assertion.target,{instance:assertion.instance});
       try {
         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==='page-visual'){result.observations[assertion.id]=await observePageVisual(app.root,assertion,plan.componentContract.page);
+        if(assertion.kind==='component-port'){result.observations[assertion.id]=observeComponentPort(assertion,plan.componentContract,app.evidence());
+        }else if(assertion.kind==='page-visual'){result.observations[assertion.id]=await observePageVisual(app.root,assertion,plan.componentContract.page);
         }else 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()});

package/tools/modules/minifish/harness/request-guard.mjs

@@ -6,7 +6,7 @@ export function createBoundary(definitions,policy) {
  assert(Object.values(policy).every(v=>typeof v==='function'),'Explicit boundary policy required');
  assert(new Set(definitions.map(d=>d.id)).size===definitions.length,'Duplicate boundary id');
  validatePacketPlan(structuredClone(definitions));
- const rows=definitions.map(item=>{assert(Number.isSafeInteger(item.times)&&item.times>0,'Positive exact request count required');validateIndependentFixture(structuredClone(item));return {...structuredClone(item),received:0,delivered:0,consumed:0,cancelled:0,released:false,callbacks:[]};});
+ const rows=definitions.map(item=>{assert(Number.isSafeInteger(item.times)&&item.times>0,'Positive exact request count required');validateIndependentFixture(structuredClone(item));return {...structuredClone(item),received:0,delivered:0,consumed:0,cancelled:0,released:false,callbacks:[],actualRequests:[]};});
  const requiresConsumption=r=>!!r.requireConsumption||!!requiresSourceConsumption(structuredClone(r));
  const attempts=[],violations=[],pending=new Map();let closed=false;
  const effective=r=>r.outcome.kind==='hold'?r.released?r.outcome.release:null:r.outcome;
@@ -22,7 +22,7 @@ export function createBoundary(definitions,policy) {
     const row=select(operation,request,r=>r.received<r.times);
     assert(row,`Unexpected operation, parameters or duplicate call: ${operation}`);
     for(const id of row.after??[]){const prior=rows.find(r=>r.id===id);assert(prior&&prior.delivered===prior.times,`Boundary before required response ${id}`);}
-    assert(!closed,'Boundary is closed');assert(!row.execution,'Official execution cannot receive a Mock response');row.received++;
+    assert(!closed,'Boundary is closed');assert(!row.execution,'Official execution cannot receive a Mock response');row.received++;row.actualRequests.push(structuredClone({operation,request,...(wire!==undefined?{wire}:{})}));
     if(row.outcome.kind==='hold')await new Promise((resolve,reject)=>pending.set(row.id,[...(pending.get(row.id)??[]),{resolve,reject,row}]));
     return result(row);
    }catch(e){if(e.message!=='Controlled held call cancelled at case cleanup')violations.push(e.message);throw e;}
@@ -31,7 +31,7 @@ export function createBoundary(definitions,policy) {
   recordNativeUiRequest(operation,request,wire){try{
    assert(!closed,'Boundary is closed');const r=select(operation,request,r=>r.execution==='official-ui'&&r.received===0);assert(r,'Unexpected, wrong or duplicate official UI request');
    for(const id of r.after??[]){const prior=rows.find(r=>r.id===id);assert(prior?.delivered===prior.times,'Official UI before '+id);}
-   r.received++;attempts.push(structuredClone({operation,request,wire,execution:'official-ui'}));return r.id;
+   r.received++;r.actualRequests.push(structuredClone({operation,request,wire,execution:'official-ui'}));attempts.push(structuredClone({operation,request,wire,execution:'official-ui'}));return r.id;
   }catch(e){violations.push(e.message);throw e;}},
   recordNativeUiResult(operation,request,receipt){try{
    attempts.push(structuredClone({operation,request,execution:'official-ui-result',receipt}));
@@ -40,7 +40,7 @@ export function createBoundary(definitions,policy) {
    assert.deepEqual(receipt.officialTarget,actualRequest.wire.officialTarget,'Actual result must belong to the same official host request');
    r.delivered++;r.officialResult=structuredClone(receipt);
   }catch(e){violations.push(e.message);throw e;}},
-  recordOfficialRequest(operation,request){try{assert(!closed,'Boundary is closed');const r=select(operation,request,r=>r.execution==='official-scroll'&&r.received===0);assert(r,'Unexpected official scroll request');for(const id of r.after??[]){const prior=rows.find(r=>r.id===id);assert(prior?.delivered===prior.times,'Official scroll before '+id);}r.received++;attempts.push(structuredClone({operation,request,execution:'official-scroll'}));}catch(e){violations.push(e.message);throw e;}},
+  recordOfficialRequest(operation,request){try{assert(!closed,'Boundary is closed');const r=select(operation,request,r=>r.execution==='official-scroll'&&r.received===0);assert(r,'Unexpected official scroll request');for(const id of r.after??[]){const prior=rows.find(r=>r.id===id);assert(prior?.delivered===prior.times,'Official scroll before '+id);}r.received++;r.actualRequests.push(structuredClone({operation,request,execution:'official-scroll'}));attempts.push(structuredClone({operation,request,execution:'official-scroll'}));}catch(e){violations.push(e.message);throw e;}},
   recordOfficialCallback(operation,request,callback){try{const r=select(operation,request,r=>r.execution==='official-scroll'&&r.received===1&&r.delivered===0);assert(r,'Official callback without request or duplicate');assert.equal(callback?.kind,'success','Official scroll success required');assert.deepEqual(callback.value,r.outcome.value,'Actual official scroll result');r.delivered++;r.consumed++;r.callbacks.push(structuredClone(callback));}catch(e){violations.push(e.message);throw e;}},
   markDelivered(operation,request){try{const r=select(operation,request,r=>r.delivered<r.received&&effective(r)&&!r.cancelled);assert(r,'Unexpected response delivery');r.delivered++;}catch(e){violations.push(e.message);throw e;}},
   markConsumed(operation,request,callback){try{const r=select(operation,request,r=>r.consumed<r.received&&effective(r)&&!r.cancelled);assert(r,'Unexpected response consumption');const expected=effective(r).kind==='error'||effective(r).value?.$testTransportFailure?'fail':'success';if(r.requireConsumption||callback?.kind)assert.equal(callback?.kind,expected,'Unexpected callback type');r.consumed++;r.callbacks.push(structuredClone(callback??{}));}catch(e){violations.push(e.message);throw e;}},

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

@@ -9,12 +9,31 @@ export function spatialTarget(ref){
  return {...ref,key,styleKeys:[],waitForPresence:false};
 }
 export function validateSpatial(spec){
- assert(spec&&Object.keys(spec).every(k=>['order','absent'].includes(k)),'Unknown spatial obligation');
- for(const name of ['order','absent'])assert(spec[name]===undefined||Array.isArray(spec[name]),'Spatial obligation must be an array');
- assert((spec.order?.length??0)+(spec.absent?.length??0)>0,'Empty spatial obligation');
+ assert(spec&&Object.keys(spec).every(k=>['order','absent','ownership','align'].includes(k)),'Unknown spatial obligation');
+ for(const name of ['order','absent','ownership','align'])assert(spec[name]===undefined||Array.isArray(spec[name]),'Spatial obligation must be an array');
+ assert(['order','absent','ownership','align'].some(k=>spec[k]?.length),'Empty spatial obligation');
  for(const pair of spec.order??[]){
   assert(pair&&Object.keys(pair).length===2&&pair.above&&pair.below,'Order pair required');
   assert.notEqual(spatialTarget(pair.above).key,spatialTarget(pair.below).key,'Order requires distinct targets');
  }
  for(const ref of spec.absent??[])spatialTarget(ref);
+ for(const pair of spec.ownership??[]){
+  assert(pair&&Object.keys(pair).length===2&&pair.parent&&pair.child,'Ownership parent/child required');
+  assert.notEqual(spatialTarget(pair.parent).key,spatialTarget(pair.child).key,'Ownership requires distinct targets');
+ }
+ for(const item of spec.align??[]){
+  assert(item&&Object.keys(item).every(k=>['subject','reference','axis','subjectEdge','referenceEdge','subjectMeasure','offset','designWidth'].includes(k)),'Unknown alignment field');
+  const subject=spatialTarget(item.subject),reference=spatialTarget(item.reference);
+  assert(['x','y'].includes(item.axis),'Alignment axis required');
+  for(const edge of [item.subjectEdge,item.referenceEdge])assert(['start','center','end'].includes(edge),'Alignment edge required');
+  assert(item.subjectMeasure===undefined||['box','text'].includes(item.subjectMeasure),'Unsupported alignment measurement');
+  assert(Number.isFinite(item.offset),'Explicit finite alignment offset required');
+  assert(Number.isFinite(item.designWidth)&&item.designWidth>0,'Positive alignment designWidth required');
+  assert(subject.key!==reference.key||item.subjectMeasure==='text','Self box alignment is not an obligation');
+  assert(item.subjectMeasure!=='text'||!item.subject.carrier||item.subject.carrier==='semantic-root','Text alignment requires semantic root');
+ }
+}
+export function spatialReferences(spec){
+ validateSpatial(spec);
+ return [...(spec.absent??[]),...(spec.order??[]).flatMap(p=>[p.above,p.below]),...(spec.ownership??[]).flatMap(p=>[p.parent,p.child]),...(spec.align??[]).flatMap(p=>[p.subject,p.reference])];
 }

package/tools/modules/minifish/port_wiring.py

@@ -0,0 +1,49 @@
+"""Inspect explicit custom-component template chains from committed product files.
+
+This proves static registration and callback wiring, not data flow or reachability.
+"""
+import json
+import posixpath
+from html.parser import HTMLParser
+
+class Tags(HTMLParser):
+    def __init__(self):
+        super().__init__(convert_charrefs=True);self.rows=[]
+    def handle_starttag(self,tag,attrs):
+        names=[k for k,v in attrs]
+        if len(names)!=len(set(names)):raise ValueError('Duplicate template attributes')
+        self.rows.append((tag,dict(attrs)))
+    def handle_startendtag(self,tag,attrs):self.handle_starttag(tag,attrs)
+
+def inspect_chain(read,product_source_root,chain,callback):
+    if not isinstance(chain,list) or not chain:raise ValueError('Explicit component template chain required')
+    prefix=product_source_root+'/'
+    def safe(name):
+        if not isinstance(name,str) or not name.startswith(prefix) or posixpath.normpath(name)!=name:raise ValueError('Component chain escaped product source root')
+        return name
+    first=None;expected=None;seen=set();files={}
+    def load(name):
+        name=safe(name);raw=read(name);files[name]=raw;return raw.decode()
+    for link in chain:
+        template=safe(link['template']);tag=link['tag']
+        if template in seen:raise ValueError('Cyclic component template chain')
+        seen.add(template)
+        if expected is not None and template!=expected+'.axml':raise ValueError('Template chain skips registered component')
+        if not template.endswith('.axml'):raise ValueError('AXML template required')
+        parsed=Tags();parsed.feed(load(template));parsed.close()
+        rows=[attrs for name,attrs in parsed.rows if name==tag]
+        if len(rows)!=1:raise ValueError('Unique component tag instance required for static binding')
+        if first is None:
+            handler=rows[0].get(callback.lower())
+            if not handler or not handler.isidentifier():raise ValueError('Literal published callback handler required')
+            first={'template':template,'handler':handler}
+        config=json.loads(load(template[:-5]+'.json'))
+        target=config.get('usingComponents',{}).get(tag)
+        if not isinstance(target,str) or not target or '://' in target:raise ValueError('Local registered component required')
+        expected=posixpath.normpath(product_source_root+target if target.startswith('/') else posixpath.join(posixpath.dirname(template),target))
+        safe(expected)
+    product_source=load(expected+'.js')
+    host_stem=first['template'][:-5]
+    try:host_source=load(host_stem+'.ts')
+    except FileNotFoundError:host_source=load(host_stem+'.js')
+    return {**first,'productSource':product_source,'hostSource':host_source,'generatedFile':expected+'.js','files':files}