@antprofuse/saddle-islands-tools 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antprofuse/saddle-islands-tools",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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/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)