原生能力与契约只读探针
研究总览 · 2026-09-20
附录 E：能力发现、schema 投影与原始诊断的复现材料。
附录 E：能力发现与契约投影的完整只读探针
Section titled “附录 E：能力发现与契约投影的完整只读探针”环境为 Windows x64、Node 24.19.0、AI SDK 7.0.91、Zod 4.1.8、Ajv 8.20.0，源码基线为 a235a3955f3ea4931e3e5cb55a7f12c164b92fe5。探针直接导入当时本地 dist，未重新构建；源码与构件分别计算 SHA-256，不假设二者已完成构建一致性证明。输入是代码中明确列出的确定性枚举，无随机采样。输出置于 TEMP，不进入产品，也不创建独立 test/spec 套件。
保存下列各段为临时 .mjs 并使用 Node 执行；第一段中的 root 可改为仓库绝对路径，后两段也可通过首个命令行参数传入仓库路径。三段均不调用 provider、不执行几何、不申请权限或提交模型。第一段统计及调用真实 SDK 查询；第二段验证 schema 投影；第三段核对内外输入契约并保存实际诊断与构件身份。原始输出是可丢弃产物，结论见 §16.2、§16.4。
另尝试读取已有本地 MCP 连接：其配置指向的 4185 端口不在监听，返回 MCP_TRANSPORT_ERROR。因此没有取得本轮浏览器/会话级证据；没有把旧凭证重定向到其他端口或创建虚假 grant。原生 catalog.describe 断层保持为源码推论。
E.1 共享 SDK 目录与真实查询
Section titled “E.1 共享 SDK 目录与真实查询”原始脚本 SHA-256：bccfcb68bf96690994820fbe23caea5a90725c76a67fae2cd06395874ab895d8。以下仅统一换行展示。
import fs from 'node:fs';import os from 'node:os';import path from 'node:path';import {createRequire} from 'node:module';import {pathToFileURL} from 'node:url';const root='<workspace-root>';const req=createRequire(pathToFileURL(root+'/packages/aira-cad-tools/package.json'));const {asSchema}=await import(pathToFileURL(req.resolve('ai')));const {exactCadTools}=await import(pathToFileURL(root+'/packages/aira-cad-tools/dist/tools.js'));const contracts=await import(pathToFileURL(root+'/packages/aira-contracts/dist/index.js'));const dir=path.join(os.tmpdir(),'aira-discovery-research-20260920');fs.mkdirSync(dir,{recursive:true});const bytes=x=>Buffer.byteLength(JSON.stringify(x));const catalog=[];for(const [name,t]of Object.entries(exactCadTools)){const schema=await asSchema(t.inputSchema).jsonSchema;catalog.push({name,description:t.description,inputSchema:schema});}fs.writeFileSync(path.join(dir,'sdk-catalog.json'),JSON.stringify(catalog,null,2));const schema=contracts.EXACT_CAD_PLAN_SCHEMA;const definitions=schema.$defs??{};const kinds=schema.properties.steps.items.anyOf.map(x=>x.$ref?definitions[x.$ref.split('/').at(-1)]:x).map(x=>x.properties.kind.const);const projections=[];for(const names of [['hole-array'],['set-parameters'],['finish-edges'],['set-product'],['build-program'],['linear-extrude','hole-array','require-hole-array']]){ const p=contracts.exactCadPlanReference(names); projections.push({kinds:names,found:p?.kinds??[],bytes:p?bytes(p.inputSchema):0,defs:p?Object.keys(p.inputSchema.$defs??{}).length:0}); if(p)fs.writeFileSync(path.join(dir,'projection-'+names.join('_')+'.json'),JSON.stringify(p,null,2));}const queries=[];for(const query of ['','holes','hole-array','equally spaced holes with edge margin','assembly distance','set-product','圆孔等距边距']){ const r=await exactCadTools.aira_library_reference.execute({query,detail:'summary',limit:5},{toolCallId:'research',messages:[]}); fs.writeFileSync(path.join(dir,'query-'+queries.length+'.json'),JSON.stringify(r,null,2)); queries.push({query,bytes:bytes(r),planKinds:r.plan?.kinds??[],entries:r.entries?.map(e=>({id:e.id,kind:e.kind})),total:r.total});}const report={scope:'Read-only isolated execution of current built SDK catalog and real library-reference executor; no browser geometry, no provider calls',node:process.version,catalogBytes:bytes(catalog),tools:catalog.map(t=>({name:t.name,bytes:bytes(t),schemaBytes:bytes(t.inputSchema),descriptionBytes:Buffer.byteLength(t.description??'')})),planKindCount:kinds.length,kinds,fullPlanSchemaBytes:bytes(schema),defs:Object.keys(definitions).length,projections,queries};fs.writeFileSync(path.join(dir,'schema-probe.json'),JSON.stringify(report,null,2));console.log(JSON.stringify(report,null,2));E.2 32 个范围的引用闭包及同输入接受性
Section titled “E.2 32 个范围的引用闭包及同输入接受性”原始脚本 SHA-256：8d559c64e1b84e15b5a7db9d83031e46b3f17e91c799fda5d98d9bf5648a2d9c。以下仅统一换行展示。
import fs from 'node:fs';import os from 'node:os';import path from 'node:path';import {createRequire} from 'node:module';import {pathToFileURL} from 'node:url';import {createHash} from 'node:crypto';import {isDeepStrictEqual as equal} from 'node:util';const root=process.argv[2]??'<workspace-root>';const req=createRequire(pathToFileURL(root+'/packages/aira-contracts/package.json'));const Ajv=(await import(pathToFileURL(req.resolve('ajv/dist/2020.js')))).default;const c=await import(pathToFileURL(root+'/packages/aira-contracts/dist/index.js'));const full=c.EXACT_CAD_PLAN_SCHEMA;const resolve=v=>v.$ref?full.$defs[v.$ref.slice('#/$defs/'.length)]:v;const variants=full.properties.steps.items.anyOf;const kinds=[...new Set(variants.map(v=>resolve(v).properties.kind.const))];const scopes=[...kinds.map(k=>[k]),['linear-extrude','hole-array','require-hole-array'],kinds];const erase=s=>{const x=structuredClone(s);delete x.$defs;delete x.properties.steps.items;return x;};const proofChecks=[];for(const names of scopes){ const p=c.exactCadPlanReference(names).inputSchema; const expected=variants.filter(v=>names.includes(resolve(v).properties.kind.const)); const checks={sameRoot:equal(erase(p),erase(full)),sameVariants:equal(p.properties.steps.items.anyOf,expected),sameDefinitions:true,resolvedReferences:true}; for(const [k,v]of Object.entries(p.$defs))checks.sameDefinitions&&=equal(v,full.$defs[k]); const walk=v=>{if(!v||typeof v!=='object')return;if(v.$ref)checks.resolvedReferences&&=v.$ref.startsWith('#/$defs/')&&Object.hasOwn(p.$defs,v.$ref.slice('#/$defs/'.length));for(const x of Object.values(v))walk(x);}; walk(p);if(!Object.values(checks).every(Boolean))throw Error(JSON.stringify({names,checks})); proofChecks.push({kinds:names,bytes:Buffer.byteLength(JSON.stringify(p)),checks});}const projection=c.exactCadPlanReference(['hole-array']).inputSchema;const validate=s=>new Ajv({strict:true,allErrors:true}).compile(s);const vFull=validate(full),vSmall=validate(projection);const envelope=steps=>({version:full.properties.version.const,requestId:'research-projection',summary:'Change only the requested hole drivers. Keep all other design requirements unchanged.',steps});const edit={kind:'hole-array',featureId:'n:holes',edits:{diameter:8}};const layout={kind:'hole-array',bodyId:'b:plate',layout:{diameter:6,x:{count:4,minimumGap:3,rule:{kind:'fixed-centers',first:-30,last:30}},y:{count:2,minimumGap:3,rule:{kind:'fixed-centers',first:-8,last:8}}}};const samples=[ ['edit-literal',edit],['edit-binding',{...edit,edits:{diameter:{parameter:'p:diameter'}}}],['create-layout',layout], ['negative-diameter',{...edit,edits:{diameter:-1}}],['empty-edit',{...edit,edits:{}}],['missing-feature',{kind:'hole-array',edits:{diameter:8}}], ['invented-coordinate',{...edit,centres:[]}],['both-modes',{...layout,featureId:'n:holes',edits:{diameter:8}}], ['fractional-count',{...edit,edits:{columns:1.5}}],['wrong-unit-object',{...edit,edits:{diameter:{value:8,unit:'mm'}}}],];const results=samples.map(([name,step])=>{const input=envelope([step]);const a=vFull(input),b=vSmall(input);return {name,input,fullAccepted:a,projectedAccepted:b,agree:a===b};});const report={scope:'Isolated JSON Schema projection checks only. No geometry execution, state binding, permissions, AI behavior, or semantic custom validator equivalence asserted.',node:process.version,ajv:req('ajv/package.json').version,uniqueKinds:kinds.length,scopesChecked:proofChecks.length,proofChecks,results};if(results.some(r=>!r.agree))throw Error('projection disagreement');if(results.some((r,i)=>r.fullAccepted!==(i<3)))throw Error('unexpected fixture acceptance');report.hashes=Object.fromEntries(['packages/aira-contracts/src/exact-cad-plan-validator.ts','packages/aira-contracts/dist/exact-cad-plan-validator.js','packages/aira-contracts/dist/exact-cad-plan-schema/plan-schema.js','packages/aira-cad-tools/dist/tools.js'].map(p=>[p,createHash('sha256').update(fs.readFileSync(path.join(root,p))).digest('hex')]));const out=path.join(os.tmpdir(),'aira-discovery-research-20260920','projection-check.json');fs.mkdirSync(path.dirname(out),{recursive:true});fs.writeFileSync(out,JSON.stringify(report,null,2));console.log(JSON.stringify({out,node:report.node,ajv:report.ajv,uniqueKinds:report.uniqueKinds,scopesChecked:report.scopesChecked,results:results.map(({input,...r})=>r),hashes:report.hashes},null,2));E.3 18 个输入的实际 SDK 校验与原始诊断
Section titled “E.3 18 个输入的实际 SDK 校验与原始诊断”原始脚本 SHA-256：a44364dbedc476dd22b3093bbe246e6e09ea59b665b7de4e0159714dafd0c49e。以下仅统一换行展示。
import fs from 'node:fs';import path from 'node:path';import os from 'node:os';import crypto from 'node:crypto';import { createRequire } from 'node:module';import { pathToFileURL, fileURLToPath } from 'node:url';
// No provider, model session, geometry evaluator, network request, or product write is used.const repo = path.resolve(process.argv[2] ?? '<workspace-root>');const outPath = path.resolve(process.argv[3] ?? path.join(path.dirname(fileURLToPath(import.meta.url)), 'interface-contract-audit.json'));const pkgDir = path.join(repo, 'packages/aira-cad-tools');const req = createRequire(path.join(pkgDir, 'package.json'));const contractReq = createRequire(path.join(repo, 'packages/aira-contracts/package.json'));const { exactCadTools } = await import(pathToFileURL(path.join(pkgDir, 'dist/tools.js')).href);const { exactCadPlanReference, EXACT_CAD_PLAN_SCHEMA } = await import(pathToFileURL(path.join(repo, 'packages/aira-contracts/dist/index.js')).href);const { asSchema } = await import(pathToFileURL(req.resolve('ai')).href);const { default: Ajv2020 } = await import(pathToFileURL(contractReq.resolve('ajv/dist/2020.js')).href);const hash = value => crypto.createHash('sha256').update(value).digest('hex');const sdkRead = asSchema(exactCadTools.aira_model_read.inputSchema);const sdkPlan = asSchema(exactCadTools.aira_compile_exact_plan.inputSchema);const planSubset = exactCadPlanReference(['set-product']).inputSchema;const subsetValidate = new Ajv2020({allErrors: true, strict: true}).compile(planSubset);const serializeError = err => err ? {name:err.name, message:err.message, ...(err.issues ? {issues:err.issues}:{}), ...(err.cause ? {cause:serializeError(err.cause)}:{})} : null;
const readInputs = [ ['empty-read', {}], ['resources-boolean-from-step-schema', {resources:true}], ['resources-empty-object', {resources:{}}], ['resources-media-type', {resources:{mediaType:'model/step'}}], ['unsupported-morph', {morph:{}}], ['unsupported-minds-eye', {mindsEye:{}}], ['unsupported-assembly-plan', {assemblyPlan:{}}],];const readCases=[];for (const [name,input] of readInputs) { const result=await sdkRead.validate(input); const zod=exactCadTools.aira_model_read.inputSchema.safeParse(input); if (result.success !== zod.success) throw new Error(`SDK/Zod validation disagreement: ${name}`); readCases.push({name,input,acceptedByActualSdkSchema:result.success,error:result.success?null:serializeError(result.error),issues:zod.success?[]:zod.error.issues.map(({code,path,message,...details})=>({code,path,message,details}))});}const p=(component,x,y,z)=>({...component?{component}:{},coordinates:{x,y,z}});const baseline={version:EXACT_CAD_PLAN_SCHEMA.properties.version.const,requestId:'readonly.contract.audit',summary:'Schema-only experiment. Compare relation vocabulary against the exact current SDK input contract.',steps:[{kind:'set-product',product:{root:{assembly:'asm.main'},assemblies:{'asm.main':{components:{moving:{definition:{body:'body.moving'},placement:{translation:{x:0,y:0,z:0},rotation:{x:0,y:0,z:0}}}},solve:{unknownComponents:['moving'],relations:{position:{kind:'coincident',a:p('moving',0,0,0),b:p(null,0,0,0)},axisX:{kind:'coincident',a:p('moving',1,0,0),b:p(null,1,0,0)},axisY:{kind:'coincident',a:p('moving',0,1,0),b:p(null,0,1,0)}},tolerance:0.001,solutionPolicy:'isolated-from-placement'}}}}}]};const planInputs=[['baseline-coincident',structuredClone(baseline)]];for (const kind of ['distance','revolute','prismatic','cylindrical','gear','axial','coplanar']) { const input=structuredClone(baseline); const relation=input.steps[0].product.assemblies['asm.main'].solve.relations.position; relation.kind=kind; if(kind==='distance') relation.distance=1; planInputs.push([`relation-${kind}`,input]);}for (const field of ['driveAngleRad','driveOffset']) { const input=structuredClone(baseline); input.steps[0].product.assemblies['asm.main'].solve.relations.position[field]=0; planInputs.push([`extra-${field}`,input]);}{ const input=structuredClone(baseline); delete input.steps[0].product.assemblies['asm.main'].solve.solutionPolicy; planInputs.push(['omitted-solution-policy-from-compact-signature',input]);}const planCases=[];for (const [name,input] of planInputs) { const result=await sdkPlan.validate(input); const subsetAccepted=subsetValidate(input); if (result.success !== subsetAccepted) throw new Error(`SDK/subset validation disagreement: ${name}`); const issues=structuredClone(subsetValidate.errors??[]).map(({keyword,instancePath,schemaPath,params,message})=>({code:keyword,path:instancePath,schemaPath,params,message})); planCases.push({name,input,acceptedByActualSdkSchema:result.success,sdkError:result.success?null:serializeError(result.error),sameAcceptanceByDerivedSubsetSchema:subsetAccepted===result.success,derivedSubsetIssues:issues});}const lookups=[];for (const query of ['hole-array','hole array','hole','layout','assembly','set-product']) { const output=await exactCadTools.aira_library_reference.execute({query,limit:5},{toolCallId:'readonly.contract.audit',messages:[]}); lookups.push({input:{query,limit:5},output});}const files=[ 'packages/aira-cad-tools/package.json', 'packages/aira-cad-tools/src/tools.ts','packages/aira-cad-tools/dist/tools.js', 'packages/aira-cad-tools/src/model-read-tool.ts','packages/aira-cad-tools/dist/model-read-tool.js', 'packages/aira-cad-tools/src/exact-cad-plan-tool.ts','packages/aira-cad-tools/dist/exact-cad-plan-tool.js', 'packages/aira-cad-tools/src/library-reference-tool.ts','packages/aira-cad-tools/dist/library-reference-tool.js', 'packages/aira-contracts/package.json', 'packages/aira-contracts/src/exact-cad-plan-validator.ts','packages/aira-contracts/dist/exact-cad-plan-validator.js', 'packages/aira-contracts/schema/amir-core-v0.4.schema.json', 'packages/aira-contracts/schema/exact-hole-array-node.schema.json', 'apps/web/src/ai/step/decision-schema.ts','apps/web/src/ai/step/decision-signatures.ts', 'apps/web/src/ai/step/capsule/step-index.ts', 'apps/web/src/ai/step/executor/decision-executor.ts','apps/web/src/ai/step/executor/tool-runner.ts', 'apps/web/src/interface/exact-operation-native-interface/native-interface.ts', 'pnpm-lock.yaml'];for(const dir of ['packages/aira-contracts/src/exact-cad-plan-schema','packages/aira-contracts/dist/exact-cad-plan-schema']) { for(const f of fs.readdirSync(path.join(repo,dir))) if(/\.(ts|js)$/.test(f)) files.push(`${dir}/${f}`);}const fileManifest=files.sort().map(relativePath=>{ const absolutePath=path.join(repo,relativePath);const bytes=fs.readFileSync(absolutePath);const stat=fs.statSync(absolutePath); return {relativePath,absolutePath,sha256:hash(bytes),byteLength:bytes.length,lastModifiedUtc:stat.mtime.toISOString()};});const resolvedDependencies={};for(const [name,resolver] of [['ai',req],['zod',req],['ajv',contractReq]]) { const entry=resolver.resolve(name); let dir=path.dirname(entry); while(dir!==path.dirname(dir)) { const candidate=path.join(dir,'package.json'); if(fs.existsSync(candidate)) { const meta=JSON.parse(fs.readFileSync(candidate,'utf8')); if(meta.name===name) {resolvedDependencies[name]={version:meta.version,entry,packageJson:candidate,packageJsonSha256:hash(fs.readFileSync(candidate))};break;} } dir=path.dirname(dir); }}const packages={};for(const rel of ['packages/aira-cad-tools/package.json','packages/aira-contracts/package.json','packages/aira-geometry-kernel/package.json']) { const p=JSON.parse(fs.readFileSync(path.join(repo,rel),'utf8'));packages[p.name]={version:p.version,dependencies:p.dependencies};}const report={ experiment:'Current built Aira SDK input contracts, schema acceptance only', timestampUtc:new Date().toISOString(),repo,environment:{node:process.version,platform:process.platform,arch:process.arch,osRelease:os.release()},packages,resolvedDependencies, artifacts:{scriptPath:fileURLToPath(import.meta.url),scriptSha256:hash(fs.readFileSync(fileURLToPath(import.meta.url))),outputPath:outPath}, schemaIdentity:{planVersion:baseline.version,fullPlanSchemaSha256:hash(JSON.stringify(EXACT_CAD_PLAN_SCHEMA)),readSchemaSha256:hash(JSON.stringify(sdkRead.jsonSchema)),setProductSubsetSha256:hash(JSON.stringify(planSubset)),planSchemaChars:JSON.stringify(EXACT_CAD_PLAN_SCHEMA).length,readSchemaChars:JSON.stringify(sdkRead.jsonSchema).length}, method:{read:'Actual AI SDK asSchema(tool.inputSchema).validate plus the identical Zod input safeParse for structured error paths.',plan:'Actual AI SDK tool validator plus Ajv 2020-12 on exactCadPlanReference([set-product]) for structured error codes and paths; all acceptance results cross-checked.',catalog:'Only existing libraryReferenceTool.execute is called. Native interface describe is not invoked; no mock session or fabricated permission grant is created.'}, limits:[ 'No provider, external model, network, geometry evaluation, model read, candidate creation, commit, or permission grant is involved.', 'Plan baseline is schema-valid only. body.moving is a syntactic example ID; no document exists and reference resolution, pose solvability, rank, geometry, semantic assertions, or transactions are tested.', 'Distance case is a schema acceptance control, not a solved consistent assembly; other baseline relations are intentionally retained.', 'Ajv detailed issues are from the canonical derived set-product subset; actual SDK reports its own condensed message without structured paths. Both acceptance results must agree.', 'Source and dist files are fingerprinted separately. Runtime imports use current on-disk dist and shared schema JSON; no rebuild is performed.', 'Lookup outputs do not establish AI discovery success or token costs. Native describe mismatch remains source-backed inference, not an invoked native interface observation.' ],readCases,planCases,lookups,fileManifest};fs.writeFileSync(outPath,JSON.stringify(report,null,2)+'\n');console.log(JSON.stringify({outputPath:outPath,scriptPath:fileURLToPath(import.meta.url),scriptSha256:report.artifacts.scriptSha256,outputSha256:hash(fs.readFileSync(outPath)),readCases:readCases.map(c=>({name:c.name,accepted:c.acceptedByActualSdkSchema,issues:c.issues})),planCases:planCases.map(c=>({name:c.name,accepted:c.acceptedByActualSdkSchema,issues:c.derivedSubsetIssues.filter(e=>!['oneOf','anyOf'].includes(e.code)).map(({code,path,params})=>({code,path,params}))})),fileManifestCount:fileManifest.length},null,2));