@antprofuse/saddle-islands-tools 0.1.4 → 0.1.6

package/package.json

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

package/tools/docs/iteration.md

@@ -1,34 +1,63 @@
-# 迭代节点渲染
+# 迭代管理与阶段交付
 
-通过独立工具集消费冻结的workflow Skill参数schema和阶段元数据，不直接调用CoTask，也不启动任务。
+统一公开入口：`python3 tools/cli/main.py iteration <action>`。所有能力只管理文件、校验与渲染，不调用CoTask、不授予启动许可。以下绝对路径为调用方提供的实际位置。
+
+## 持久元数据
+
+发起者填写workflow包 `resources/iteration.schema.json` 定义的v2实例。`persistentRoot` 必须等于 `--registry/<iteration.id>`，不得位于临时共享根内。Skill及工具定位、来源版本等元数据不全量注入执行者。
+
+```bash
+python3 tools/cli/main.py iteration init --registry /workspace/iterations \
+  --input /workspace/prepared-meta.json --workflow /packages/workflow
+python3 tools/cli/main.py iteration list --registry /workspace/iterations
+python3 tools/cli/main.py iteration update --registry /workspace/iterations \
+  --input /workspace/updated-meta.json --workflow /packages/workflow \
+  --expected-sha256 <current-metadata-sha256>
+```
+
+init拒绝覆盖。update校验当前摘要、保旧元数据历史，再原子替换元数据和刷新索引。操作以目录锁串行；单文件写入原子，多文件不构成数据库事务，索引可由list扫描真实元数据恢复。list只读现有台账，不要求已结束任务的临时共享区仍存在。更新完整元数据须通过schema与结构校验，但不要求已回收的共享区仍存在；不能靠改变状态自动放行任务。
+
+工具支持随包schema使用的受限JSON Schema词汇；未知字段和未知校验关键词拒绝。还核绝对/相对路径、独立持久位置、写入范围、记录输入禁止、分支名、阶段ID与依赖环。渲染成功不证明分支已推送、全部输入实际可读或业务已通过；Owner须在放行前确认。
+
+## 任务渲染
 
 ```bash
-python3 tools/cli/main.py iteration render \
-  --workflow /absolute/path/to/workflow-skill \
-  --input /absolute/path/to/iteration.json \
-  --output /absolute/path/to/new-review.json
+python3 tools/cli/main.py iteration render --workflow /packages/workflow \
+  --input /workspace/iterations/example/iteration.meta.json --output /workspace/rendered.json
 ```
 
-输入结构见workflow包的 `resources/iteration.schema.json`，固定阶段规则见 `resources/stage-meta.json`。发起者冻结Skill版本后填写实例；阶段实例不允许覆盖全局git或bizdir。`sharedOutput` 相对全局共享根，正式输出目录与单文件权限由阶段元数据派生，非用户手填。
+生成公共及执行/检查点Markdown，还有结构化Git权限与依赖。使用context原文，不把JSON塞进任务正文。不覆盖已有输出。localInputs/localOutputs按内容分配，可多个；recordDirectory只写执行记录，不能被其他阶段列为输入。inputCommit允许草稿阶段暂缺，交接后须绑定精确提交。
 
-输出JSON包含公共上下文和各执行节点的Markdown正文，以及供目录门禁消费的结构化路径权限。调用方使用 `context` 原文更新节点，不能把整个JSON塞进节点说明。不会覆盖已有输出文件。未知参数、缺失必填值、共享根不存在、重复ID/工作分支、共享路径重叠或逃逸、未解析占位符都以非零退出拒绝。
+## 阶段门禁
 
-目前是启动前审阅渲染：`acceptedInput` 可指向等待上游检查点生成的登记文件；`inputCommit` 在检查点接受成果后绑定。渲染成功不表示后续分支、输入文件或运行环境已准备完毕，也不授予执行许可。输出还包含阶段检查点及最终检查点的Markdown；工具不自动构建依赖图或调用平台。
+Owner生成阶段最小配置并通过执行环境索引提供：
+
+```bash
+python3 tools/cli/main.py iteration scope --workflow /packages/workflow \
+  --input /workspace/iterations/example/iteration.meta.json --stage-id D \
+  --output /shared/environment/scopes/design.json
+```
+
+执行者无需访问Owner元数据，只读取该冻结范围文件：
+
+```bash
+python3 tools/cli/main.py iteration stage-gate --workflow /packages/workflow \
+  --input /shared/environment/scopes/design.json --repository /work/business \
+  --head <full-candidate-commit> --output /shared/execution-records/design/gate.md
+```
 
-本工具对随Skill schema使用的受限JSON Schema关键字执行校验，不冒充通用JSON Schema实现；未知关键字拒绝，不静默忽略。Git差异目录门禁见下。
+范围来自stage类型及冻结stage-meta，基线使用scope.inputCommit；scope不接受任意路径白名单。scope必须经Owner准备并冻结，门禁本身不验证分发者身份。公开工具只读Git，比较基线至候选；不扫描未提交内容、不自动推送。完整提交、祖先关系和路径权限通过返回0，越界返回3并输出差异Markdown，读取或参数错误返回2。重命名检查两端，空diff允许。未提交修改仍须按Skill处理，不能仅有门禁绿就声称完整交付。
 
+Owner集成审阅仍可用 `iteration diff-review --input <meta> --workflow <package> --repository <repo> --base <sha> --head <sha> --stage-id D [--stage-id MT] --output <new.md>` 检查已接受阶段权限并集。它只检查路径，不扩展成内容或文件类型门禁。
 
-## Git目录门禁
+## 报告与记录归档
 
 ```bash
-python3 tools/cli/main.py iteration diff-review \
-  --workflow /absolute/path/to/workflow-skill \
-  --input /absolute/path/to/iteration.json \
-  --repository /absolute/path/to/business-checkout \
-  --base <full-base-commit> --head <full-candidate-commit> \
-  --stage-id D --output /absolute/path/to/new-diff-review.md
+python3 tools/cli/main.py iteration archive \
+  --input /workspace/iterations/example/iteration.meta.json \
+  --source /shared/report-content --kind reports --name minifish-r1
 ```
 
