devagent-ignition 0.1.0__py3-none-any.whl

devagent_spatial/v078_commands.py

@@ -0,0 +1,277 @@
+"""V0.7.8 isolated Device Command Contract and Virtual PLC FAT.
+
+No production endpoints accepted. Control authority is restricted to a single
+fake OPC UA server on loopback. Native Perspective output is a disabled-by-default
+lab candidate until independently imported/tested on an isolated Ignition Gateway.
+"""
+from __future__ import annotations
+import asyncio
+import datetime as dt
+import hashlib
+import json
+import re
+import uuid
+from pathlib import Path
+from .model import qualify
+
+SCHEMA = 'devagent.device_command_contract.v078'
+REPORT_SCHEMA = 'devagent.fat.device_commands.v078'
+LAB_NS_PREFIX = 'urn:devagent:isolated:virtual-plc:v078:'
+COMMANDS = ('START', 'STOP', 'RESET')
+SUPPORTED = frozenset({'conveyor', 'spiral', 'sorter', 'motor', 'vfd', 'pump'})
+ASSET_RE = re.compile(r'[A-Za-z][A-Za-z0-9_]{1,59}\Z')
+LAB_PROVIDER = 'DevAgentLabCommands'
+LAB_CONFIRM = 'ISOLATED_VIRTUAL_PLC_LOOPBACK_ONLY'
+
+class CommandHold(ValueError):
+    pass
+
+
+def digest(model):
+    return hashlib.sha256(json.dumps(model, ensure_ascii=False, sort_keys=True,
+                             separators=(',', ':')).encode()).hexdigest()
+
+
+def contract_template(model:dict, asset_id:str) -> dict:
+    """Build *unapproved* lab contract; never infer a physical PLC address."""
+    if qualify(model)['status'] != 'PASS_STATIC_CONTRACT_ONLY':
+        raise CommandHold('CUSTOMER_MODEL_HOLD')
+    assets = [x for x in model['equipment'] if x['id'] == asset_id]
+    if len(assets) != 1 or assets[0]['kind'] not in SUPPORTED or not ASSET_RE.fullmatch(asset_id):
+        raise CommandHold('EQUIPMENT_NOT_ELIGIBLE_FOR_DEMO_COMMANDS')
+    base = '[%s]VirtualPLC/%s/' % (LAB_PROVIDER, asset_id)
+    return {'schema':SCHEMA, 'model_sha256':digest(model),
+            'scope':'ISOLATED_FAKE_OPCUA_ONLY','asset_id':asset_id,
+            'kind':assets[0]['kind'], 'actions':list(COMMANDS),
+            'tag_paths':{'request':base+'CommandRequest','ack_id':base+'AckId',
+                'result':base+'CommandResult','state':base+'State',
+                'run_feedback':base+'RunFeedback','fault':base+'Fault',
+                'permissive':base+'Permissive'},
+            'simulated_namespace_uri':LAB_NS_PREFIX+digest(model)[:16],
+            'engineer':'','approval':'PENDING_LAB_REVIEW',
+            'timeout_ms':2500, 'role':'Authenticated/Roles/DevAgentLabOperator',
+            'command_identity':'LAB_SYNTHETIC_NOT_CUSTOMER_TAG',
+            'production_mapping':None, 'production_authority':'NONE',
+            'note':'Explicit lab-only contract. No customer NodeIds or field authorization.'}
+
+
+def validate_contract(model, c, *, require_lab_approval=False):
+    if not isinstance(c,dict) or set(c)!=set(contract_template(model,c.get('asset_id',''))):
+        raise CommandHold('COMMAND_CONTRACT_SCHEMA_MISMATCH')
+    skeleton=contract_template(model,c['asset_id'])
+    immutable=['schema','model_sha256','scope','asset_id','kind','actions','tag_paths',
+               'simulated_namespace_uri','timeout_ms','role','command_identity',
+               'production_mapping','production_authority']
+    for key in immutable:
+        if c[key] != skeleton[key]: raise CommandHold('COMMAND_CONTRACT_FIELD_MISMATCH:'+key)
+    if not isinstance(c['note'],str) or len(c['note'])>400:
+        raise CommandHold('CONTRACT_NOTE_INVALID')
+    if require_lab_approval:
+        if c['approval']!='APPROVED_FOR_ISOLATED_FAT_ONLY' or not isinstance(c['engineer'],str) or not 3<=len(c['engineer'].strip())<=100:
+            raise CommandHold('EXPLICIT_ENGINEER_LAB_APPROVAL_REQUIRED')
+    elif c['approval'] not in ('PENDING_LAB_REVIEW','APPROVED_FOR_ISOLATED_FAT_ONLY'):
+        raise CommandHold('CONTRACT_APPROVAL_INVALID')
+    return c
+
+
+def transition(state, action, permissive, fault):
+    """Functional control model; independent oracle for OPC UA readback tests."""
+    if action not in COMMANDS: return state,'REJECTED_UNKNOWN_COMMAND'
+    if action=='STOP': return 'FAULT' if fault else 'STOPPED','ACCEPTED_STOP'
+    if action=='RESET':
+        if state=='FAULT' and fault: return 'STOPPED','ACCEPTED_RESET'
+        return state,'REJECTED_RESET_REQUIRES_FAULT'
+    if fault or state=='FAULT': return state,'REJECTED_FAULT_ACTIVE'
+    if not permissive: return state,'REJECTED_PERMISSIVE'
+    if state!='STOPPED': return state,'REJECTED_NOT_STOPPED'
+    return 'RUNNING','ACCEPTED_START'
+
+
+async def run_virtual_plc_fat(model, contract:dict, *, port=4899, confirm=None):
+    """Run a local OPC UA server + independent TCP OPC UA client command/feedback FAT.
+
+    Client writes are limited to the synthetic CommandRequest node on 127.0.0.1.
+    All mechanical interlocks here are simulated, not field-proven.
+    """
+    if confirm!=LAB_CONFIRM: raise CommandHold('LAB_CONFIRM_REQUIRED')
+    validate_contract(model,contract,require_lab_approval=True)
+    if type(port) is not int or not 1024<=port<=65535:raise CommandHold('PORT_INVALID')
+    try:
+        from asyncua import Server, Client, ua
+    except ImportError as ex:
+        raise CommandHold('ASYNCUA_NOT_INSTALLED_REAL_OPC_TEST_NOT_RUN') from ex
+    server=Server()
+    await server.init()
+    uri=contract['simulated_namespace_uri']
+    endpoint='opc.tcp://127.0.0.1:%d/devagent-virtual-plc/' % port
+    server.set_endpoint(endpoint)
+    server.set_server_name('DevAgent V078 ISOLATED VIRTUAL PLC (NOT PHYSICAL)')
+    server.set_security_policy([ua.SecurityPolicyType.NoSecurity])
+    namespace=await server.register_namespace(uri)
+    root=await server.nodes.objects.add_object(namespace, 'VirtualPLC_'+contract['asset_id'])
+    # Test node identities are generated solely inside a fresh lab namespace.
+    variables={}
+    node_types={'CommandRequest':ua.VariantType.String,'AckId':ua.VariantType.String,
+                'CommandResult':ua.VariantType.String,'State':ua.VariantType.String,
+                'RunFeedback':ua.VariantType.Boolean,'Fault':ua.VariantType.Boolean,
+                'Permissive':ua.VariantType.Boolean}
+    initials={'CommandRequest':'','AckId':'','CommandResult':'IDLE',
+              'State':'STOPPED','RunFeedback':False,'Fault':False,'Permissive':True}
+    for name in node_types:
+        nid=ua.NodeId('VPLC/'+contract['asset_id']+'/'+name,namespace)
+        variables[name]=await root.add_variable(nid,name,ua.Variant(initials[name],node_types[name]))
+    # Only command request is client-writable. No physical output is present.
+    await variables['CommandRequest'].set_writable()
+    state={'value':'STOPPED','fault':False,'permissive':True}
+    processed=set()
+    stop=asyncio.Event()
+    async def worker():
+        while not stop.is_set():
+            raw=await variables['CommandRequest'].read_value()
+            if raw and raw not in processed:
+                processed.add(raw)
+                try:
+                    req,action=raw.split('|',1)
+                    if not re.fullmatch('[0-9a-f]{32}',req):raise ValueError
+                except ValueError:
+                    req='INVALID';action='INVALID'
+                new,outcome=transition(state['value'],action,state['permissive'],state['fault'])
+                if outcome=='ACCEPTED_RESET':state['fault']=False
+                state['value']=new
+                await variables['State'].write_value(new)
+                await variables['Fault'].write_value(state['fault'])
+                await variables['RunFeedback'].write_value(new=='RUNNING')
+                await variables['CommandResult'].write_value(outcome)
+                await variables['AckId'].write_value(req)
+            await asyncio.sleep(.02)
+    tests=[]
+    async def scenario(client,action,expected_state,expected_result):
+        request_id=uuid.uuid4().hex
+        await client.get_node(ua.NodeId('VPLC/'+contract['asset_id']+'/CommandRequest',ns_client)).write_value(request_id+'|'+action)
+        deadline=asyncio.get_running_loop().time()+contract['timeout_ms']/1000
+        observations={}
+        while asyncio.get_running_loop().time()<deadline:
+            readings={}
+            for name in ('AckId','CommandResult','State','RunFeedback','Fault','Permissive'):
+                remote=client.get_node(ua.NodeId('VPLC/'+contract['asset_id']+'/'+name,ns_client))
+                dv=await remote.read_data_value(raise_on_bad_status=False)
+                readings[name]=dv
+            if readings['AckId'].Value.Value==request_id:
+                observations={k:v.Value.Value for k,v in readings.items()}
+                observations['all_quality_good']=all(v.StatusCode.is_good() for v in readings.values())
+                break
+            await asyncio.sleep(.03)
+        passed=bool(observations and observations['all_quality_good'] and
+            observations['State']==expected_state and observations['CommandResult']==expected_result and
+            observations['RunFeedback']==(expected_state=='RUNNING'))
+        tests.append({'command':action,'expected_state':expected_state,'expected_result':expected_result,
+            'status':'PASS_LAB_ONLY' if passed else 'FAIL',
+            'observed':{k:v for k,v in observations.items() if k!='AckId'},
+            'independent_opc_tcp':True})
+        if not passed:raise CommandHold('OPC_COMMAND_ACK_OR_FEEDBACK_MISMATCH_'+action)
+
+    try:
+        async with server:
+            task=asyncio.create_task(worker())
+            try:
+                # TCP client has its own OPC UA session independent of server memory.
+                async with Client(endpoint,timeout=4) as client:
+                    arr=await client.get_namespace_array()
+                    if uri not in arr:raise CommandHold('SYNTHETIC_NAMESPACE_MISMATCH')
+                    ns_client=arr.index(uri)
+                    await scenario(client,'START','RUNNING','ACCEPTED_START')
+                    await scenario(client,'START','RUNNING','REJECTED_NOT_STOPPED')
+                    await scenario(client,'STOP','STOPPED','ACCEPTED_STOP')
+                    await scenario(client,'RESET','STOPPED','REJECTED_RESET_REQUIRES_FAULT')
+                    # Fault stimulus is *server-side* only, not a writable OPC tag.
+                    state.update(value='FAULT',fault=True)
+                    await variables['State'].write_value('FAULT')
+                    await variables['Fault'].write_value(True)
+                    await scenario(client,'START','FAULT','REJECTED_FAULT_ACTIVE')
+                    await scenario(client,'RESET','STOPPED','ACCEPTED_RESET')
+                    state['permissive']=False
+                    await variables['Permissive'].write_value(False)
+                    await scenario(client,'START','STOPPED','REJECTED_PERMISSIVE')
+                    state['permissive']=True
+                    await variables['Permissive'].write_value(True)
+                    await scenario(client,'START','RUNNING','ACCEPTED_START')
+                    await scenario(client,'STOP','STOPPED','ACCEPTED_STOP')
+                    # Verify readback tags cannot be remotely overwritten.
+                    try:
+                        await client.get_node(ua.NodeId('VPLC/'+contract['asset_id']+'/RunFeedback',ns_client)).write_value(True)
+                        raise CommandHold('PROTECTED_FEEDBACK_UNEXPECTEDLY_WRITABLE')
+                    except ua.UaStatusCodeError:
+                        tests.append({'command':'UNAUTHORIZED_FEEDBACK_WRITE','status':'PASS_LAB_ONLY',
+                                      'expected_result':'ACCESS_DENIED'})
+            finally:
+                stop.set()
+                task.cancel()
+                try:await task
+                except asyncio.CancelledError:pass
+    except CommandHold:raise
+    except Exception as exc:raise CommandHold('LAB_RUNTIME_'+type(exc).__name__.upper()) from exc
+    ok=len(tests)==10 and all(x['status']=='PASS_LAB_ONLY' for x in tests)
+    return {'schema':REPORT_SCHEMA,'status':'PASS_ISOLATED_VIRTUAL_PLC_COMMAND_FAT_ONLY' if ok else 'FAIL',
+            'asset_id':contract['asset_id'],'model_sha256':contract['model_sha256'],
+            'contract_sha256':hashlib.sha256(json.dumps(contract,sort_keys=True).encode()).hexdigest(),
+            'cases':tests,'case_count':len(tests),'endpoint_scope':'127.0.0.1_ONLY',
+            'fake_opcua':'EXECUTED_WITH_INDEPENDENT_TCP_CLIENT','ignition_gateway':'NOT_TESTED',
+            'physical_plc':'NOT_VERIFIED','production_release':'HOLD',
+            'recorded_utc':dt.datetime.now(dt.timezone.utc).isoformat()}
+
+async def serve_virtual_plc(model, contract:dict, *, port=4899, seconds=300, confirm=None):
+    """Temporary live Virtual PLC for *manual* Ignition test on the SAME HOST.
+
+    Unlike the automatic FAT runner, this stays online for a bounded time so
+    Ignition Perspective can issue lab CommandRequest writes through approved
+    OPC tags. No production or Docker/public binding is attempted.
+    """
+    if confirm!=LAB_CONFIRM:raise CommandHold('LAB_CONFIRM_REQUIRED')
+    validate_contract(model,contract,require_lab_approval=True)
+    if type(port) is not int or not 1024<=port<=65535:raise CommandHold('PORT_INVALID')
+    if type(seconds) is not int or not 10<=seconds<=900:raise CommandHold('LAB_DURATION_LIMIT_10_TO_900_SECONDS')
+    try:
+        from asyncua import Server,ua
+    except ImportError as exc:raise CommandHold('ASYNCUA_NOT_INSTALLED_REAL_OPC_TEST_NOT_RUN') from exc
+    server=Server();await server.init()
+    uri=contract['simulated_namespace_uri']
+    endpoint=f'opc.tcp://127.0.0.1:{port}/devagent-virtual-plc/'
+    server.set_endpoint(endpoint)
+    server.set_server_name('DevAgent V078 LAB ONLY OPC UA -- NEVER PRODUCTION')
+    server.set_security_policy([ua.SecurityPolicyType.NoSecurity])
+    ns=await server.register_namespace(uri)
+    obj=await server.nodes.objects.add_object(ns,'VirtualPLC_'+contract['asset_id'])
+    fields={'CommandRequest':('',ua.VariantType.String), 'AckId':('',ua.VariantType.String),
+        'CommandResult':('IDLE',ua.VariantType.String), 'State':('STOPPED',ua.VariantType.String),
+        'RunFeedback':(False,ua.VariantType.Boolean), 'Fault':(False,ua.VariantType.Boolean),
+        'Permissive':(True,ua.VariantType.Boolean)}
+    nodes={}
+    for name,(initial,kind) in fields.items():
+        nodes[name]=await obj.add_variable(ua.NodeId('VPLC/'+contract['asset_id']+'/'+name,ns),name,
+                                           ua.Variant(initial,kind))
+    await nodes['CommandRequest'].set_writable()
+    processed=set();state='STOPPED';fault=False
+    start=asyncio.get_running_loop().time()
+    try:
+        async with server:
+            while asyncio.get_running_loop().time()-start<seconds:
+                raw=await nodes['CommandRequest'].read_value()
+                if raw and raw not in processed:
+                    processed.add(raw)
+                    try:
+                        request_id,action=raw.split('|',1)
+                        if not re.fullmatch('[0-9a-f]{32}',request_id):raise ValueError
+                    except ValueError:
+                        request_id='INVALID';action='INVALID'
+                    permissible=await nodes['Permissive'].read_value()
+                    state,outcome=transition(state,action,permissible,fault)
+                    if outcome=='ACCEPTED_RESET':fault=False
+                    await nodes['State'].write_value(state)
+                    await nodes['Fault'].write_value(fault)
+                    await nodes['RunFeedback'].write_value(state=='RUNNING')
+                    await nodes['CommandResult'].write_value(outcome)
+                    await nodes['AckId'].write_value(request_id)
+                await asyncio.sleep(.025)
+    except Exception as exc:raise CommandHold('LAB_SERVER_'+type(exc).__name__.upper()) from exc
+    return {'status':'LAB_SERVER_STOPPED_AFTER_BOUNDED_WINDOW','endpoint_scope':'LOOPBACK_ONLY',
+            'physical_plc':'NOT_VERIFIED','ignition_runtime':'NOT_VERIFIED','production':'HOLD'}

