devagent-ignition 0.1.0__py3-none-any.whl

devagent_hmi.py

@@ -0,0 +1,471 @@
+#!/usr/bin/env python3
+"""DevAgent Spatial HMI Engine — independent local design and validation tool.
+
+This program NEVER imports into Ignition, modifies PLC tags, or writes OPC UA.
+"""
+from __future__ import annotations
+import argparse
+import json
+import zipfile
+from functools import partial
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from devagent_spatial.generator import build, BuildHold, ROOT
+from devagent_spatial.model import qualify
+from devagent_spatial.strict_json import loads as strict_loads
+
+
+def main(argv=None):
+    p=argparse.ArgumentParser(description='DevAgent Spatial HMI — model-driven preview and static FAT contract generator (read-only)')
+    sub=p.add_subparsers(dest='action',required=True)
+    a=sub.add_parser('validate',help='Validate JSON project contract without writing files')
+    a.add_argument('--model',type=Path,required=True)
+    a=sub.add_parser('build',help='Create a NEW preview artifact directory (no overwrite)')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a.add_argument('--vendor-three',type=Path,default=None,help='Existing LOCAL Three.js r180 vendor directory with license; source is not changed')
+    a=sub.add_parser('studio',help='Start localhost customer project creator, no remote bind')
+    a.add_argument('--port',type=int,default=8895)
+    a.add_argument('--workspace',type=Path,default=Path.home()/'.local/share/devagent/spatial-projects')
+    a.add_argument('--vendor-three',type=Path,default=None,help='Optional local r180 vendor folder, e.g. R9 viewer web/vendor')
+    a=sub.add_parser('preview',help='Serve an existing generated preview over localhost HTTP')
+    a.add_argument('--project-dir',type=Path,required=True)
+    a.add_argument('--port',type=int,default=8896)
+    a=sub.add_parser('opc-snapshot',help='READ-ONLY isolated-lab OPC UA node/type/quality verification; no trigger or HMI claims')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--endpoint',required=True)
+    a.add_argument('--lab-confirm',required=True)
+    a=sub.add_parser('qualify',help='Independent artifact integrity/traceability audit, preview or production gate')
+    a.add_argument('--project-dir',type=Path,required=True)
+    a.add_argument('--purpose',choices=['preview','production'],default='preview')
+    a=sub.add_parser('audit-ignition',help='Read-only safety audit of a native Ignition Perspective ZIP (not import qualification)')
+    a.add_argument('--project-zip',type=Path,required=True)
+    a=sub.add_parser('ignition-list',help='List views in a customer-provided native Ignition project export, without mutation')
+    a.add_argument('--reference-zip',type=Path,required=True)
+    a=sub.add_parser('ignition-candidate',help='Build read-only native Perspective view RESOURCE overlay (not a verified project export)')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--reference-zip',type=Path,required=True)
+    a.add_argument('--reference-sha256',required=True)
+    a.add_argument('--template-view',required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a=sub.add_parser('ignition-verify-candidate',help='Independently compare view candidate against original customer model and reference')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--reference-zip',type=Path,required=True)
+    a.add_argument('--reference-sha256',required=True)
+    a.add_argument('--template-view',required=True)
+    a.add_argument('--candidate',type=Path,required=True)
+    a=sub.add_parser('ignition-project-candidate',help='Build a NEW minimal read-only isolated Ignition project ZIP candidate; never imports')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--reference-zip',type=Path,required=True)
+    a.add_argument('--reference-sha256',required=True)
+    a.add_argument('--template-view',required=True)
+    a.add_argument('--new-project-name',required=True)
+    a.add_argument('--confirm',required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a=sub.add_parser('ignition-verify-project',help='Independently verify a new minimal project candidate')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--reference-zip',type=Path,required=True)
+    a.add_argument('--reference-sha256',required=True)
+    a.add_argument('--template-view',required=True)
+    a.add_argument('--new-project-name',required=True)
+    a.add_argument('--candidate',type=Path,required=True)
+    a=sub.add_parser('ops-studio-lab',help='Create copy-only Studio import CSV + lab-only remapped model, original unchanged')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--out-dir',type=Path,required=True)
+    a.add_argument('--confirm',required=True)
+    a=sub.add_parser('ops-demo',help='Create synthetic LAB ONLY alarm/KPI replay JSON, never live proof')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a=sub.add_parser('ops-evaluate',help='Validate external isolated-lab observation frames by exact customer tag identity')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--frames',type=Path,required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a=sub.add_parser('ops-capture',help='Bounded READ ONLY OPC UA capture on approved isolated lab endpoint')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--endpoint',required=True)
+    a.add_argument('--lab-confirm',required=True)
+    a.add_argument('--samples',type=int,default=3)
+    a.add_argument('--out',type=Path,required=True)
+    a=sub.add_parser('v07-binding-skeleton',help='Create NEW customer lab-tag manifest template, with NO guessed tag paths')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a=sub.add_parser('v07-native-compile',help='Compile isolated native Perspective project candidate with read-only lab bindings + route')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--binding-manifest',type=Path,required=True)
+    a.add_argument('--reference-zip',type=Path,required=True)
+    a.add_argument('--reference-sha256',required=True)
+    a.add_argument('--template-view',required=True)
+    a.add_argument('--new-project-name',required=True)
+    a.add_argument('--confirm',required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a=sub.add_parser('v07-native-verify',help='Byte-for-byte independent verifier for V0.7 offline project candidate')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--binding-manifest',type=Path,required=True)
+    a.add_argument('--reference-zip',type=Path,required=True)
+    a.add_argument('--reference-sha256',required=True)
+    a.add_argument('--template-view',required=True)
+    a.add_argument('--new-project-name',required=True)
+    a.add_argument('--candidate',type=Path,required=True)
+    a=sub.add_parser('v07-fat-plan',help='Create unexecuted per-signal FAT plan: signal coverage and quality transitions')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--binding-manifest',type=Path,required=True)
+    a.add_argument('--out',type=Path,required=True)
+    for action in ('v083-native-compile', 'v083-native-verify'):
+        a=sub.add_parser(action,help='Create/verify native operator candidate; UI selection only, no command authority')
+        a.add_argument('--model',type=Path,required=True)
+        a.add_argument('--binding-manifest',type=Path,required=True)
+        a.add_argument('--operator-policy',type=Path,help='Reviewed PE association and freshness policy; omitted means all pending')
+        a.add_argument('--reference-zip',type=Path,required=True)
+        a.add_argument('--reference-sha256',required=True)
+        a.add_argument('--template-view',required=True)
+        a.add_argument('--new-project-name',required=True)
+        if action=='v083-native-compile':
+            a.add_argument('--confirm',required=True)
+            a.add_argument('--out',type=Path,required=True)
+        else:
+            a.add_argument('--candidate',type=Path,required=True)
+    a=sub.add_parser('v07-fat-assess',help='Evaluate supplied OPC/Tag/HMI phase consistency; never asserts live FAT PASS')
+    a.add_argument('--candidate',type=Path,required=True)
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--binding-manifest',type=Path,required=True)
+    a.add_argument('--observations',type=Path,required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a=sub.add_parser('v076-opc-plan',help='Generate synthetic OPC UA lab plan only; no protocol execution')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a=sub.add_parser('v076-opc-fat',help='Execute READ-ONLY-TO-CLIENTS fake OPC UA loopback FAT with independent client; NO IGNITION CLAIM')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a.add_argument('--port',type=int,default=4898)
+    a.add_argument('--confirm',required=True)
+    a=sub.add_parser('v078-command-template',help='Create UNAPPROVED lab-only Device Command Contract for a declared equipment ID')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--asset-id',required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a=sub.add_parser('v078-virtual-plc-serve',help='Serve bounded live fake OPC UA Virtual PLC on localhost for manual Ignition FAT')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--contract',type=Path,required=True)
+    a.add_argument('--port',type=int,default=4899)
+    a.add_argument('--seconds',type=int,default=300)
+    a.add_argument('--confirm',required=True)
+    a=sub.add_parser('v078-virtual-plc-fat',help='Execute fake OPC UA START/STOP/RESET interlock/feedback FAT on loopback only')
+    a.add_argument('--model',type=Path,required=True)
+    a.add_argument('--contract',type=Path,required=True)
+    a.add_argument('--out',type=Path,required=True)
+    a.add_argument('--port',type=int,default=4899)
+    a.add_argument('--confirm',required=True)
+    for action in ('v078-native-compile','v078-native-verify'):
+        a=sub.add_parser(action,help='Create/verify disabled-by-default LAB ONLY Perspective device command project candidate')
+        a.add_argument('--model',type=Path,required=True)
+        a.add_argument('--contract',type=Path,required=True)
+        a.add_argument('--binding-manifest',type=Path,required=True)
+        a.add_argument('--reference-zip',type=Path,required=True)
+        a.add_argument('--reference-sha256',required=True)
+        a.add_argument('--template-view',required=True)
+        a.add_argument('--new-project-name',required=True)
+        a.add_argument('--confirm',default='',required=action=='v078-native-compile')
+        if action=='v078-native-compile':a.add_argument('--out',type=Path,required=True)
+        else:a.add_argument('--candidate',type=Path,required=True)
+    a=sub.add_parser('preflight',help='Offline cross-project release checks; does NOT certify Ignition runtime')
+    a.add_argument('--reference-zip',type=Path,default=None)
+    a.add_argument('--reference-sha256',default=None)
+    a.add_argument('--template-view',default=None)
+    a.add_argument('--report',type=Path,default=None,help='Create a new JSON report; refuses overwrite')
+    a=sub.add_parser('examples',help='Show bundled customer model examples')
+    args=p.parse_args(argv)
+    if args.action.startswith('v078-'):
+        from devagent_spatial.v078_commands import (contract_template,validate_contract,run_virtual_plc_fat,
+            CommandHold,LAB_CONFIRM)
+        try:
+            if args.model.stat().st_size>2_000_000:raise CommandHold('MODEL_TOO_LARGE')
+            model=strict_loads(args.model.read_text(encoding='utf8'))
+            if args.action=='v078-command-template':
+                result=contract_template(model,args.asset_id)
+                with args.out.open('x',encoding='utf8') as f:
+                    json.dump(result,f,indent=2);f.write('\n')
+                print(json.dumps({'status':'PENDING_LAB_REVIEW','file':str(args.out),'production':'HOLD'}))
+                return 0
+            if args.contract.stat().st_size>100_000:raise CommandHold('CONTRACT_TOO_LARGE')
+            contract=strict_loads(args.contract.read_text(encoding='utf8'))
+            validate_contract(model,contract,require_lab_approval=True)
+            if args.action=='v078-virtual-plc-serve':
+                import asyncio
+                from devagent_spatial.v078_commands import serve_virtual_plc
+                print('LAB_VPLC_ENDPOINT=opc.tcp://127.0.0.1:'+str(args.port)+'/devagent-virtual-plc/')
+                print('LAB_VPLC_ONLY=YES | IGNITION_GATEWAY=NOT_VERIFIED | PRODUCTION=HOLD',flush=True)
+                result=asyncio.run(serve_virtual_plc(model,contract,port=args.port,
+                      seconds=args.seconds,confirm=args.confirm))
+                print(json.dumps(result,indent=2));return 0
+            if args.action=='v078-virtual-plc-fat':
+                import asyncio
+                result=asyncio.run(asyncio.wait_for(run_virtual_plc_fat(
+                    model,contract,port=args.port,confirm=args.confirm),timeout=45))
+                with args.out.open('x',encoding='utf8') as f:
+                    json.dump(result,f,indent=2);f.write('\n')
+                print(json.dumps({'status':result['status'],'file':str(args.out),'production':'HOLD'}))
+                return 0 if result['status'].startswith('PASS_') else 2
+            from devagent_spatial.v078_native_commands import compile_lab_native,verify_lab_native
+            from devagent_spatial.ignition_native import NativeHold
+            if args.binding_manifest.stat().st_size>2_000_000:raise CommandHold('BINDING_MANIFEST_TOO_LARGE')
+            binding_manifest=strict_loads(args.binding_manifest.read_text(encoding='utf8'))
+            if args.action=='v078-native-compile':
+                result=compile_lab_native(model,binding_manifest,contract,args.reference_zip,
+                    args.template_view,args.reference_sha256,args.new_project_name,args.out,args.confirm)
+            else:
+                result=verify_lab_native(model,binding_manifest,contract,args.reference_zip,
+                    args.template_view,args.reference_sha256,args.new_project_name,args.candidate)
+            print(json.dumps(result,indent=2));return 0
+        except (OSError,CommandHold,ValueError,TypeError,KeyError,RecursionError,Exception) as ex:
+            # Only known stable error codes leave the CLI; never leak model credentials/hostnames.
+            from devagent_spatial.ignition_native import NativeHold
+            if not isinstance(ex,(OSError,CommandHold,ValueError,TypeError,KeyError,RecursionError,NativeHold)):
+                raise
+            code=str(ex)
+            import re
+            if not re.fullmatch('[A-Z0-9_:]{3,170}',code):code='LAB_COMMAND_OR_NATIVE_COMPILER_HOLD'
+            print('HOLD=V078: '+code);return 2
+    if args.action in ('v076-opc-plan','v076-opc-fat'):
+        from devagent_spatial.v076_opc_fat import plan,run_loopback_fat,save_new,LabHold
+        import asyncio
+        try:
+            if args.action=='v076-opc-fat' and args.confirm!='ISOLATED_FAKE_OPC_LOOPBACK_ONLY':
+                raise LabHold('EXPLICIT_LAB_CONFIRMATION_REQUIRED')
+            if args.model.stat().st_size>2_000_000:raise LabHold('MODEL_FILE_TOO_LARGE')
+            model=strict_loads(args.model.read_text(encoding='utf8'))
+            result=(plan(model) if args.action=='v076-opc-plan' else
+                    asyncio.run(asyncio.wait_for(run_loopback_fat(model,args.port),timeout=50)))
+            save_new(args.out,result)
+            print(json.dumps({'status':result['status'],'report':str(args.out),
+                'production':'HOLD','ignition':'NOT_VERIFIED'},indent=2))
+            return 0 if result['status'] in ('NOT_EXECUTED','PASS_LAB_OPC_PROTOCOL_ONLY') else 2
+        except (OSError,LabHold,ValueError,TypeError,KeyError,RecursionError) as e:
+            print('HOLD=V076_FAKE_OPC_FAT: '+str(e)[:160]);return 2
+    if args.action in ('v083-native-compile','v083-native-verify'):
+        from devagent_spatial.v083_native import candidate, policy_skeleton
+        from devagent_spatial.ignition_native import NativeHold
+        try:
+            for path in (args.model,args.binding_manifest,args.operator_policy):
+                if path and path.stat().st_size>2_000_000:
+                    raise NativeHold('OPERATOR_INPUT_TOO_LARGE')
+            model=strict_loads(args.model.read_text(encoding='utf8'))
+            manifest=strict_loads(args.binding_manifest.read_text(encoding='utf8'))
+            policy=(strict_loads(args.operator_policy.read_text(encoding='utf8'))
+                    if args.operator_policy else policy_skeleton(model))
+            verify=args.action=='v083-native-verify'
+            result=candidate(model,manifest,policy,args.reference_zip,args.template_view,
+                args.reference_sha256,args.new_project_name,
+                args.candidate if verify else args.out,verify=verify,
+                confirm='' if verify else args.confirm)
+            print(json.dumps(result,indent=2,ensure_ascii=False));return 0
+        except (NativeHold,OSError,ValueError,TypeError,KeyError,zipfile.BadZipFile,RecursionError) as ex:
+            print('HOLD=V083: '+str(ex)[:300]);return 2
+    if args.action.startswith('v07-'):
+        from devagent_spatial.v07_native import (manifest_skeleton, compile_lab, verify_lab,
+                    fat_plan, NativeHold)
+        try:
+            if args.model.stat().st_size>2_000_000:raise NativeHold('MODEL_FILE_TOO_LARGE')
+            model=strict_loads(args.model.read_text(encoding='utf8'))
+            if args.action=='v07-binding-skeleton':
+                result=manifest_skeleton(model)
+            else:
+                if args.binding_manifest.stat().st_size>2_000_000:raise NativeHold('MANIFEST_FILE_TOO_LARGE')
+                manifest=strict_loads(args.binding_manifest.read_text(encoding='utf8'))
+                if args.action=='v07-fat-assess':
+                    from devagent_spatial.v07_fat import assess
+                    if args.observations.stat().st_size>2_000_000:raise NativeHold('OBSERVATIONS_TOO_LARGE')
+                    observations=strict_loads(args.observations.read_text(encoding='utf8'))
+                    result=assess(model,manifest,observations,args.candidate)
+                elif args.action=='v07-native-compile':
+                    result=compile_lab(model,manifest,args.reference_zip,args.template_view,
+                        args.reference_sha256,args.new_project_name,args.out,args.confirm)
+                elif args.action=='v07-native-verify':
+                    result=verify_lab(model,manifest,args.reference_zip,args.template_view,
+                        args.reference_sha256,args.new_project_name,args.candidate)
+                else:result=fat_plan(model,manifest)
+            if args.action in ('v07-binding-skeleton','v07-fat-plan','v07-fat-assess'):
+                with args.out.expanduser().open('x',encoding='utf8') as f:
+                    json.dump(result,f,indent=2,ensure_ascii=False);f.write('\n')
+                print(json.dumps({'status':result.get('status','PASS_UNEXECUTED_PLAN_ONLY'),
+                       'file':str(args.out), 'production_release':'HOLD',
+                       'gateway_fat':'NOT_VERIFIED'},indent=2))
+            else:print(json.dumps(result,indent=2,ensure_ascii=False))
+            return 0
+        except (NativeHold,OSError,ValueError,TypeError,KeyError,zipfile.BadZipFile,RecursionError) as e:
+            print('HOLD=V07: '+str(e)[:400]);return 2
+    if args.action=='ops-studio-lab':
+        from devagent_spatial.operations_lab import create_lab_derivative
+        from devagent_spatial.operations import OperationsHold
+        try:
+            if args.model.stat().st_size>2_000_000:raise OperationsHold('MODEL_TOO_LARGE')
+            original=strict_loads(args.model.read_text(encoding='utf-8'))
+            result=create_lab_derivative(original,args.out_dir,args.confirm)
+            print(json.dumps(result,indent=2,ensure_ascii=False))
+            return 0
+        except (OSError,ValueError,KeyError,OperationsHold) as exc:
+            print('HOLD=STUDIO_LAB_ALIAS: '+str(exc)[:300]);return 2
+    if args.action in ('ops-demo','ops-evaluate','ops-capture'):
+        from devagent_spatial.operations import (evaluate,make_synthetic_frames,OperationsHold)
+        try:
+            if args.model.stat().st_size>2_000_000:raise OperationsHold('MODEL_TOO_LARGE')
+            model=strict_loads(args.model.read_text(encoding='utf-8'))
+            if args.action=='ops-demo':
+                frames=make_synthetic_frames(model)
+                origin='SYNTHETIC_OFFLINE_FIXTURE'
+            elif args.action=='ops-evaluate':
+                if args.frames.stat().st_size>2_000_000:raise OperationsHold('FRAMES_TOO_LARGE')
+                frames=strict_loads(args.frames.read_text(encoding='utf-8'))
+                origin='SYNTHETIC_OFFLINE_FIXTURE' # Unproven supplied frames cannot claim verified Studio readings.
+            else:
+                if args.lab_confirm!='ISOLATED_TEST_ONLY':raise OperationsHold('EXPLICIT_LAB_CONFIRMATION_REQUIRED')
+                if not 1<=args.samples<=12:raise OperationsHold('UNSAFE_CAPTURE_SAMPLE_COUNT')
+                import asyncio
+                from devagent_spatial.operations_capture import capture_lab
+                frames=asyncio.run(capture_lab(model,args.endpoint,args.samples))
+                origin='ISOLATED_LAB_OPC_READ_ONLY'
+            receipt=evaluate(model,frames,origin=origin)
+            with args.out.expanduser().open('x',encoding='utf-8') as f:
+                json.dump(receipt,f,indent=2,ensure_ascii=False)
+                f.write('\n')
+            print(json.dumps({'status':receipt['status'],'file':str(args.out),'frames':len(receipt['frames']),
+                              'events':len(receipt['events']),'mapping_digest':receipt['mapping_digest'],
+                              'ignition_hmi':'NOT_VERIFIED','plc_writes':'DISABLED'},indent=2))
+            return 0
+        except (OSError,ValueError,TypeError,KeyError,OperationsHold) as exc:
+            print('HOLD=OPERATIONS: '+str(exc)[:300]);return 2
+    if args.action=='preflight':
+        from devagent_spatial.preflight import preflight
+        result=preflight(reference_zip=args.reference_zip,
+                         reference_sha256=args.reference_sha256,template_view=args.template_view)
+        blob=json.dumps(result,indent=2,ensure_ascii=False)+'\n'
+        if args.report:
+            try:
+                with args.report.open('x',encoding='utf-8') as f:f.write(blob)
+            except (OSError,ValueError) as exc:
+                print('HOLD=REPORT_CREATE_ONLY: '+str(exc));return 2
+        print(blob)
+        return 0 if result['status']=='PASS_OFFLINE_PRETEST_ONLY' else 2
+    if args.action in ('ignition-project-candidate','ignition-verify-project'):
+        from devagent_spatial.ignition_project import compile_project, verify_project
+        from devagent_spatial.ignition_native import NativeHold
+        try:
+            if args.model.stat().st_size>2_000_000:raise NativeHold('MODEL_FILE_TOO_LARGE')
+            model=strict_loads(args.model.read_text(encoding='utf-8'))
+            if args.action=='ignition-project-candidate':
+                result=compile_project(model,args.reference_zip,args.template_view,
+                                       args.reference_sha256,args.new_project_name,args.out,args.confirm)
+            else:
+                result=verify_project(model,args.reference_zip,args.template_view,
+                                      args.reference_sha256,args.new_project_name,args.candidate)
+            print(json.dumps(result,indent=2,ensure_ascii=False))
+            return 0
+        except (NativeHold,OSError,ValueError,KeyError,TypeError,zipfile.BadZipFile,RecursionError) as exc:
+            print('HOLD=IGNITION_PROJECT: '+str(exc)[:350])
+            return 2
+    if args.action in ('ignition-list','ignition-candidate','ignition-verify-candidate'):
+        from devagent_spatial.ignition_native import (find_views, compile_candidate,
+                                                       verify_candidate,NativeHold)
+        try:
+            if args.action=='ignition-list':
+                result=find_views(args.reference_zip)
+            else:
+                if args.model.stat().st_size>2_000_000:raise NativeHold('MODEL_FILE_TOO_LARGE')
+                data=strict_loads(args.model.read_text(encoding='utf-8'))
+                if args.action=='ignition-candidate':
+                    result=compile_candidate(data,args.reference_zip,args.template_view,
+                                             args.reference_sha256,args.out)
+                else:
+                    result=verify_candidate(data,args.reference_zip,args.template_view,
+                                            args.reference_sha256,args.candidate)
+            print(json.dumps(result,indent=2,ensure_ascii=False))
+            return 0
+        except (NativeHold,OSError,ValueError,KeyError,TypeError,zipfile.BadZipFile) as e:
+            print('HOLD=IGNITION_NATIVE: '+str(e))
+            return 2
+    if args.action=='opc-snapshot':
+        from devagent_spatial.opc_snapshot import probe_live, SnapshotHold
+        import asyncio
+        if args.lab_confirm!='ISOLATED_TEST_ONLY':
+            print('HOLD=EXPLICIT_ISOLATED_LAB_CONFIRMATION_REQUIRED');return 2
+        try:
+            if args.model.stat().st_size>2_000_000:raise ValueError('MODEL_FILE_TOO_LARGE')
+            model=strict_loads(args.model.read_text(encoding='utf8'))
+            result=asyncio.run(probe_live(model,args.endpoint))
+            print(json.dumps(result,indent=2,ensure_ascii=False))
+            return 0 if result['status']=='PASS_LAB_PROTOCOL_SNAPSHOT_ONLY' else 2
+        except (OSError,ValueError,SnapshotHold) as e:
+            print('HOLD=OPC_SNAPSHOT: '+str(e));return 2
+    if args.action=='qualify':
+        from devagent_spatial.qualification import audit
+        report=audit(args.project_dir,purpose=args.purpose)
+        print(json.dumps(report,indent=2,ensure_ascii=False))
+        return 0 if report['status']=='PASS_CONCEPT_PREVIEW_ONLY' else 2
+    if args.action=='audit-ignition':
+        from devagent_spatial.native_reference import audit_ignition_archive
+        report=audit_ignition_archive(args.project_zip)
+        print(json.dumps(report,indent=2,ensure_ascii=False))
+        return 0 if report['status']=='PASS_ZIP_SAFETY_ONLY' else 2
+    if args.action=='examples':
+        print('WAREHOUSE_EXAMPLE='+str(ROOT/'examples/warehouse.json'))
+        print('WATER_TREATMENT_EXAMPLE='+str(ROOT/'examples/water.json'))
+        print('SINGLE_FLOOR_EXAMPLE='+str(ROOT/'examples/single_floor.json'))
+        return 0
+    if args.action in ('validate','build'):
+        try:
+            raw_path=args.model.expanduser()
+            if raw_path.stat().st_size > 2_000_000:raise ValueError('INPUT_FILE_TOO_LARGE')
+            data=strict_loads(raw_path.read_text(encoding='utf-8'))
+        except (OSError,ValueError,RecursionError,UnicodeError) as e:
+            print('HOLD=INPUT_UNREADABLE_OR_INVALID_JSON: '+str(e))
+            return 2
+        if args.action=='validate':
+            report=qualify(data)
+            print(json.dumps(report,indent=2,ensure_ascii=False))
+            return 0 if report['status']!='HOLD' else 2
+        try:
+            result=build(data,args.out,vendor_three=args.vendor_three)
+            print(json.dumps(result,indent=2,ensure_ascii=False))
+            return 0
+        except (BuildHold,OSError,ValueError) as e:
+            print('HOLD='+str(e))
+            return 2
+    if not 1024<=args.port<=65535:
+        print('HOLD=INVALID_PORT')
+        return 2
+    if args.action=='studio':
+        from devagent_spatial.studio import StudioServer
+        try:
+            server=StudioServer(('127.0.0.1',args.port),args.workspace,args.vendor_three)
+        except (OSError,ValueError,RecursionError,UnicodeError) as e:
+            print('HOLD=STUDIO_START: '+str(e))
+            return 2
+        print('DEVAGENT_SPATIAL_STUDIO=READY',flush=True)
+        print(f'LOCAL_UI=http://127.0.0.1:{args.port}/',flush=True)
+        print(f'CUSTOMER_PROJECTS={server.workspace}',flush=True)
+        print('WRITE_AUTHORITY=DISABLED; IGNITION_MODIFICATIONS=NONE',flush=True)
+        try:server.serve_forever(poll_interval=.2)
+        except KeyboardInterrupt:pass
+        finally:server.server_close()
+        return 0
+    if args.action=='preview':
+        project=args.project_dir.expanduser().resolve()
+        viewer=project/'viewer'
+        if not (viewer/'index.html').is_file() or not (project/'BUILD.json').is_file():
+            print('HOLD=NOT_A_GENERATED_DEVAGENT_PREVIEW')
+            return 2
+        class Handler(SimpleHTTPRequestHandler):
+            def end_headers(self):
+                self.send_header('X-Content-Type-Options','nosniff');self.send_header('Cache-Control','no-store')
+                super().end_headers()
+        try:
+            server=ThreadingHTTPServer(('127.0.0.1',args.port),partial(Handler,directory=str(viewer)))
+        except OSError as e:
+            print('HOLD=PREVIEW_PORT: '+str(e))
+            return 2
+        print(f'PREVIEW=http://127.0.0.1:{args.port}/',flush=True)
+        try:server.serve_forever(poll_interval=.2)
+        except KeyboardInterrupt:pass
+        finally:server.server_close()
+        return 0
+    return 2
+
+if __name__=='__main__':raise SystemExit(main())