-基线须为候选的祖先，两个端点必须是完整提交ID。范围来自同一实例参数和冻结阶段元数据，不接受手填任意白名单。集成交付可重复传 `--stage-id` 检查已接受阶段范围的并集。退出0表示路径检查通过，3表示有越界路径（仍写出审阅报告），2表示参数或读取错误。只读Git，不暂存、不修改、不提交。
+`kind`为reports或records。目标在持久迭代目录下，以新内容版本命名，不覆盖原件。逐文件摘要校验复制一致，拒绝符号链接，检查静态HTML/CSS引用是否缺失或逃出归档目录；保存归档清单到records/archives。不会生成ZIP，不删除源目录。源需已停止写入；先后摘要不同则拒绝交付。
 
-报告按目标父目录汇总文件变更类型和增删行，列所有变更文件；重命名同时检查源、目标路径，删除不能逃避检查。本门禁只核Git记录的变更路径，不追踪链接目标或增加文件类型门禁。该门禁不判断业务内容是否正确，不扫描未提交内容，也不代替缓存、依赖、报告等产物类型审查。
+不执行或解析JavaScript生成的动态URL、不下载外部HTTP资源，也不证明图片能够解码或预览服务可达。最终检查点须实际打开用户预览链接、检查截图；动态资源在浏览器中核验。服务与持久文件分别管理。结束CoTask前归档并核验，不能结束后才尝试复制已回收文件。

package/tools/docs/minifish-testing.md

@@ -30,3 +30,15 @@ Eight is the public tool default, not a universal hardware optimum. Lower concur
 Both `batch-input.json` and `batch-summary.json` contain `concurrencyPolicy`: `defaultWorkers`, `requestedWorkers`, `actualConcurrency` (effective simultaneous worker upper bound, not a measured peak), `workersReason`, and truthful `shardSizes` including plugin tails. The summary's `concurrency` uses that effective upper bound; its worker records retain every actual shard and lifecycle receipt.
 
 Legacy component-host integrations must supply an explicit `repositoryRoot` to `component_runtime.main(prepare, sourceRoot, projectRoot, repositoryRoot)`. No directory-depth inference is performed. Current case packages use the public `run` or `batch` commands.
+
+### 区域视觉声明
+
+`region` 且 `check: "visual"` 的断言由公共编译器及运行器校验。`visual-expectation.mjs` 公开 `validateVisualExpectation` 和纯函数 `assertVisualMetrics`。声明必须含正数 `designWidth` 和至少一项实际期望；空对象、仅设计宽度、未知键、非有限数值被拒绝，合法零值保留。
+
+支持 `text`（fontSize/fontWeight/color/lineHeight）、`lengths`（padding四边、margin四边、borderRadius、gap/rowGap/columnGap）、`dimensions`（width/height）、`backgroundColor`、`align`，以及 `layout`（position/display/flexDirection/alignItems/justifyContent/overflowX/overflowY/boxSizing）。数值长度以声明的设计宽度换算，字体容差0.02px，几何容差0.25px；布局与颜色按浏览器计算值比较。
+
+运行器在声明的语义载体上独立采集并判定；按压状态使用释放前冻结的原生快照。观察模块的自报成功不能替代公共判定。该合同不证明期望覆盖完整，也不为缺少语义身份的内部部件猜测选择器；这类观察能力须先明确，不能按期望尺寸或颜色挑选能通过的元素。其他断言类别不隐式套用本合同。
+
+可选 `carrier` 默认为 `semantic-root`。`source-content-group` 在语义root内对可见文字/图像取最低公共元素祖先；`owned-text-block` 在该组内要求唯一不属于其他语义目标的文字分支。选择与期待样式、class、原型HTML标签无关，候选缺失或歧义明确失败；不适用的拓扑不得借此猜测观察目标。`viewportInsets` 可声明 left/right/top/bottom 到业务frame视口的设计长度，返回采样记录包含原root盒及是否选中root。
+
+按压快照目前只支持 `semantic-root`，其他carrier在按下前拒绝，不能释放后采样冒充按住状态。这是明确能力限制，不能默默降级。内容分组不覆盖背景装饰/无文字无图像部件或Shadow DOM；相应责任另用适用的公开观察合同。

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

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

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