devagent_spatial/v078_native_commands.py

@@ -0,0 +1,161 @@
+"""Native Perspective lab command panel candidate; no Gateway I/O or production authority.
+
+Extends V07 isolated read-only project export with reviewed, LAB-only command actions.
+Only project-owned, disabled-by-default candidate ZIPs are generated. All operator
+writes are to fixed DevAgentLabCommands provider; role, tag quality and simulated
+permissives are checked at click time. Gateway FAT is mandatory before using.
+"""
+from __future__ import annotations
+import hashlib
+import json
+import os
+import tempfile
+import zipfile
+from pathlib import Path
+from .v078_commands import validate_contract, CommandHold, LAB_PROVIDER
+from .v07_native import expected_members as v07_expected, _walk
+from .ignition_project import _zip_blob
+from .ignition_native import sha, NativeHold
+
+
+def _lab_script(c, action):
+    tags=c['tag_paths']
+    # The script contains ONLY fixed lab tag paths from the validated contract.
+    # Role must be configured via Ignition IdP; tag write permissions separately.
+    # This script is a *Gateway-test candidate*, not a production control strategy.
+    lines=[
+        'import uuid',
+        'logger = system.util.getLogger("DevAgent.LAB.DeviceCommands")',
+        'if not system.perspective.isAuthorized(False, ["Authenticated/Roles/DevAgentLabOperator"]):',
+        '    logger.warn("DENIED: lab operator security level required")',
+        'else:',
+        '    paths = '+repr([tags['state'],tags['fault'],tags['permissive']]),
+        '    checks = system.tag.readBlocking(paths, 2000)',
+        '    if not all(x.quality.isGood() for x in checks):',
+        '        logger.warn("DENIED: lab feedback quality unavailable")',
+        '    else:',
+        '        state, fault, permissive = [x.value for x in checks]',
+    ]
+    pred={'START':'state == "STOPPED" and not fault and permissive',
+          'STOP':'state in ("STOPPED", "RUNNING", "FAULT")',
+          'RESET':'state == "FAULT" and fault'}[action]
+    lines += [
+        '        if not ('+pred+'):',
+        '            logger.warn("DENIED: lab command precondition")',
+        '        else:',
+        '            request = str(uuid.uuid4()).replace("-", "") + "|'+action+'"',
+        '            # LAB PROVIDER ONLY; never substitute a customer tag path.',
+        '            result = system.tag.writeBlocking(['+repr(tags['request'])+'], [request], 2000)',
+        '            if not result or not result[0].isGood():',
+        '                logger.error("LAB request write failed; check OPC quality/permissions")',
+        '            else:',
+        '                logger.info("LAB command request submitted; verify AckId and State before FAT PASS")',
+    ]
+    return '\n'.join('\t'+line for line in lines)+'\n'
+
+
+def _button(c, action):
+    return {'type':'ia.input.button','meta':{'name':'Lab_'+action},
+        'props':{'text':action+'  ·  LAB ONLY','enabled':True,
+                 'style':{'backgroundColor':'#174c67','color':'#f4faff','padding':10}},
+        'position':{'basis':'auto','grow':0,'shrink':0},
+        'events':{'component':{'onActionPerformed':{'type':'script','scope':'G',
+                    'config':{'script':_lab_script(c,action)}}}}}
+
+
+def _label_binding(name, tag_path):
+    return {'type':'ia.display.label','meta':{'name':'Lab_'+name},
+        'props':{'text':'UNKNOWN','style':{'color':'#f3cb7d','fontSize':13}},
+        'position':{'basis':'auto','grow':0,'shrink':0},
+        'propConfig':{'props.text':{'binding':{'type':'tag',
+                         'config':{'mode':'direct','tagPath':tag_path}}}}}
+
+
+def expected_lab_members(model, binding_manifest, c, reference, template_view, reference_sha, name):
+    validate_contract(model,c,require_lab_approval=True)
+    members,meta=v07_expected(model,binding_manifest,Path(reference),template_view,
+                              reference_sha,name,project_enabled=False)
+    view_paths=[n for n in members if n.endswith('/view.json')]
+    if len(view_paths)!=1:raise CommandHold('NATIVE_VIEW_COUNT_INVALID')
+    vp=view_paths[0]
+    view=json.loads(members[vp].decode())
+    root=view['root']
+    panel={'type':'ia.container.flex','meta':{'name':'DevAgentV078LabCommandPanel'},
+        'props':{'direction':'column','style':{'padding':18,'backgroundColor':'#102b40',
+                 'border':'2px solid #d8a75a','borderRadius':8,'gap':8}},
+        'position':{'basis':'auto','grow':0,'shrink':0},
+        'children':[
+            {'type':'ia.display.label','meta':{'name':'CommandNotice'},
+             'props':{'text':'VIRTUAL PLC LAB ONLY · NEVER USE WITH PHYSICAL PLC',
+                      'style':{'color':'#ffcc72','fontWeight':'bold'}},
+             'position':{'basis':'auto','grow':0,'shrink':0}},
+            {'type':'ia.display.label','meta':{'name':'CommandAsset'},
+             'props':{'text':'Equipment: '+c['asset_id']+'  |  simulator authority only'},
+             'position':{'basis':'auto','grow':0,'shrink':0}},
+            *[_label_binding(k, c['tag_paths'][k]) for k in ('state','run_feedback','fault','permissive','ack_id','result')],
+            {'type':'ia.container.flex','meta':{'name':'LabCommandActions'},
+             'props':{'direction':'row','wrap':'wrap','style':{'gap':12}},
+             'position':{'basis':'auto','grow':0,'shrink':0},
+             'children':[_button(c,action) for action in c['actions']]},
+        ]}
+    root['children'].append(panel)
+    if sum(1 for _ in _walk(root))>1600:raise CommandHold('NATIVE_COMPONENT_LIMIT')
+    members[vp]=(json.dumps(view,sort_keys=True,indent=2)+'\n').encode()
+    _audit_native_members(members,c)
+    return members, {'base':meta,'view_path':vp}
+
+
+def _audit_native_members(members,c):
+    if len(members)!=5:raise CommandHold('NATIVE_MEMBER_COUNT_INVALID')
+    if not any(n.endswith('page-config/config.json') for n in members):
+        raise CommandHold('PAGE_ROUTING_MISSING')
+    project=[json.loads(v) for k,v in members.items() if k.endswith('project.json')]
+    if len(project)!=1 or project[0].get('enabled') is not False:
+        raise CommandHold('NATIVE_PROJECT_MUST_BE_DISABLED')
+    views=[json.loads(v) for k,v in members.items() if k.endswith('/view.json')]
+    if len(views)!=1:raise CommandHold('INVALID_NATIVE_VIEW')
+    panels=[x for x in _walk(views[0]['root']) if x.get('meta',{}).get('name')=='DevAgentV078LabCommandPanel']
+    if len(panels)!=1:raise CommandHold('LAB_PANEL_MISSING')
+    buttons=[x for x in _walk(views[0]['root']) if x.get('meta',{}).get('name','').startswith('Lab_') and x.get('type')=='ia.input.button']
+    if len(buttons)!=3:raise CommandHold('LAB_BUTTON_COUNT_INVALID')
+    expected=[_lab_script(c,action) for action in c['actions']]
+    actual=[x['events']['component']['onActionPerformed']['config']['script'] for x in buttons]
+    if actual!=expected:raise CommandHold('LAB_SCRIPT_TAMPER_DETECTED')
+    for value in members.values():
+        if b'[default]' in value or b'prod:' in value.lower():raise CommandHold('PRODUCTION_PROVIDER_REFERENCE_DETECTED')
+    return True
+
+
+def compile_lab_native(model,bindings,c,reference,template_view,reference_sha,name,out,confirm):
+    if confirm!='ISOLATED_IGNITION_LAB_CANDIDATE_ONLY':raise CommandHold('CONFIRM_REQUIRED')
+    target=Path(out).expanduser().absolute()
+    if target.suffix.lower()!='.zip' or not target.parent.is_dir() or target.exists():
+        raise CommandHold('CREATE_ONLY_ZIP_REQUIRED')
+    prior=sha(Path(reference))
+    members,meta=expected_lab_members(model,bindings,c,reference,template_view,reference_sha,name)
+    if sha(Path(reference))!=prior:raise CommandHold('REFERENCE_CHANGED')
+    payload=_zip_blob(members)
+    fd,tmp=tempfile.mkstemp(prefix='.v078-native-',suffix='.zip',dir=target.parent)
+    try:
+        with os.fdopen(fd,'wb') as f:
+            f.write(payload);f.flush();os.fsync(f.fileno())
+        if Path(tmp).read_bytes()!=payload:raise CommandHold('STAGED_BYTES_INVALID')
+        try:os.link(tmp,target)
+        except FileExistsError:raise CommandHold('TARGET_ALREADY_EXISTS') from None
+        os.chmod(target,0o600)
+    finally:Path(tmp).unlink(missing_ok=True)
+    return {'status':'PASS_OFFLINE_NATIVE_LAB_COMMAND_CANDIDATE_ONLY',
+            'path':str(target),'sha256':sha(target),'asset_id':c['asset_id'],
+            'number_of_lab_commands':3,'project_default_enabled':False,
+            'native_events':'GENERATED_NOT_GATEWAY_TESTED',
+            'virtual_plc_opc':'SEPARATE_LAB_FAT_REQUIRED','live_ignition':'NOT_VERIFIED',
+            'physical_plc':'NOT_VERIFIED','production_release':'HOLD'}
+
+
+def verify_lab_native(model,bindings,c,reference,template_view,reference_sha,name,candidate):
+    target=Path(candidate)
+    if not target.is_file() or target.is_symlink():raise CommandHold('CANDIDATE_UNSAFE')
+    members,_=expected_lab_members(model,bindings,c,reference,template_view,reference_sha,name)
+    if target.read_bytes()!=_zip_blob(members):raise CommandHold('NATIVE_CANDIDATE_NOT_REPRODUCIBLE')
+    return {'status':'PASS_OFFLINE_NATIVE_COMMAND_VERIFICATION_ONLY','sha256':sha(target),
+            'native_ignition_runtime':'NOT_TESTED','production_release':'HOLD'}

