@antprofuse/saddle-islands-tools 0.0.0-stage → 0.1.4

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "@antprofuse/saddle-islands-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "description": "Independent Saddle–Islands engineering tools",
+  "files": [
+    "tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@code.alipay.com/profuse/saddle-islands.git"
+  },
+  "license": "MIT OR Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/tools/adapters/islands/trigger_source.py

@@ -0,0 +1,53 @@
+"""Islands trigger source validation; consumes the frozen official language guide."""
+import re
+from tools.core.semantic_identity import normalize
+
+RETURN_RULE = {'path': 'docs/language/visual.md', 'heading': '页面初始化事务与终点响应'}
+
+
+def resolve_pointer(document, pointer):
+    if not isinstance(pointer, str) or not pointer.startswith('/') or re.search(r'~(?![01])', pointer):
+        raise ValueError('invalid source pointer')
+    value = document
+    for encoded in pointer[1:].split('/'):
+        key = encoded.replace('~1', '/').replace('~0', '~')
+        if isinstance(value, dict) and key in value:
+            value = value[key]
+        elif isinstance(value, list) and re.fullmatch(r'0|[1-9][0-9]*', key) and int(key) < len(value):
+            value = value[int(key)]
+        else:
+            raise ValueError('source pointer does not resolve')
+    return value
+
+
+def validate_trigger_source(identity, source, document, *, page_path, language_guide=None):
+    """Validate source shape/resolution. Project compiler still verifies trigger semantics.
+
+    Caller supplies the actual parsed source and its repository path, not a sample.
+    language_guide is the actual frozen Islands visual.md text, not user content.
+    """
+    value = normalize(identity)
+    expected = f"{value['business']}/spec/domains/{value['domain']}/visual/{value['page']}.yaml"
+    if page_path != expected or not isinstance(source, dict) or source.get('path') != page_path:
+        raise ValueError('source does not belong to the identity page')
+    if source.get('kind') == 'explicit':
+        if set(source) != {'kind', 'path', 'pointer'} or source['pointer'] != value['trigger']:
+            raise ValueError('explicit source must match trigger')
+        return resolve_pointer(document, source['pointer'])
+    if source.get('kind') != 'languageDefault' or set(source) != {'kind', 'path', 'pointer', 'rule'}:
+        raise ValueError('unknown trigger source shape')
+    if value['trigger'] != '/页面/页面返回时事务' or source['pointer'] != '/页面' or source['rule'] != RETURN_RULE:
+        raise ValueError('unsupported language default')
+    page = resolve_pointer(document, '/页面')
+    if not isinstance(page, dict) or '页面返回时事务' in page:
+        raise ValueError('return declaration is explicit, not inherited')
+    heading = '## ' + RETURN_RULE['heading']
+    if not isinstance(language_guide, str) or heading not in language_guide:
+        raise ValueError('missing frozen Islands rule')
+    section = language_guide.split(heading, 1)[1].split('\n## ', 1)[0]
+    if '缺少返回事务声明时整体复用初始化事务配置' not in section:
+        raise ValueError('frozen Islands guide does not establish this default')
+    initialization = page.get('页面初始化事务', {})
+    if not isinstance(initialization, dict):
+        raise ValueError('invalid initialization configuration')
+    return initialization