@@ -1,3 +1,4 @@
+import {validateRegionVisualAssertions} from '../harness/visual-expectation.mjs';
 import assert from 'node:assert/strict';
 import {validateTargetActions} from '../harness/target-actions.mjs';
 function jsonValue(value, path = '$') {
@@ -34,6 +35,7 @@ export function compileCase(catalog, definition, fragments,policy) {
   assert(policy&&typeof policy.validateSemanticTargets==='function','Explicit project plan policy required');
   const {validateSemanticTargets,validateIndependentFixture,validatePacketPlan,validatePluginEvents,validatePluginAssertionIdentity,validateObservationModuleName}=policy;
   jsonValue(definition);
+  validateRegionVisualAssertions(definition.assertions);
   validateSemanticTargets(definition);
   jsonValue(fragments);
   for(const fragment of fragments)validateSemanticTargets(fragment);
@@ -170,6 +172,7 @@ export function compileCase(catalog, definition, fragments,policy) {
 export function renderCaseModule(plan,validateSemanticTargets) {
   assert.equal(typeof validateSemanticTargets,'function','Explicit project source validator required');
   jsonValue(plan);
+  validateRegionVisualAssertions(plan.assertions);
   validateSemanticTargets(plan);
   return `// Generated from miniapp case definitions. Do not edit.\nexport default ${JSON.stringify(plan, null, 2)};\n`;
 }

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

@@ -1,3 +1,4 @@
+import {assertVisualMetrics} from './visual-expectation.mjs';
 import assert from 'node:assert/strict';
 import {sampleNativeMetrics,sampleNativeTextVisibility,sampleNativeStyle,sampleNativePressed,sampleHeldNativeState} from './native-dom-sampling.mjs';
 import {nativeMetricsFrameIdentity} from './independent-visual.mjs';
@@ -53,6 +54,7 @@ export function validateFrozenHeldAssertion(snapshot,a,validators){
  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.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.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};

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

@@ -1,3 +1,4 @@
+import {validateRegionVisualAssertions,assertVisualMetrics} from './visual-expectation.mjs';
 import {hostPolicy} from '@minifish/project-host';
 import {prepareHeldNativeInput,executeHeldSnapshot} from './held-snapshot.mjs';
 import {prepareHeldSnapshot,independentBoundary,assertNativeState,projectAssert,locateProject,queryBoundaryIds,validateReleasedPaymentRows} from '@minifish/project-runtime';
@@ -26,6 +27,7 @@ export const screenshotPolicyVersion = 1;
 function target(root, name) { return semanticLocator(root, name); }
 
 export async function runMiniappCase({page, plan, testInfo}) {
+  validateRegionVisualAssertions(plan.assertions);
   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);
@@ -92,6 +94,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)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 +117,12 @@ export async function runMiniappCase({page, plan, testInfo}) {
         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'){result.observations[assertion.id]=await observation.assertTarget({app,page,assertion,images});
+        }else if(assertion.kind==='region'){
+          result.observations[assertion.id]=await observation.assertTarget({app,page,assertion,images});
+          if(assertion.check==='visual') {
+            const metrics=await nativeMetrics(locator,{carrier:assertion.visual.carrier});
+            result.observations[assertion.id]={...result.observations[assertion.id],publicVisual:assertVisualMetrics(metrics,assertion.visual)};
+          }
         }else if(await projectAssert({root:app.root,assertion,locator,locate,images,result})){
         }else if(['hidden','visible'].includes(assertion.kind)){await assertNativeState(locator,assertion);
         }else if(assertion.kind==='text'){

package/tools/modules/minifish/harness/independent-visual.mjs

@@ -1,3 +1,4 @@
+import {resolveVisualCarrier} from './visual-carrier.mjs';
 import {sampleNativeMetrics} from './native-dom-sampling.mjs';
 import {rendererImageFrameId} from './renderer-image-evidence.mjs';
 import assert from 'node:assert/strict';
@@ -7,9 +8,9 @@ export async function nativeMetricsFrameIdentity(locator) {
  try{const frame=await handle?.ownerFrame();if(frame)frameId=rendererImageFrameId(locator.page(),frame);}finally{await handle?.dispose();}
  return frameId;
 }
-export async function nativeMetrics(locator) {
+export async function nativeMetrics(locator, {carrier='semantic-root'}={}) {
  const frameId=await nativeMetricsFrameIdentity(locator);
- const metrics=await locator.evaluate(sampleNativeMetrics);
+ const metrics=carrier==='semantic-root'?await locator.evaluate(sampleNativeMetrics):await locator.evaluate(Function('return ((root,kind)=>{const resolve='+resolveVisualCarrier.toString()+';const sample='+sampleNativeMetrics.toString()+';const selected=resolve(root,kind);return {...sample(selected),carrierEvidence:{kind,rootBox:sample(root).box,selectedIsRoot:selected===root}};})')(),carrier);
  metrics.frameId=frameId;for(const paint of [...metrics.imagePaints,...metrics.imagePaintInventory])paint.frameId=frameId;return metrics;
 }
 export function near(actual,expected,label,tolerance=.02){assert(Math.abs(actual-expected)<=tolerance,`${label}: ${actual} != ${expected}`);}

package/tools/modules/minifish/harness/native-dom-sampling.mjs

@@ -1,7 +1,7 @@
 // Existing public browser collectors, extracted without changing measured fields.
 export function sampleNativeMetrics(el){
   const s=getComputedStyle(el),r=el.getBoundingClientRect();
-  const styles=Object.fromEntries(['fontFamily','fontSize','fontWeight','lineHeight','color','backgroundColor','borderRadius','paddingLeft','paddingRight','paddingTop','paddingBottom','marginTop','marginBottom','marginLeft','marginRight','backgroundImage','backgroundSize','backgroundRepeat','backgroundPosition','objectFit'].map(k=>[k,s[k]]));
+  const styles=Object.fromEntries(['fontFamily','fontSize','fontWeight','lineHeight','color','backgroundColor','borderRadius','paddingLeft','paddingRight','paddingTop','paddingBottom','marginTop','marginBottom','marginLeft','marginRight','backgroundImage','backgroundSize','backgroundRepeat','backgroundPosition','objectFit','textAlign','position','display','flexDirection','alignItems','justifyContent','overflowX','overflowY','boxSizing','gap','rowGap','columnGap'].map(k=>[k,s[k]]));
   const texts=[],textStyles=[];
   function visit(node){if(node.nodeType===3 && node.textContent.trim()){const range=document.createRange();range.selectNodeContents(node);const ts=getComputedStyle(node.parentElement);textStyles.push(Object.fromEntries(['fontFamily','fontSize','fontWeight','lineHeight','color'].map(k=>[k,ts[k]])));for(const b of range.getClientRects())if(b.width&&b.height)texts.push({x:b.x,y:b.y,width:b.width,height:b.height});}else{for(const c of node.childNodes)visit(c);if(node.shadowRoot)visit(node.shadowRoot);}}
   visit(el);

package/tools/modules/minifish/harness/visual-carrier.mjs

@@ -0,0 +1,44 @@
+/** Browser-side, expectation-independent selection inside one semantic root. */
+export function resolveVisualCarrier(root, kind = 'semantic-root') {
+  if(kind==='semantic-root')return root;
+  if(!['source-content-group','owned-text-block'].includes(kind))throw Error('Unsupported visual carrier');
+  const visible=element=>{
+    for(let p=element;p;p=p.parentElement){const s=getComputedStyle(p);if(s.display==='none'||s.visibility!=='visible'||Number(s.opacity)===0)return false;}
+    return true;
+  };
+  const content=[],texts=[];
+  const walk=node=>{
+    if(node.nodeType===3&&node.textContent.trim()&&visible(node.parentElement)) {
+      const range=node.ownerDocument.createRange();range.selectNodeContents(node);
+      if([...range.getClientRects()].some(r=>r.width>0&&r.height>0)){content.push(node.parentElement);texts.push(node);}
+    } else if(node.nodeType===1) {
+      if(node.shadowRoot)throw Error('Unsupported shadow content carrier topology');
+      if(node.tagName==='IMG'&&visible(node)){const r=node.getBoundingClientRect();if(r.width>0&&r.height>0)content.push(node);}
+      for(const child of node.childNodes)walk(child);
+    }
+  };
+  walk(root);
+  if(!content.length)throw Error('Content carrier requires actual painted text or image');
+  let group=content[0];
+  while(group&& !content.every(n=>group.contains(n)))group=group.parentElement;
+  if(!group||!root.contains(group))throw Error('Content group escaped semantic owner');
+  if(kind==='source-content-group')return group;
+  const branches=new Set();
+  for(const text of texts) {
+    let owned=true;
+    for(let p=text.parentElement;p&&p!==root;p=p.parentElement){
+      const path=p.$$dataset?.anchorId??p.getAttribute('data-anchor-id');
+      if(path){owned=false;break;}
+    }
+    if(!owned)continue;
+    let branch=text.parentElement;
+    if(branch===group)throw Error('Owned text has no distinct block');
+    while(branch.parentElement!==group)branch=branch.parentElement;
+    branches.add(branch);
+  }
+  if(branches.size!==1)throw Error('Owned text block missing or ambiguous');
+  const block=[...branches][0];
+  // Do not let an unanchored wrapper make text belonging to other targets owned.
+  for(const n of block.querySelectorAll('*'))if(n.$$dataset?.anchorId||n.getAttribute('data-anchor-id'))throw Error('Owned text block contains another semantic target');
+  return block;
+}

package/tools/modules/minifish/harness/visual-expectation.mjs

@@ -0,0 +1,79 @@
+import assert from 'node:assert/strict';
+
+const lengths = new Set(['paddingLeft','paddingRight','paddingTop','paddingBottom','marginLeft','marginRight','marginTop','marginBottom','borderRadius','gap','rowGap','columnGap']);
+const layout = new Set(['position','display','flexDirection','alignItems','justifyContent','overflowX','overflowY','boxSizing']);
+const top = new Set(['designWidth','text','lengths','dimensions','backgroundColor','align','layout','carrier','viewportInsets']);
+function object(value, name) {
+  assert(value && Object.getPrototypeOf(value) === Object.prototype, `${name}: object required`);
+}
+function number(value, name) { assert(typeof value === 'number' && Number.isFinite(value), `${name}: finite number required`); }
+function string(value, name) { assert(typeof value === 'string' && value.trim(), `${name}: nonempty string required`); }
+function keys(value, allowed, name, validate) {
+  object(value,name);
+  for (const [key,item] of Object.entries(value)) {
+    assert(allowed.has(key), `${name}: unsupported ${key}`);
+    validate(item, `${name}.${key}`);
+  }
+  return Object.keys(value).length;
+}
+
+/** Validates declarations, not whether the source obligations are sufficiently covered. */
+export function validateVisualExpectation(value) {
+  object(value,'visual');
+  for (const key of Object.keys(value)) assert(top.has(key), `visual: unsupported ${key}`);
+  number(value.designWidth,'visual.designWidth');
+  assert(value.designWidth > 0,'visual.designWidth must be positive');
+  if(value.carrier!==undefined)assert(['semantic-root','source-content-group','owned-text-block'].includes(value.carrier),'visual: unsupported carrier');
+  let checks = 0;
+  if(value.viewportInsets!==undefined)checks+=keys(value.viewportInsets,new Set(['left','right','top','bottom']),'visual.viewportInsets',number);
+  if (value.text !== undefined) {
+    checks += keys(value.text,new Set(['fontSize','fontWeight','color','lineHeight']),'visual.text',(v,k)=>k.endsWith('.color')?string(v,k):number(v,k));
+  }
+  if (value.lengths !== undefined) checks += keys(value.lengths,lengths,'visual.lengths',number);
+  if (value.dimensions !== undefined) checks += keys(value.dimensions,new Set(['width','height']),'visual.dimensions',number);
+  if (value.layout !== undefined) checks += keys(value.layout,layout,'visual.layout',string);
+  for (const key of ['backgroundColor','align']) if (value[key] !== undefined) { string(value[key],`visual.${key}`); checks++; }
+  assert(checks > 0,'visual: at least one substantive expectation required');
+  return value;
+}
+
+function near(actual,expected,tolerance,label) {
+  number(actual,label);
+  assert(Math.abs(actual-expected)<=tolerance,`${label}: ${actual} != ${expected}`);
+}
+function pixels(value,label) {
+  assert(typeof value==='string' && /^-?(?:\d+(?:\.\d*)?|\.\d+)px$/.test(value),`${label}: resolved px required`);
+  return Number(value.slice(0,-2));
+}
+
+/** Pure public predicate. Metrics must be sampled from the declared semantic carrier. */
+export function assertVisualMetrics(metrics, expectation) {
+  const v=validateVisualExpectation(expectation), m=metrics;
+  assert(m?.box && m?.viewport && m?.styles,'visual: native metrics required');
+  number(m.viewport.width,'viewport.width');assert(m.viewport.width>0,'positive viewport width required');
+  number(m.box.width,'box.width');number(m.box.height,'box.height');
+  assert(m.box.width>0&&m.box.height>0,'visual: painted carrier required');
+  const unit=m.viewport.width/v.designWidth;
+  for(const [side,value] of Object.entries(v.viewportInsets??{})) {
+    const actual=side==='left'?m.box.x:side==='top'?m.box.y:side==='right'?m.viewport.width-m.box.x-m.box.width:m.viewport.height-m.box.y-m.box.height;
+    near(actual,value*unit,.25,`visual.viewportInsets.${side}`);
+  }
+  if(v.text && Object.keys(v.text).length) {
+    assert(m.texts?.length&&m.textStyles?.length,'visual: actual text paint required');
+    for(const style of m.textStyles) for(const [key,value] of Object.entries(v.text)) {
+      if(key==='color') assert.equal(style.color,value,'visual.text.color');
+      else if(key==='fontWeight') {assert(style.fontWeight!==''&&style.fontWeight!=null,'fontWeight required');assert.equal(Number(style.fontWeight),value,'visual.text.fontWeight');}
+      else near(pixels(style[key],key),value*unit,.02,`visual.text.${key}`);
+    }
+  }
+  for(const [key,value] of Object.entries(v.lengths??{})) near(pixels(m.styles[key],key),value*unit,.25,`visual.lengths.${key}`);
+  for(const [key,value] of Object.entries(v.dimensions??{})) near(m.box[key],value*unit,.25,`visual.dimensions.${key}`);
+  for(const [key,value] of Object.entries(v.layout??{})) assert.equal(m.styles[key],value,`visual.layout.${key}`);
+  if(v.backgroundColor!==undefined) assert.equal(m.styles.backgroundColor,v.backgroundColor,'visual.backgroundColor');
+  if(v.align!==undefined) assert.equal(m.styles.textAlign,v.align,'visual.align');
+  return {checks:'passed',expectation:v,metrics:m};
+}
+
+export function validateRegionVisualAssertions(assertions) {
+  for(const a of assertions??[]) if(a.kind==='region'&&a.check==='visual') validateVisualExpectation(a.visual);
+}

package/tools/modules/workflow/iteration.py

@@ -57,119 +57,192 @@ def branch(value):
         raise Invalid('Invalid branch name: ' + value)
 
 
-def render(config, workflow):
+def render(config, workflow, require_shared=True):
     workflow = Path(workflow)
-    schema = json.loads((workflow / 'resources/iteration.schema.json').read_text())
+    validate(config, json.loads((workflow / 'resources/iteration.schema.json').read_text()))
     meta = json.loads((workflow / 'resources/stage-meta.json').read_text())
-    validate(config, schema)
     if meta['version'] != config['metaVersion']:
         raise Invalid('Stage metadata version mismatch')
-    relative(config['bizdir'])
-    branch(config['git']['branch'])
-    # Operational input paths are explicit absolute paths, not cwd-relative guesses.
-    for value in [config['persistentDeliveryDirectory'], config['sharedRoot'], config['source']['root'], config['skillsRoot'], config['toolsRoot'], config['frameworkSkill'], *config['generated'].values()]:
-        if not Path(value).is_absolute():
-            raise Invalid('Expected absolute operational input path: ' + value)
-    shared = Path(config['sharedRoot']).resolve(strict=True)
-    if not shared.is_dir():
-        raise Invalid('Shared root must exist as a directory')
-    def field(label, value):
-        return f'- {label}：`{value}`'
-    def expand(template, params):
-        def get(match):
-            value = params
-            for key in match.group(1).split('.'):
-                if not isinstance(value, dict) or key not in value:
-                    raise Invalid('Unknown template parameter: ' + match.group(1))
-                value = value[key]
-            if not isinstance(value, str):
-                raise Invalid('Template value must be a string')
-            return value
-        result = re.sub(r'\{([A-Za-z][A-Za-z0-9_.]*)\}', get, template)
-        if '{' in result or '}' in result:
-            raise Invalid('Unresolved template parameter')
-        return result
-    nodes, ids, branches, outputs = [], set(), set(), []
+    relative(config['bizdir']); branch(config['git']['branch'])
+    def absolute(value):
+        p = Path(value)
+        if not p.is_absolute() or '..' in p.parts:
+            raise Invalid('Expected normalized absolute path: ' + value)
+        return p.resolve()
+    shared = absolute(config['sharedRoot'])
+    if require_shared and not shared.is_dir():
+        raise Invalid('Shared root must exist')
+    persistent = absolute(config['persistentRoot'])
+    if persistent == shared or persistent.is_relative_to(shared) or shared.is_relative_to(persistent):
+        raise Invalid('Persistent iteration storage must be independent of temporary shared storage')
+    absolute(config['source']['root']); absolute(config['environmentIndex'])
+    for artifact in config['provenance']:
+        absolute(artifact['path'])
+    def field(k, v): return f'- {k}：`{v}`'
+    def local(k, v): return field(k, 'localPath:' + v)
+    records = shared / config['bizdir'] / 'execution-records'
+    nodes, ids, branches, writes = [], set(), set(), []
+    def output_path(value):
+        p = absolute(value)
+        if p == shared or not p.is_relative_to(shared):
+            raise Invalid('Shared output escapes its root')
+        if any(p == old or p.is_relative_to(old) or old.is_relative_to(p) for old in writes):
+            raise Invalid('Overlapping shared writers')
+        writes.append(p)
+        return p
     for stage in config['stages']:
         if stage['id'] in ids or stage['workBranch'] in branches:
             raise Invalid('Duplicate stage ID or work branch')
         ids.add(stage['id']); branches.add(stage['workBranch']); branch(stage['workBranch'])
-        relative(stage['sharedOutput'])
-        output = (shared / stage['sharedOutput']).resolve()
-        if not output.is_relative_to(shared) or output == shared:
-            raise Invalid('Shared output escapes its root')
-        if any(output == old or output.is_relative_to(old) or old.is_relative_to(output) for old in outputs):
-            raise Invalid('Overlapping shared output directories')
-        outputs.append(output)
-        if not Path(stage['acceptedInput']).is_absolute():
-            raise Invalid('Accepted input registry must be an absolute path')
+        rec = output_path(stage['recordDirectory'])
+        if rec == records or not rec.is_relative_to(records):
+            raise Invalid('Execution records must be inside the business execution-records area')
+        for item in stage['localInputs']:
+            p = absolute(item['path'])
+            if p == records or p.is_relative_to(records) or records.is_relative_to(p):
+                raise Invalid('Execution records cannot be a stage input')
+        for item in stage['localOutputs']:
+            p = output_path(item['path'])
+            if p == records or p.is_relative_to(records):
+                raise Invalid('Use recordDirectory for execution records')
         m = meta['stages'][stage['stage']]
-        params = {**config, **stage}
-        directories = [expand(v, params) for _, v in m['outputDirectories']]
-        files = [expand(v, params) for _, v in m['outputFiles']]
-        for p in directories + files:
-            if not relative(p).is_relative_to(relative(config['bizdir'])) or p == config['bizdir']:
+        def expand(value):
+            value = value.replace('{bizdir}', config['bizdir'])
+            if '{' in value or '}' in value:
+                raise Invalid('Unknown path placeholder')
+            if not relative(value).is_relative_to(relative(config['bizdir'])) or value == config['bizdir']:
                 raise Invalid('Output outside business directory')
-        lines = ['### 输入', '', field('工作分支', stage['workBranch'])] + [field(k, 'localPath:' + expand(v, params)) for k, v in m['inputs']]
-        if 'inputCommit' in stage:
-            lines.append(field('阶段输入提交', stage['inputCommit']))
-        if 'group' in stage:
-            lines.append(field('业务分组', stage['group']))
-        lines += ['', '### 执行', '', f'使用 `{m["skill"]}` 完成{m["label"]}阶段。', '',
-                  field('Skill入口', config['skillsRoot'] + '/' + stage['stage'] + '/SKILL.md'), '', '### 交付', '']
-        lines += [field(k, 'gitBranchPath:' + expand(v, params)) for k, v in m['outputDirectories'] + m['outputFiles']]
-        lines.append(field('任务信息目录', 'localPath:' + str(output)))
-        lines += ['', meta['gitDeliveryInstruction'], '', field(meta['deliveryGate']['label'], meta['deliveryGate']['command']), '', meta['deliveryGate']['scope']]
+            return value
+        directories = [expand(v) for _, v in m['outputDirectories']]
+        files = [expand(v) for _, v in m['outputFiles']]
+        lines = ['### 输入', '', field('工作分支', stage['workBranch'])]
+        lines += [local(i['label'], i['path']) for i in stage['localInputs']]
+        if 'group' in stage: lines.append(field('业务分组', stage['group']))
+        lines += ['', '### 执行', '', f'使用 Skill `{m["skill"]}` 完成{m["label"]}。', '', '### 交付', '']
+        lines += [field(k, 'gitBranchPath:' + expand(v)) for k, v in m['outputDirectories'] + m['outputFiles']]
+        lines += [local(i['label'], i['path']) for i in stage['localOutputs']]
+        lines.append(local('任务执行记录目录', stage['recordDirectory']))
         nodes.append({'id':stage['id'], 'stage':stage['stage'], 'context':'\n'.join(lines),
                       'workBranch':stage['workBranch'], 'outputDirectories':directories,
-                      'outputFiles':files, 'sharedOutput':str(output)})
-    common = '\n'.join(['### 全局参数', ''] + [field(k, v) for k, v in [
-        ('Git仓库',config['git']['url']), ('基线分支',config['git']['branch']), ('基线提交',config['git']['commit']),
-        ('业务目录',config['bizdir']), ('业务源版本',config['source']['commit']), ('业务源根目录',config['source']['root']),
-        ('共享根目录',str(shared)), ('Skill根目录',config['skillsRoot']), ('工具目录',config['toolsRoot'])]])
-    def checkpoint(template, params, extra_inputs=()):
-        return '\n'.join(['### 输入', ''] + [field(k, ('localPath:' if '目录' in k else '') + expand(v, params)) for k, v in template['inputs']] + list(extra_inputs) +
-                         ['', '### 审核', '', template['review'], '', '### 交付', ''] +
-                         [field(k, 'localPath:' + expand(v, params)) for k, v in template['outputs']])
-    reserved = {n['id'] + '-review' for n in nodes} | {'delivery'}
-    if ids & reserved:
-        raise Invalid('Stage ID conflicts with a checkpoint ID')
-    checkpoints = [{'id':n['id']+'-review', 'context':checkpoint(meta['checkpoint'],
-                    {**config, **n, 'stageOutput':n['sharedOutput']})} for n in nodes]
-    final = {'id':'delivery', 'context':checkpoint(meta['delivery'], config,
-             [field(n['id']+'工作分支', n['workBranch']) for n in nodes])}
-    return {'schemaVersion':1,'metaVersion':meta['version'],'commonContext':common,'nodes':nodes,
+                      'outputFiles':files, 'recordDirectory':stage['recordDirectory'],
+                      'dependencies':[i+'-review' for i in stage['dependencies']]})
+    reserved = {i+'-review' for i in ids} | {'delivery'}
+    if ids & reserved: raise Invalid('Stage ID conflicts with a checkpoint ID')
+    dependencies = {s['id']:s['dependencies'] for s in config['stages']}
+    visited, active = set(), set()
+    def visit(key):
+        if key not in ids: raise Invalid('Unknown dependency: ' + key)
+        if key in active: raise Invalid('Cyclic stage dependency')
+        if key in visited: return
+        active.add(key)
+        for dep in dependencies[key]: visit(dep)
+        active.remove(key); visited.add(key)
+    for key in ids: visit(key)
+    for entry in config['reviews']:
+        if entry['stageId'] not in ids: raise Invalid('Unknown reviewed stage')
+        absolute(entry['record'])
+    common = '\n'.join(['### 公共执行信息', '', field('Git仓库',config['git']['url']),
+                         field('业务目录',config['bizdir']),local('Skill与工具入口',config['environmentIndex'])])
+    checkpoints=[]
+    for n in nodes:
+        lines=['### 输入','',field('工作分支',n['workBranch']),local('任务执行记录目录',n['recordDirectory']),
+               '', '### 审核','',meta['checkpoint']['review'],'','### 交付','',
+               local('审核记录目录',str(records/'checkpoints'/Path(n['recordDirectory']).relative_to(records)))]
+        checkpoints.append({'id':n['id']+'-review','dependencies':[n['id']],'context':'\n'.join(lines)})
+    used={dep for deps in dependencies.values() for dep in deps}
+    final={'id':'delivery','dependencies':[n['id']+'-review' for n in nodes if n['id'] not in used],
+           'context':'\n'.join(['### 输入','']+[field(n['stage']+'工作分支',n['workBranch']) for n in nodes if n['id'] not in used]+[
+               local('任务执行记录目录',str(records)),'','### 审核','',meta['delivery']['review'],'','### 交付','',
+               local('持久迭代目录',str(persistent))])}
+    return {'schemaVersion':2,'metaVersion':meta['version'],'commonContext':common,'nodes':nodes,
             'checkpoints':checkpoints,'delivery':final}
 
 
+def stage_scope(config, rendered, stage_id):
+    stage = next((s for s in config['stages'] if s['id'] == stage_id), None)
+    if stage is None: raise Invalid('Unknown stage ID')
+    if 'inputCommit' not in stage: raise Invalid('Stage input commit has not been accepted yet')
+    return {'schemaVersion':1,'id':stage_id,'stage':stage['stage'],'bizdir':config['bizdir'],
+            'workBranch':stage['workBranch'],'inputCommit':stage['inputCommit'],
+            'metaVersion':rendered['metaVersion']}
+
+
+def scope_nodes(scope, workflow):
+    text={'type':'string','minLength':1,'pattern':r'^[^\x00-\x1f`{}]+$'}
+    props={'schemaVersion':{'const':1},'id':text,'stage':text,'bizdir':text,'workBranch':text,
+           'inputCommit':{'type':'string','pattern':'^[0-9a-f]{40}$'},'metaVersion':{'const':2}}
+    validate(scope,{'type':'object','additionalProperties':False,'properties':props,'required':list(props)})
+    relative(scope['bizdir']); branch(scope['workBranch'])
+    meta=json.loads((Path(workflow)/'resources/stage-meta.json').read_text())
+    if meta['version'] != scope['metaVersion']: raise Invalid('Stage metadata version mismatch')
+    if scope['stage'] not in meta['stages']: raise Invalid('Unknown stage type')
+    stage=meta['stages'][scope['stage']]
+    result={}
+    for key in ('outputDirectories','outputFiles'):
+        paths=[v.replace('{bizdir}',scope['bizdir']) for _,v in stage[key]]
+        for p in paths:
+            if not relative(p).is_relative_to(relative(scope['bizdir'])) or p == scope['bizdir']:
+                raise Invalid('Invalid stage output path')
+        result[key]=paths
+    return [result]
+
+
 def main(argv=None):
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('action', choices=['render', 'diff-review'])
-    parser.add_argument('--input', required=True)
-    parser.add_argument('--workflow', required=True, help='Frozen workflow Skill directory')
-    parser.add_argument('--output', required=True, help='Review JSON; node contexts are Markdown')
+    parser.add_argument('action', choices=['render','diff-review','scope','stage-gate','init','update','list','archive'])
+    parser.add_argument('--input', help='Owner metadata or stage scope, depending on command')
+    parser.add_argument('--workflow', help='Frozen workflow Skill directory')
+    parser.add_argument('--output')
     parser.add_argument('--repository')
     parser.add_argument('--base')
     parser.add_argument('--head')
     parser.add_argument('--stage-id', action='append')
+    parser.add_argument('--registry', help='Initiator workspace persistent iterations directory')
+    parser.add_argument('--expected-sha256')
+    parser.add_argument('--source')
+    parser.add_argument('--kind', choices=['reports','records'])
+    parser.add_argument('--name')
     args = parser.parse_args(argv)
+    def require(*names):
+        for name in names:
+            if not getattr(args,name): raise Invalid('Missing --'+name.replace('_','-'))
     try:
-        result = render(json.loads(Path(args.input).read_text()), args.workflow)
-        target = Path(args.output)
-        if target.exists():
-            raise Invalid('Output already exists; choose a new review artifact')
-        if args.action == 'diff-review':
-            if not all((args.repository, args.base, args.head, args.stage_id)):
-                raise Invalid('diff-review requires repository, base, head and stage-id')
-            selected = [n for n in result['nodes'] if n['id'] in args.stage_id]
-            if {n['id'] for n in selected} != set(args.stage_id):
-                raise Invalid('Unknown stage ID in diff-review scope')
+        from . import registry
+        if args.action == 'list':
+            require('registry')
+            print(json.dumps(registry.entries(args.registry),ensure_ascii=False,indent=2)); return 0
+        require('input')
+        config=json.loads(Path(args.input).read_text())
+        if args.action == 'archive':
+            require('source','kind','name')
+            result=registry.archive(args.input,args.source,args.kind,args.name)
+            print(json.dumps({'directory':result['directory'],'files':len(result['files'])},ensure_ascii=False)); return 0
+        require('workflow')
+        if args.action in ('init','update'):
+            require('registry')
+            if args.action == 'update': require('expected_sha256')
+            elif args.expected_sha256: raise Invalid('init does not accept an update hash')
+            print(json.dumps(registry.save(config,args.workflow,args.registry,args.expected_sha256),ensure_ascii=False)); return 0
+        require('output')
+        target=Path(args.output)
+        if target.exists(): raise Invalid('Output already exists; choose a new artifact')
+        if args.action == 'stage-gate':
+            require('repository','head')
+            from .diff_review import review
+            checked=review(args.repository,config['inputCommit'],args.head,scope_nodes(config,args.workflow))
+            target.write_text(checked['markdown']); return 0 if checked['passed'] else 3
+        result=render(config,args.workflow)
+        if args.action == 'scope':
+            if not args.stage_id or len(args.stage_id)!=1: raise Invalid('scope requires exactly one stage-id')
+            result=stage_scope(config,result,args.stage_id[0])
+        elif args.action == 'diff-review':
+            require('repository','base','head','stage_id')
+            selected=[n for n in result['nodes'] if n['id'] in args.stage_id]
+            if {n['id'] for n in selected} != set(args.stage_id): raise Invalid('Unknown stage ID')
             from .diff_review import review
-            checked = review(args.repository, args.base, args.head, selected)
-            target.write_text(checked['markdown'])
-            return 0 if checked['passed'] else 3
-        target.write_text(json.dumps(result, ensure_ascii=False, indent=2) + '\n')
+            checked=review(args.repository,args.base,args.head,selected)
+            target.write_text(checked['markdown']); return 0 if checked['passed'] else 3
+        target.write_text(json.dumps(result,ensure_ascii=False,indent=2)+'\n')
     except (ValueError, KeyError, OSError) as error:
-        print(str(error), file=sys.stderr)
-        return 2
+        print(str(error),file=sys.stderr); return 2
     return 0

package/tools/modules/workflow/registry.py

@@ -0,0 +1,151 @@
+"""Initiator-owned iteration registry and durable report storage; never drives tasks."""
+from contextlib import contextmanager
+from hashlib import sha256
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+import fcntl
+import json
+import os
+import re
+import shutil
+import tempfile
+
+
+def digest(path):
+    return sha256(Path(path).read_bytes()).hexdigest()
+
+
+def atomic_json(path, value):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix='.pending-')
+    try:
+        with os.fdopen(fd, 'w') as out:
+            json.dump(value, out, ensure_ascii=False, indent=2)
+            out.write('\n'); out.flush(); os.fsync(out.fileno())
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp): os.unlink(tmp)
+
+
+@contextmanager
+def lock(root):
+    root = Path(root).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    with (root / '.registry.lock').open('a') as stream:
+        fcntl.flock(stream, fcntl.LOCK_EX)
+        yield root
+
+
+def entries(root):
+    result = []
+    for path in sorted(Path(root).glob('*/iteration.meta.json')):
+        value = json.loads(path.read_text())
+        result.append({'id':value['iteration']['id'], 'goal':value['iteration']['goal'],
+                       'state':value['iteration']['state'], 'metadata':str(path), 'sha256':digest(path)})
+    return result
+
+
+def save(config, workflow, root, expected=None):
+    from .iteration import render, Invalid
+    render(config, workflow, require_shared=False)
+    with lock(root) as root:
+        target = root / config['iteration']['id']
+        if Path(config['persistentRoot']).resolve() != target.resolve():
+            raise Invalid('persistentRoot must equal registry root / iteration ID')
+        path = target / 'iteration.meta.json'
+        if path.exists():
+            if not expected or digest(path) != expected:
+                raise Invalid('Metadata exists or changed; supply its current SHA256 for update')
+            old = json.loads(path.read_text())
+            if old['iteration']['id'] != config['iteration']['id']:
+                raise Invalid('Cannot change iteration identity')
+            history = target / 'records' / 'metadata-history' / (digest(path)+'.json')
+            atomic_json(history, old)
+        elif expected:
+            raise Invalid('Cannot update missing iteration metadata')
+        for subdir in ('records','reports'):
+            (target/subdir).mkdir(parents=True, exist_ok=True)
+        atomic_json(path, config)
+        atomic_json(root/'index.json', {'schemaVersion':1,'iterations':entries(root)})
+        return {'metadata':str(path),'sha256':digest(path)}
+
+
+class References(HTMLParser):
+    def __init__(self):
+        super().__init__(); self.values=[]
+    def handle_starttag(self, tag, attrs):
+        attrs=dict(attrs)
+        if tag == 'base':
+            raise ValueError('Report must not override its relative base URL')
+        for key in ('src','href','poster','data'):
+            if key in attrs: self.values.append(attrs[key])
+        if attrs.get('srcset'):
+            value=attrs['srcset']
+            if not value.startswith('data:'):
+                self.values.extend(x.strip().split()[0] for x in value.split(',') if x.strip())
+        if attrs.get('style'):
+            self.values.extend(css_refs(attrs['style']))
+
+
+def css_refs(text):
+    return re.findall(r'url\(\s*[\"\']?([^\"\')]+)[\"\']?\s*\)',text,flags=re.I) + re.findall(r'@import\s+[\"\']([^\"\']+)[\"\']',text,flags=re.I)
+
+
+def check_assets(root):
+    """Check static HTML/CSS dependencies. JS-generated URLs require browser review."""
+    root=Path(root).resolve(); files={}; errors=[]
+    for path in sorted(root.rglob('*')):
+        if path.is_symlink():
+            raise ValueError('Archive source contains a symlink: '+str(path))
+        if not path.is_file(): continue
+        files[path.relative_to(root).as_posix()]=digest(path)
+        refs=[]
+        if path.suffix.lower() in ('.html','.htm'):
+            text=path.read_text(); parser=References(); parser.feed(text)
+            refs=parser.values+css_refs(text)
+        elif path.suffix.lower()=='.css': refs=css_refs(path.read_text())
+        for ref in refs:
+            url=urlsplit(ref.strip())
+            if url.scheme in ('http','https','data','mailto','tel') or url.netloc or not url.path: continue
+            if url.scheme or url.path.startswith('/'):
+                errors.append(f'{path.relative_to(root)}: nonportable reference {ref}'); continue
+            linked=(path.parent/unquote(url.path)).resolve()
+            if not linked.is_relative_to(root) or not linked.exists():
+                errors.append(f'{path.relative_to(root)}: missing/outside reference {ref}')
+    if errors: raise ValueError('\n'.join(errors))
+    if not files: raise ValueError('Archive contains no files')
+    return files
+
+
+def archive(metadata, source, kind, name):
+    from .iteration import Invalid
+    if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_-]*',name): raise Invalid('Invalid archive name')
+    if kind not in ('reports','records'): raise Invalid('Unknown archive kind')
+    metadata=Path(metadata).resolve()
+    config=json.loads(metadata.read_text())
+    persistent=Path(config['persistentRoot']).resolve()
+    if metadata != persistent/'iteration.meta.json': raise Invalid('Not a registered metadata path')
+    source=Path(source)
+    if source.is_symlink() or not source.is_dir(): raise Invalid('Archive source must be a real directory')
+    source=source.resolve()
+    if source == persistent or source.is_relative_to(persistent) or persistent.is_relative_to(source):
+        raise Invalid('Source and persistent archive must be disjoint')
+    before=check_assets(source)
+    with lock(persistent.parent):
+        target=persistent/kind/name
+        if target.exists(): raise Invalid('Archive already exists; use a new content version')
+        pending=Path(tempfile.mkdtemp(prefix='.archive-',dir=persistent))
+        try:
+            shutil.copytree(source,pending/'content')
+            after=check_assets(pending/'content')
+            if before != after: raise Invalid('Archive source changed while copying')
+            target.parent.mkdir(parents=True,exist_ok=True)
+            os.replace(pending/'content',target)
+            record={'schemaVersion':1,'kind':kind,'name':name,'directory':str(target),
+                    'files':after,'staticAssetsVerified':True,'browserReview':'required-for-user-preview'}
+            atomic_json(persistent/'records'/'archives'/(kind+'-'+name+'.json'),record)
+            return record
+        finally:
+            shutil.rmtree(pending)