devagent_spatial/v07_fat.py

@@ -0,0 +1,110 @@
+"""V0.7 independent consistency assessment for supplied LAB observations.
+
+The data is UNATTESTED: this module cannot observe a Gateway or Perspective UI.
+It must never return Ignition FAT PASS, physical mapping PASS, or production approval.
+"""
+from __future__ import annotations
+import hashlib
+import json
+import math
+import re
+from pathlib import Path
+from .v07_native import model_sha, canonical, validate_manifest
+from .ignition_native import NativeHold
+
+SCHEMA='devagent.fat.v07.supplied_observations.v1'
+EXPECTED=('GOOD','BAD','STALE')
+PHASES={'GOOD':'GOOD','BAD':'BAD','STALE':'STALE'}
+
+
+def _same_value(v1,v2,datatype):
+    if datatype=='Boolean':
+        if type(v1) is not bool:return False
+        return (type(v2) is bool and v1==v2) or (isinstance(v2,str) and v2.lower()==str(v1).lower())
+    if datatype=='Int32':
+        return type(v1) is int and -2147483648<=v1<=2147483647 and (
+            (type(v2) is int and v1==v2) or (isinstance(v2,str) and v2==str(v1)))
+    if datatype=='Double':
+        if type(v1) not in (int,float) or not math.isfinite(v1):return False
+        try:return (type(v2) in (int,float,str) and math.isfinite(float(v2))
+                    and abs(float(v1)-float(v2))<=max(1e-6,abs(v1)*1e-7))
+        except (ValueError,TypeError,OverflowError):return False
+    if datatype=='String':return isinstance(v1,str) and v1==v2
+    return False
+
+
+def assess(model:dict,manifest:dict,observations:dict,candidate:Path) -> dict:
+    approved=validate_manifest(model,manifest)
+    if not isinstance(observations,dict) or set(observations)!={'schema','model_sha256','candidate_sha256','source','signals'}:
+        raise NativeHold('FAT_OBSERVATIONS_SCHEMA_INVALID')
+    if observations['schema']!=SCHEMA or observations['model_sha256']!=model_sha(model):
+        raise NativeHold('FAT_MODEL_IDENTITY_MISMATCH')
+    if (not isinstance(observations['candidate_sha256'],str)
+            or not re.fullmatch('[a-f0-9]{64}',observations['candidate_sha256'])):
+        raise NativeHold('FAT_CANDIDATE_SHA256_REQUIRED')
+    candidate=Path(candidate)
+    if (not candidate.is_file() or candidate.is_symlink()
+            or candidate.stat().st_size>4_000_000
+            or hashlib.sha256(candidate.read_bytes()).hexdigest()!=observations['candidate_sha256']):
+        raise NativeHold('FAT_CANDIDATE_IDENTITY_MISMATCH')
+    if observations['source']!='EXTERNALLY_SUPPLIED_UNATTESTED_LAB_OBSERVATIONS':
+        raise NativeHold('FAT_SOURCE_CLAIM_NOT_ALLOWED')
+    samples=observations['signals']
+    if not isinstance(samples,list) or len(samples)>len(model['signals']):
+        raise NativeHold('FAT_SAMPLE_COLLECTION_INVALID')
+    declared={s['id']:s for s in model['signals']}
+    found=set();cases=[]
+    for item in samples:
+        if not isinstance(item,dict) or set(item)!={'signal_id','phases'}:
+            raise NativeHold('FAT_SIGNAL_OBSERVATION_INVALID')
+        sid=item['signal_id']
+        if not isinstance(sid,str) or sid not in declared or sid in found:
+            raise NativeHold('FAT_SIGNAL_ID_UNKNOWN_OR_DUPLICATE')
+        found.add(sid)
+        if sid not in approved:raise NativeHold('FAT_UNAPPROVED_BINDING_OBSERVATION')
+        readings=item['phases']
+        if not isinstance(readings,list) or len(readings)!=3:
+            cases.append({'signal_id':sid,'result':'HOLD_PHASE_COVERAGE','issues':['PHASES_REQUIRED_GOOD_BAD_STALE']})
+            continue
+        by_phase={};issues=[]
+        for phase in readings:
+            if not isinstance(phase,dict) or set(phase)!={'phase','opc','ignition','hmi'}:
+                issues.append('PHASE_FORMAT_INVALID');continue
+            key=phase['phase']
+            if key not in EXPECTED or key in by_phase:
+                issues.append('PHASE_DUPLICATE_OR_UNKNOWN');continue
+            by_phase[key]=phase
+        if set(by_phase)!=set(EXPECTED):issues.append('PHASE_COVERAGE_MISMATCH')
+        for phase_name,record in by_phase.items():
+            for source in ('opc','ignition','hmi'):
+                entry=record[source]
+                if not isinstance(entry,dict) or 'quality' not in entry or entry['quality'] not in EXPECTED:
+                    issues.append(phase_name+'_'+source+'_QUALITY_INVALID')
+                elif entry['quality']!=phase_name:
+                    issues.append(phase_name+'_'+source+'_QUALITY_MISMATCH')
+            if any(not isinstance(record[s],dict) for s in ('opc','ignition','hmi')):continue
+            if phase_name=='GOOD':
+                if 'value' not in record['opc'] or 'value' not in record['ignition'] or 'display_value' not in record['hmi']:
+                    issues.append('GOOD_READBACK_DATA_MISSING')
+                else:
+                    dt=declared[sid]['datatype'];v=record['opc']['value']
+                    if not _same_value(v,record['ignition']['value'],dt):issues.append('OPC_IGNITION_VALUE_MISMATCH')
+                    if not _same_value(v,record['hmi']['display_value'],dt):issues.append('IGNITION_HMI_VALUE_MISMATCH')
+            else:
+                if record['hmi'].get('quality_indicator_visible') is not True:
+                    issues.append(phase_name+'_HMI_QUALITY_INDICATION_MISSING')
+        cases.append({'signal_id':sid,'result':'PASS_SUPPLIED_DATA_CONSISTENCY_ONLY' if not issues else 'HOLD',
+                      'issues':sorted(set(issues))})
+    for sid in declared:
+        if sid not in found:cases.append({'signal_id':sid,'result':'HOLD_NO_OBSERVATIONS',
+                                           'issues':['NO_SUPPLIED_OBSERVATIONS']})
+    cases.sort(key=lambda c:c['signal_id'])
+    complete=all(c['result']=='PASS_SUPPLIED_DATA_CONSISTENCY_ONLY' for c in cases)
+    return {'schema':'devagent.fat.v07.consistency_review.v1',
+            'status':'PASS_SUPPLIED_DATA_CONSISTENCY_ONLY' if complete else 'HOLD',
+            'model_sha256':model_sha(model), 'candidate_sha256':observations['candidate_sha256'],
+            'observations_sha256':hashlib.sha256(canonical(observations)).hexdigest(),
+            'cases':cases,'total_signals':len(declared),'cases_consistent':sum(c['result']=='PASS_SUPPLIED_DATA_CONSISTENCY_ONLY' for c in cases),
+            'source_trust':'UNATTESTED', 'requirements_fat':'NOT_EXECUTED', 'real_ignition_fat':'NOT_VERIFIED',
+            'physical_mapping':'NOT_VERIFIED','production_release':'HOLD',
+            'remarks':'Supplied capture data is not proof of Gateway execution. Obtain independently attested readbacks and live UI evidence.'}