package/tools/cli/backend.mjs

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict';
+import {dirname,resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {readFile} from 'node:fs/promises';
+import {verifyIdentity} from '../core/package-identity.mjs';
+const args=process.argv.slice(2);
+if(args.includes('--help')){
+ console.log('backend --project <suite-root> --repository <source-root> --adapter <adapter.mjs> --identity <trusted.json> [--list | --binary <executable> --out <fresh-external-output> [--case <id>]]');
+ process.exit(0);
+}
+const allowed=new Set(['--project','--repository','--adapter','--identity','--binary','--out','--case','--list']);
+const parsed={};
+for(let i=0;i<args.length;i++){
+ const key=args[i];assert(allowed.has(key),'unknown argument '+key);assert(!(key in parsed),'duplicate argument '+key);
+ if(key==='--list')parsed[key]=true;
+ else{assert(args[i+1]&&!args[i+1].startsWith('--'),'missing value '+key);parsed[key]=args[++i];}
+}
+assert(parsed['--identity'],'explicit frozen tool identity file required');
+const identity=JSON.parse(await readFile(parsed['--identity'],'utf8'));
+const root=resolve(dirname(fileURLToPath(import.meta.url)),'../..');
+await verifyIdentity(root,identity);
+// Load execution dependencies only after source verification succeeds.
+const {run}=await import('../modules/backend/run.mjs');
+await run({projectRoot:parsed['--project'],repositoryRoot:parsed['--repository'],adapter:parsed['--adapter'],out:parsed['--out'],binary:parsed['--binary'],caseId:parsed['--case'],list:!!parsed['--list'],identity});

package/tools/cli/main.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Saddle–Islands tools: only implemented commands are registered."""
+import argparse
+from pathlib import Path
+import sys
+import subprocess
+
+sys.dont_write_bytecode = True
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+
+def main():
+    if len(sys.argv) > 1 and sys.argv[1] == 'iteration':
+        from tools.modules.workflow.iteration import main as iteration_main
+        return iteration_main(sys.argv[2:])
+    if len(sys.argv) > 1 and sys.argv[1] == 'identity':
+        from tools.core.semantic_identity import main as identity_main
+        sys.argv = [sys.argv[0] + ' identity', *sys.argv[2:]]
+        return identity_main()
+    if len(sys.argv) > 1 and sys.argv[1] == 'backend':
+        return subprocess.call(['node', str(Path(__file__).with_name('backend.mjs')), *sys.argv[2:]])
+    if len(sys.argv) > 1 and sys.argv[1] == 'minifish':
+        args = sys.argv[2:]
+        if not args or args == ['--help']:
+            print('minifish build|package|plugin|batch|run|report <explicit options>; see tools/docs/minifish-testing.md')
+            return 0
+        command = args[0]
+        if command not in ('build', 'package', 'plugin', 'batch', 'run', 'report'):
+            raise SystemExit('Unknown minifish command: ' + command)
+        entry = 'minifish.mjs' if command in ('build', 'package', 'plugin') else 'minifish.py'
+        return subprocess.call(['node' if entry.endswith('.mjs') else sys.executable, str(Path(__file__).with_name(entry)), *args])
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('command', choices=['identity', 'backend', 'minifish', 'iteration'], help='semantic identities, backend tests or Minifish tests')
+    parser.parse_args()
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/tools/cli/minifish.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import {readFile} from 'node:fs/promises';
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import {createRequire,registerHooks} from 'node:module';
+import {pathToFileURL} from 'node:url';
+const [command,...args]=process.argv.slice(2),flags={};
+for(let i=0;i<args.length;i+=2){assert(args[i]?.startsWith('--')&&args[i+1],'Expected named option and value');assert(!Object.hasOwn(flags,args[i].slice(2)),'Duplicate option');flags[args[i].slice(2)]=args[i+1];}
+assert(['build','package','plugin'].includes(command),'Usage: minifish.mjs build|package|plugin --project-root ROOT --config FILE --output DIR --definition CASE | --plan JSON [--tool-node-modules DIR]');
+assert(flags['project-root']&&flags.config&&flags.output,'Explicit project root, config and output required');
+if(!process.execArgv.includes('--experimental-vm-modules')){const child=spawnSync(process.execPath,['--experimental-vm-modules',process.argv[1],...process.argv.slice(2)],{stdio:'inherit',env:process.env});process.exit(child.status??1);}
+const packageRoot=path.resolve(import.meta.dirname,'../..');
+assert(flags['tool-source'],'External --tool-source manifest required; invoke through the trusted project launcher');
+assert(!path.resolve(flags['tool-source']).startsWith(packageRoot+path.sep),'Trust manifest must be outside package');
+const identity=JSON.parse(await readFile(flags['tool-source'],'utf8')),verifier='tools/modules/minifish/compiler/tool-identity.mjs';
+for(const trustedModule of [verifier,'tools/core/package-identity.mjs'])assert.equal(createHash('sha256').update(await readFile(path.join(packageRoot,trustedModule))).digest('hex'),identity.files?.[trustedModule],'Untrusted tool identity verifier: '+trustedModule);
+const {toolIdentity}=await import('../modules/minifish/compiler/tool-identity.mjs');
+await toolIdentity(identity,flags['tool-source']);
+for(const [flag,lock]of [['tool-node-modules','tools/modules/minifish/package-lock.json'],['sdk-node-modules','tools/modules/minifish/sdk/package-lock.json']])if(flags[flag])assert.equal(createHash('sha256').update(await readFile(path.resolve(flags[flag],'../package-lock.json'))).digest('hex'),identity.files[lock],'External dependency lock mismatch: '+flag);
+process.env.MINIFISH_TOOL_SOURCE_LOCK=path.resolve(flags['tool-source']);
+if(flags['tool-node-modules']){
+ const require=createRequire(path.join(path.resolve(flags['tool-node-modules']),'../package.json'));
+ registerHooks({resolve(specifier,context,next){if(['typescript','@playwright/test'].includes(specifier)){let file=require.resolve(specifier);if(specifier==='@playwright/test')file=path.join(path.dirname(file),'index.mjs');return {url:pathToFileURL(file).href,shortCircuit:true};}return next(specifier,context);}});
+}
+registerHooks({resolve(specifier,context,next){const prefix='@antprofuse/saddle-islands-tools/';if(specifier.startsWith(prefix)){const file=path.resolve(packageRoot,specifier.slice(prefix.length));assert(file.startsWith(packageRoot+path.sep),'Public package import escaped');return {url:pathToFileURL(file).href,shortCircuit:true};}return next(specifier,context);}});
+const {buildCase,buildPlanPackage}=await import('../modules/minifish/compiler/build-case.mjs');
+const options={projectRoot:path.resolve(flags['project-root']),config:path.resolve(flags.config)};
+let result;
+if(command==='plugin'){
+ const {loadProject}=await import('../modules/minifish/compiler/config.mjs');
+ const project=await loadProject(options.projectRoot,options.config);
+ const {validatePluginEvents}=await import(pathToFileURL(await project.resolveAdapter(project.config.pluginAdapter)).href);
+ const {buildPluginArtifact}=await import('../modules/minifish/harness/build-plugin-artifact.mjs');
+ result=await buildPluginArtifact({planFile:flags.plan,output:flags.output,modules:flags['sdk-node-modules'],source:flags.source,repositoryRoot:path.resolve(project.root,project.config.repositoryRoot),validatePluginEvents});
+}else result=command==='build'?await buildCase(flags.definition,flags.output,options):await buildPlanPackage(JSON.parse(await readFile(flags.plan,'utf8')),flags.output,options);
+console.log(JSON.stringify(result));

package/tools/cli/minifish.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Stable public batch/runtime/report entry, all implementation lives in tools."""
+from pathlib import Path
+import json
+import hashlib
+import os
+import subprocess
+import sys
+sys.dont_write_bytecode = True
+PACKAGE = Path(__file__).resolve().parents[2]
+try:
+    index = sys.argv.index('--tool-source')
+    manifest_file = Path(sys.argv[index + 1]).resolve(strict=True)
+    del sys.argv[index:index + 2]
+except (ValueError, IndexError):
+    raise SystemExit('External --tool-source manifest required; invoke through trusted project launcher')
+if PACKAGE in manifest_file.parents: raise SystemExit('Trust manifest must be outside package')
+identity = json.loads(manifest_file.read_text())
+verifier = 'tools/modules/minifish/identity.py'
+for trusted_module in (verifier, 'tools/core/package_identity.py'):
+    if hashlib.sha256((PACKAGE / trusted_module).read_bytes()).hexdigest() != identity.get('files', {}).get(trusted_module):
+        raise SystemExit('Untrusted tool identity verifier: ' + trusted_module)
+sys.path.insert(0, str(PACKAGE / 'tools/modules/minifish'))
+from identity import verify_package
+verify_package(PACKAGE, manifest_file)
+if '--node-modules' in sys.argv:
+    modules = Path(sys.argv[sys.argv.index('--node-modules') + 1]).resolve()
+    if hashlib.sha256((modules.parent / 'package-lock.json').read_bytes()).hexdigest() != identity['files']['tools/modules/minifish/sdk/package-lock.json']:
+        raise SystemExit('External SDK dependency lock mismatch')
+for flag in ['--output', '--report-dir']:
+    if flag in sys.argv:
+        output = Path(sys.argv[sys.argv.index(flag) + 1]).resolve()
+        if output == PACKAGE or PACKAGE in output.parents:
+            raise SystemExit('Outputs must be outside tool package')
+os.environ['MINIFISH_TOOL_SOURCE_LOCK'] = str(manifest_file)
+os.environ['PYTHONDONTWRITEBYTECODE'] = '1'
+ROOT = PACKAGE / 'tools/modules/minifish/harness'
+if len(sys.argv) < 2: raise SystemExit('usage: minifish.py batch|run|report <explicit options>')
+command = sys.argv[1]
+if command in ('batch', 'run'):
+    result = subprocess.run([sys.executable, str(ROOT / ('run-batch.py' if command == 'batch' else 'run-platform.py')), *sys.argv[2:]])
+    raise SystemExit(result.returncode)
+if command == 'report':
+    import argparse
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--summary', type=Path, required=True)
+    parser.add_argument('--output', type=Path, required=True)
+    args = parser.parse_args(sys.argv[2:])
+    sys.path.insert(0, str(ROOT))
+    from batch_report import render_report
+    print(render_report(json.loads(args.summary.read_text()), args.output))
+else: raise SystemExit('unknown minifish command: '+command)

package/tools/core/package-identity.mjs

@@ -0,0 +1,23 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import {readFile,readdir,lstat,realpath} from 'node:fs/promises';
+import {createHash} from 'node:crypto';
+const sha=bytes=>createHash('sha256').update(bytes).digest('hex');
+const required=['package.json','tools/cli/main.py','tools/cli/backend.mjs','tools/core/package-identity.mjs','tools/core/package_identity.py','tools/modules/backend/package.json','tools/modules/backend/package-lock.json','tools/cli/minifish.mjs','tools/cli/minifish.py','tools/modules/minifish/compiler/tool-identity.mjs','tools/modules/minifish/identity.py','tools/modules/minifish/package.json','tools/modules/minifish/package-lock.json','tools/modules/minifish/sdk/package.json','tools/modules/minifish/sdk/package-lock.json'];
+const dependencies=[{path:'tools/modules/backend/node_modules',packageJson:'tools/modules/backend/package.json',lock:'tools/modules/backend/package-lock.json'},{path:'tools/modules/minifish/node_modules',packageJson:'tools/modules/minifish/package.json',lock:'tools/modules/minifish/package-lock.json'},{path:'tools/modules/minifish/sdk/node_modules',packageJson:'tools/modules/minifish/sdk/package.json',lock:'tools/modules/minifish/sdk/package-lock.json'}];
+export async function verifyIdentity(root,identity){
+ root=await realpath(root);
+ assert(typeof identity.repository==='string'&&identity.repository.length,'Trusted repository required');assert(/^[a-f0-9]{40}$/.test(identity.commit),'Complete frozen commit required');
+ assert(identity.packagePath&&identity.package&&identity.version,'Trusted package path/name/version required');assert(identity.files&&Object.keys(identity.files).length,'Trusted complete file hashes required');
+ for(const file of required)assert(Object.hasOwn(identity.files,file),'Missing trusted file: '+file);
+ assert.deepEqual(identity.dependencyRoots,dependencies,'Explicit locked dependency boundaries required');
+ for(const [file,digest]of Object.entries(identity.files)){
+  assert(file&&!path.isAbsolute(file)&&!file.split('/').some(p=>['','.','..'].includes(p))&&/^[a-f0-9]{64}$/.test(digest),'Invalid trusted file: '+file);
+  let current=root;for(const part of file.split('/')){current=path.join(current,part);assert(!(await lstat(current)).isSymbolicLink(),'Package symlink forbidden: '+file);}
+  assert((await lstat(current)).isFile(),'Regular trusted file required: '+file);assert.equal(sha(await readFile(current)),digest,'Tool file hash mismatch: '+file);
+ }
+ async function inventory(dir,prefix=''){
+  for(const entry of await readdir(dir,{withFileTypes:true})){const file=prefix+entry.name;assert(!entry.isSymbolicLink(),'Package symlink forbidden: '+file);if(file==='.git'||dependencies.some(d=>d.path===file)){assert(entry.isDirectory(),'Installation boundary must be directory: '+file);continue;}if(entry.isDirectory())await inventory(path.join(dir,entry.name),file+'/');else assert(entry.isFile()&&Object.hasOwn(identity.files,file),'Unlisted package file: '+file);}
+ }
+ await inventory(root);const manifest=JSON.parse(await readFile(path.join(root,'package.json'),'utf8'));assert.equal(manifest.name,identity.package,'Tool package name mismatch');assert.equal(manifest.version,identity.version,'Tool package version mismatch');return identity;
+}

package/tools/core/package_identity.py

@@ -0,0 +1,58 @@
+"""Project-owned trust bootstrap. Only stdlib runs before all package bytes match."""
+import hashlib
+import json
+from pathlib import Path
+import re
+
+REQUIRED = ('package.json', 'tools/cli/main.py', 'tools/cli/backend.mjs', 'tools/core/package-identity.mjs', 'tools/core/package_identity.py', 'tools/modules/backend/package.json', 'tools/modules/backend/package-lock.json', 'tools/cli/minifish.mjs', 'tools/cli/minifish.py',
+            'tools/modules/minifish/compiler/tool-identity.mjs', 'tools/modules/minifish/identity.py',
+            'tools/modules/minifish/package.json', 'tools/modules/minifish/package-lock.json',
+            'tools/modules/minifish/sdk/package.json', 'tools/modules/minifish/sdk/package-lock.json')
+DEPENDENCIES = {'tools/modules/backend/node_modules': ('tools/modules/backend/package.json', 'tools/modules/backend/package-lock.json'), 'tools/modules/minifish/node_modules': ('tools/modules/minifish/package.json', 'tools/modules/minifish/package-lock.json'),
+                'tools/modules/minifish/sdk/node_modules': ('tools/modules/minifish/sdk/package.json', 'tools/modules/minifish/sdk/package-lock.json')}
+
+
+def verify_package(root, manifest_file):
+    root = Path(root).resolve(strict=True)
+    manifest_file = Path(manifest_file).resolve(strict=True)
+    if manifest_file == root or root in manifest_file.parents:
+        raise ValueError('Trust manifest must be outside tool package')
+    identity = json.loads(manifest_file.read_text())
+    if not identity.get('repository') or not re.fullmatch('[a-f0-9]{40}', identity.get('commit', '')):
+        raise ValueError('Trusted repository and complete commit required')
+    if not identity.get('version') or not identity.get('packagePath') or not identity.get('package'):
+        raise ValueError('Trusted package path/name/version required')
+    files = identity.get('files', {})
+    for name in REQUIRED:
+        if name not in files:
+            raise ValueError('Missing trusted file: ' + name)
+    boundaries = identity.get('dependencyRoots')
+    expected = [{'path': p, 'packageJson': v[0], 'lock': v[1]} for p, v in DEPENDENCIES.items()]
+    if boundaries != expected:
+        raise ValueError('Explicit locked dependency boundaries required')
+    for name, digest in files.items():
+        parts = name.split('/')
+        if not name or name.startswith('/') or any(p in ('', '.', '..') for p in parts) or not re.fullmatch('[a-f0-9]{64}', digest):
+            raise ValueError('Invalid trusted file: ' + name)
+        file = root / name
+        if any((root.joinpath(*parts[:i])).is_symlink() for i in range(1, len(parts) + 1)) or not file.is_file():
+            raise ValueError('Missing or unsafe trusted file: ' + name)
+        if hashlib.sha256(file.read_bytes()).hexdigest() != digest:
+            raise ValueError('Tool file hash mismatch: ' + name)
+    def inventory(directory, prefix=''):
+        for item in directory.iterdir():
+            name = prefix + item.name
+            if item.is_symlink():
+                raise ValueError('Package symlink forbidden: ' + name)
+            if name == '.git' or name in DEPENDENCIES:
+                if not item.is_dir(): raise ValueError('Installation boundary must be directory: ' + name)
+                continue
+            if item.is_dir():
+                inventory(item, name + '/')
+            elif not item.is_file() or name not in files:
+                raise ValueError('Unlisted package file: ' + name)
+    inventory(root)
+    package = json.loads((root / 'package.json').read_text())
+    if package['name'] != identity['package'] or package['version'] != identity['version']:
+        raise ValueError('Tool package name/version mismatch')
+    return identity

package/tools/core/semantic_identity.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Semantic identity generator. Python 3 standard library only."""
+import argparse
+import hashlib
+import json
+import os
+import re
+import tempfile
+import unicodedata
+from pathlib import Path
+
+# Explicit Unicode White_Space set, frozen for this algorithm (not Python-version-dependent strip).
+EDGE_SPACE = frozenset(chr(n) for n in [*range(9,14),32,133,160,5760,*range(8192,8203),8232,8233,8239,8287,12288])
+
+FIELDS = {'kind', 'business', 'domain', 'page', 'trigger'}
+
+
+def unique_pairs(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f'duplicate JSON key: {key}')
+        result[key] = value
+    return result
+
+
+def read(path):
+    return json.loads(Path(path).read_text(encoding='utf-8'), object_pairs_hook=unique_pairs)
+
+
+def normalize(identity):
+    if not isinstance(identity, dict) or set(identity) != FIELDS:
+        raise ValueError('identity must contain exactly: ' + ', '.join(sorted(FIELDS)))
+    result = {}
+    for key, value in identity.items():
+        if not isinstance(value, str) or not value or (value[0] in EDGE_SPACE or value[-1] in EDGE_SPACE):
+            raise ValueError(f'{key}: expected nonempty string without surrounding whitespace')
+        if any(ord(c) < 32 or 0xD800 <= ord(c) <= 0xDFFF for c in value):
+            raise ValueError(f'{key}: control characters and surrogates are forbidden')
+        result[key] = unicodedata.normalize('NFC', value)
+    if result['kind'] != 'backend_contract':
+        raise ValueError('unsupported identity kind')
+    if not result['trigger'].startswith('/') or re.search(r'~(?![01])', result['trigger']):
+        raise ValueError('trigger: expected RFC 6901 pointer with valid escaping')
+    return result
+
+
+def canonical(identity):
+    return json.dumps(normalize(identity), ensure_ascii=False, sort_keys=True, separators=(',', ':'))
+
+
+def identifier(identity):
+    return 'api_' + hashlib.sha256(canonical(identity).encode('utf-8')).hexdigest()[:32]
+
+
+def validate_registry(registry):
+    if not isinstance(registry, dict):
+        raise ValueError('registry must be an ID-to-identity object')
+    for key, identity in registry.items():
+        if identity != normalize(identity):
+            raise ValueError(f'{key}: registry identity must already be normalized')
+        if key != identifier(identity):
+            raise ValueError(f'{key}: identity digest mismatch')
+    return registry
+
+
+def validate_append_only(base, current):
+    validate_registry(base)
+    validate_registry(current)
+    for key, identity in base.items():
+        if current.get(key) != identity:
+            raise ValueError(f'{key}: historical entry removed or changed')
+
+
+def register(registry, identity):
+    validate_registry(registry)
+    value = normalize(identity)
+    key = identifier(value)
+    previous = registry.get(key)
+    if previous is not None and previous != value:
+        raise ValueError(f'{key}: digest collision')
+    registry[key] = value
+    return key
+
+
+def check_active(registry, contracts):
+    validate_registry(registry)
+    if not isinstance(contracts, list):
+        raise ValueError('active contracts must be a JSON array')
+    seen = set()
+    for contract in contracts:
+        if not isinstance(contract, dict) or set(contract) != {'id', 'identity'}:
+            raise ValueError('active record must contain exactly id and identity')
+        key = identifier(contract['identity'])
+        if contract['id'] != key:
+            raise ValueError('active contract digest mismatch')
+        if key in seen:
+            raise ValueError(f'{key}: duplicate active definition')
+        seen.add(key)
+        if registry.get(key) != normalize(contract['identity']):
+            raise ValueError(f'{key}: active identity is not registered')
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest='command', required=True)
+    generate = sub.add_parser('generate')
+    generate.add_argument('identity')
+    append = sub.add_parser('register')
+    append.add_argument('identity')
+    append.add_argument('--registry', required=True)
+    verify = sub.add_parser('check')
+    verify.add_argument('--registry', required=True)
+    verify.add_argument('--baseline', required=True, help='registry extracted from trusted Git base')
+    verify.add_argument('--active', required=True, help='all current contracts exported as id/identity JSON array')
+    args = parser.parse_args()
+    try:
+        if args.command == 'generate':
+            value = read(args.identity)
+            print(json.dumps({'id': identifier(value), 'identity': normalize(value)}, ensure_ascii=False, sort_keys=True))
+        elif args.command == 'register':
+            path = Path(args.registry)
+            registry = read(path) if path.exists() else {}
+            key = register(registry, read(args.identity))
+            content = json.dumps(registry, ensure_ascii=False, sort_keys=True, indent=2) + '\n'
+            # No write occurs until validation succeeds. Commit serially; concurrent branch merges require recheck.
+            temporary = None
+            try:
+                with tempfile.NamedTemporaryFile(mode='w', encoding='utf-8', dir=path.parent, delete=False) as stream:
+                    temporary = stream.name
+                    stream.write(content)
+                    stream.flush()
+                    os.fsync(stream.fileno())
+                os.replace(temporary, path)
+            finally:
+                if temporary and os.path.exists(temporary):
+                    os.unlink(temporary)
+            print(key)
+        else:
+            current = read(args.registry)
+            validate_append_only(read(args.baseline), current)
+            check_active(current, read(args.active))
+            print('identity registry and active contracts: PASS')
+    except (ValueError, OSError, TypeError) as error:
+        parser.exit(1, f'{error}\n')
+
+
+if __name__ == '__main__':
+    main()

package/tools/core/test_semantic_identity.py

@@ -0,0 +1,136 @@
+import copy
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+import unittest
+from unittest.mock import patch
+from tools.core import semantic_identity as s
+from tools.adapters.islands import trigger_source as source_api
+
+IDENTITY = {'kind': 'backend_contract', 'business': 'example-app', 'domain': '示例领域', 'page': '示例页面', 'trigger': '/页面/页面初始化事务'}
+EXPECTED = 'api_c6267626643566cd7945122e2bd54b73'
+
+class IdentityTests(unittest.TestCase):
+    def registry(self):
+        return {}
+
+    def test_fixed_vector(self):
+        self.assertEqual(s.identifier(IDENTITY), EXPECTED)
+        self.assertEqual(s.canonical(IDENTITY), '{"business":"example-app","domain":"示例领域","kind":"backend_contract","page":"示例页面","trigger":"/页面/页面初始化事务"}')
+
+    def test_order_and_unicode(self):
+        self.assertEqual(s.identifier(dict(reversed(list(IDENTITY.items())))), EXPECTED)
+        self.assertEqual(s.identifier({**IDENTITY, 'page':'café'}), s.identifier({**IDENTITY, 'page':'cafe\u0301'}))
+        self.assertNotEqual(s.identifier({**IDENTITY, 'page':'Payment'}), EXPECTED)
+
+    def test_invalid_identity(self):
+        for value in [None, '', [], {}, 1, True, ' payment', 'payment\n', '\ud800']:
+            with self.subTest(value=repr(value)), self.assertRaises(ValueError):
+                s.identifier({**IDENTITY, 'page':value})
+        for value in [{**IDENTITY,'name':'title'}, {k:v for k,v in IDENTITY.items() if k!='page'}, {**IDENTITY,'identityVersion':'v2'}]:
+            with self.assertRaises(ValueError): s.identifier(value)
+
+    def test_source_coordinates(self):
+        for trigger in ['page_load', '/页面/~x', '/页面/~']:
+            with self.assertRaises(ValueError):
+                s.identifier({**IDENTITY, 'trigger':trigger})
+        self.assertNotEqual(s.identifier({**IDENTITY, 'domain':'其他领域'}), EXPECTED)
+        self.assertNotEqual(s.identifier({**IDENTITY, 'business':'其他业务'}), EXPECTED)
+        self.assertNotEqual(s.identifier({**IDENTITY, 'trigger':'/页面/页面返回时事务'}), EXPECTED)
+        with self.assertRaises(ValueError):
+            s.identifier({**IDENTITY, 'purpose':'query'})
+
+    def test_duplicate_json_keys(self):
+        with self.assertRaises(ValueError): json.loads('{"id":1,"id":2}', object_pairs_hook=s.unique_pairs)
+
+    def test_idempotence_and_append(self):
+        registry=self.registry()
+        s.register(registry, IDENTITY)
+        base=copy.deepcopy(registry)
+        s.register(registry, IDENTITY)
+        self.assertEqual(registry, base)
+        s.register(registry,{**IDENTITY,'trigger':'/页面/页面返回时事务'})
+        s.validate_append_only(base,registry)
+        s.check_active(registry,[{'id':EXPECTED,'identity':IDENTITY}])
+        s.check_active(registry,[]) # Retired identity stays registered.
+
+    def test_historical_deletion_and_change(self):
+        base=self.registry();s.register(base,IDENTITY)
+        with self.assertRaises(ValueError): s.validate_append_only(base,self.registry())
+        altered=copy.deepcopy(base);altered[EXPECTED]['page']='other'
+        with self.assertRaises(ValueError): s.validate_append_only(base,altered)
+
+    def test_unregistered_duplicate_or_wrong_active(self):
+        record={'id':EXPECTED,'identity':IDENTITY}
+        with self.assertRaises(ValueError): s.check_active(self.registry(),[record])
+        registry=self.registry();s.register(registry,IDENTITY)
+        with self.assertRaises(ValueError): s.check_active(registry,[record,record])
+        with self.assertRaises(ValueError): s.check_active(registry,[{**record,'id':'api_wrong'}])
+
+    def test_simulated_digest_collision(self):
+        registry=self.registry();s.register(registry,IDENTITY)
+        with patch.object(s,'identifier',return_value=EXPECTED):
+            with self.assertRaisesRegex(ValueError,'collision'):
+                s.register(registry,{**IDENTITY,'page':'other'})
+
+class SourceTests(unittest.TestCase):
+    page_path = 'example-app/spec/domains/示例领域/visual/示例页面.yaml'
+    guide = '## 页面初始化事务与终点响应\n缺少返回事务声明时整体复用初始化事务配置（包括成功响应）。'
+    def returning(self):
+        return {**IDENTITY, 'trigger':'/页面/页面返回时事务'}
+    def source(self):
+        return {'kind':'languageDefault', 'path':self.page_path, 'pointer':'/页面', 'rule':dict(source_api.RETURN_RULE)}
+    def validate(self, identity, source, document, **kw):
+        return source_api.validate_trigger_source(identity, source, document, page_path=self.page_path, language_guide=kw.get('guide',self.guide))
+    def test_inherited_return_distinct_from_initialization(self):
+        config={'响应':[]};doc={'页面':{'页面初始化事务':config}}
+        self.assertEqual(self.validate(self.returning(),self.source(),doc),config)
+        self.assertNotEqual(s.identifier(self.returning()),s.identifier(IDENTITY))
+    def test_explicit_empty_is_not_inheritance(self):
+        doc={'页面':{'页面返回时事务':{}}}
+        with self.assertRaises(ValueError):self.validate(self.returning(),self.source(),doc)
+        src={'kind':'explicit','path':self.page_path,'pointer':'/页面/页面返回时事务'}
+        self.assertEqual(self.validate(self.returning(),src,doc),{})
+    def test_wrong_event_rule_and_page_rejected(self):
+        for identity,src in [(IDENTITY,self.source()),(self.returning(),{**self.source(),'rule':{}}),(self.returning(),{**self.source(),'path':'other.yaml'})]:
+            with self.assertRaises(ValueError):self.validate(identity,src,{'页面':{}})
+        with self.assertRaises(ValueError):self.validate(self.returning(),self.source(),{'页面':{}},guide='')
+    def test_explicit_missing_or_wrong_pointer(self):
+        src={'kind':'explicit','path':self.page_path,'pointer':IDENTITY['trigger']}
+        with self.assertRaises(ValueError):self.validate(IDENTITY,src,{'页面':{}})
+        with self.assertRaises(ValueError):self.validate(IDENTITY,{**src,'pointer':'/页面'},{'页面':{}})
+    def test_pointer_escaping(self):
+        self.assertEqual(source_api.resolve_pointer({'a/b':{'~key':[7]}},'/a~1b/~0key/0'),7)
+        with self.assertRaises(ValueError):source_api.resolve_pointer({'a':[7]},'/a/00')
+
+class CliTests(unittest.TestCase):
+    def test_lifecycle_and_failed_write(self):
+        script=Path(s.__file__).resolve()
+        with tempfile.TemporaryDirectory() as directory:
+            root=Path(directory)
+            identity=root/'identity.json'; registry=root/'registry.json'
+            baseline=root/'baseline.json'; active=root/'active.json'
+            identity.write_text(json.dumps(IDENTITY),encoding='utf-8')
+            def run(*args):
+                return subprocess.run([sys.executable,str(script),*map(str,args)],capture_output=True,text=True)
+            generated=run('generate',identity)
+            self.assertEqual(generated.returncode,0,generated.stderr)
+            self.assertEqual(json.loads(generated.stdout)['id'],EXPECTED)
+            self.assertEqual(run('register',identity,'--registry',registry).returncode,0)
+            original=registry.read_bytes();baseline.write_bytes(original)
+            self.assertEqual(run('register',identity,'--registry',registry).returncode,0)
+            self.assertEqual(registry.read_bytes(),original)
+            active.write_text(json.dumps([{'id':EXPECTED,'identity':IDENTITY}]),encoding='utf-8')
+            self.assertEqual(run('check','--registry',registry,'--baseline',baseline,'--active',active).returncode,0)
+            identity.write_text('{"page":null}',encoding='utf-8')
+            self.assertNotEqual(run('register',identity,'--registry',registry).returncode,0)
+            self.assertEqual(registry.read_bytes(),original)
+            registry.write_text(json.dumps({}),encoding='utf-8')
+            active.write_text('[]',encoding='utf-8')
+            rejected=run('check','--registry',registry,'--baseline',baseline,'--active',active)
+            self.assertNotEqual(rejected.returncode,0)
+            self.assertIn('removed or changed',rejected.stderr)
+
+if __name__=='__main__': unittest.main()