devagent-ignition 0.1.0__py3-none-any.whl

devagent_spatial/studio_workflow.py

@@ -0,0 +1,277 @@
+"""Project-scoped engineering workspace for an EXISTING isolated Studio R2.
+
+Never mutates generated HMI/renderer or starts processes. Studio communication is
+fixed to loopback; writes are allowed only to customer nodes in a lab that was
+empty when this Creator session imported the exact project's mappings.
+No physical PLC / Ignition / Perspective / production qualification is claimed.
+"""
+from __future__ import annotations
+import asyncio
+import csv
+import io
+import copy
+import hashlib
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from .operations import evaluate, mapping_digest
+from .operations_capture import capture_lab
+from .operations_lab import LAB_NAMESPACE, TYPES, create_lab_derivative
+from .qualification import audit
+
+class LabHold(ValueError): pass
+
+
+def load_project(workspace:Path, project_id:str):
+    from .operations import policy
+    if not project_id or len(project_id)>100 or not __import__('re').fullmatch(r'[a-z0-9-]+',project_id):
+        raise LabHold('INVALID_PROJECT_ID')
+    root=(workspace/project_id).resolve()
+    if root.parent!=workspace.resolve():raise LabHold('INVALID_PROJECT_PATH')
+    result=audit(root)
+    if result['status']!='PASS_CONCEPT_PREVIEW_ONLY':raise LabHold('PROJECT_ARTIFACT_INTEGRITY_HOLD')
+    model=json.loads((root/'contracts'/'project.json').read_text())
+    policy(model)
+    return model
+
+
+def studio_request(port:int,method:str,path:str,body:bytes|None=None):
+    """No arbitrary URL, proxy, or user-provided Host. Fixed loopback only."""
+    if type(port) is not int or not 1024<=port<=65535:raise LabHold('STUDIO_PORT_INVALID')
+    if path not in ('/api/state','/api/manifest','/api/probe','/api/upload-tags','/api/command'):
+        raise LabHold('STUDIO_ROUTE_NOT_ALLOWED')
+    if method not in ('GET','POST'):raise LabHold('STUDIO_METHOD_NOT_ALLOWED')
+    req=urllib.request.Request(f'http://127.0.0.1:{port}{path}',data=body,method=method,
+        headers={'Content-Type':'application/json' if path in ('/api/probe','/api/command') else 'text/csv; charset=utf-8'})
+    try:
+        with urllib.request.urlopen(req,timeout=12 if path!='/api/probe' else 160) as response:
+            if response.status!=200:raise LabHold('STUDIO_HTTP_NOT_OK')
+            if int(response.headers.get('Content-Length','0'))>2_000_000:
+                raise LabHold('STUDIO_RESPONSE_TOO_LARGE')
+            raw=response.read(2_000_001)
+            if len(raw)>2_000_000:raise LabHold('STUDIO_RESPONSE_TOO_LARGE')
+            value=json.loads(raw)
+            if not isinstance(value,dict):raise LabHold('STUDIO_RESPONSE_INVALID')
+            return value
+    except (urllib.error.URLError, TimeoutError, OSError, ValueError) as exc:
+        raise LabHold('STUDIO_OFFLINE_OR_REJECTED_'+type(exc).__name__.upper()) from exc
+
+
+def studio_state(port:int):
+    state=studio_request(port,'GET','/api/state')
+    customer=state.get('customer',{})
+    if (state.get('status')!='OPC_UA_SOURCE_RUNNING' or state.get('lab_only') is not True or
+        not isinstance(customer,dict) or customer.get('namespace_uri')!=LAB_NAMESPACE or
+        type(customer.get('tag_count')) is not int or type(customer.get('revision')) is not int or
+        not isinstance(state.get('opc_endpoint'),str)):
+        raise LabHold('NOT_A_SUPPORTED_ISOLATED_STUDIO_R2')
+    return state
+
+
+def project_lab_dir(workspace,project_id):
+    p=(workspace/'.devagent-engineering-tests'/project_id).resolve()
+    if p.parent!=(workspace/'.devagent-engineering-tests').resolve():raise LabHold('INVALID_LAB_OUTPUT_PATH')
+    return p
+
+
+def verify_prepared_model(workspace,project_id,model):
+    """Reject changed lab alias data even when project source is intact."""
+    destination=project_lab_dir(workspace,project_id)
+    required=('customer-original.json','lab-model.json','studio-tags.csv','alias-review.json')
+    try:
+        manifest={}
+        for line in (destination/'SHA256SUMS.txt').read_text().splitlines():
+            digest,filename=line.split('  ',1)
+            if (filename not in required or filename in manifest or len(digest)!=64
+                or any(c not in '0123456789abcdef' for c in digest)):
+                raise LabHold('LAB_MANIFEST_INVALID')
+            manifest[filename]=digest
+        if set(manifest)!=set(required):raise LabHold('LAB_MANIFEST_INCOMPLETE')
+        for filename,digest in manifest.items():
+            if hashlib.sha256((destination/filename).read_bytes()).hexdigest()!=digest:
+                raise LabHold('LAB_ARTIFACT_TAMPER_HOLD')
+        original=json.loads((destination/'customer-original.json').read_text())
+        lab=json.loads((destination/'lab-model.json').read_text())
+        expected=copy.deepcopy(model)
+        for s in expected['signals']:
+            s['source']['namespace_uri']=LAB_NAMESPACE
+        if original!=model or lab!=expected:
+            raise LabHold('LAB_ALIAS_MAPPING_DRIFT')
+        parsed=list(csv.DictReader(io.StringIO((destination/'studio-tags.csv').read_text())))
+        rows=sorted((r['TagPath'],r['DataType']) for r in parsed)
+        if rows!=_expected(lab):raise LabHold('LAB_TAGS_CSV_MODEL_DRIFT')
+        return lab
+    except (OSError,KeyError,TypeError,ValueError,IndexError,json.JSONDecodeError) as exc:
+        if isinstance(exc,LabHold):raise
+        raise LabHold('LAB_ARTIFACTS_INVALID') from exc
+
+
+def prepare(workspace,project_id,model):
+    destination=project_lab_dir(workspace,project_id)
+    destination.parent.mkdir(parents=True,exist_ok=True)
+    if destination.exists():
+        verify_prepared_model(workspace,project_id,model)
+        return {'status':'LAB_PREPARED_CREATE_ONLY','signal_count':len(model['signals']),'already_prepared':True}
+    result=create_lab_derivative(model,destination,'ISOLATED_TEST_ONLY')
+    verify_prepared_model(workspace,project_id,model)
+    return {'status':'LAB_PREPARED_CREATE_ONLY','signal_count':result['signals'],'already_prepared':False}
+
+
+def _expected(model):
+    return sorted((s['source']['node_id'], TYPES[s['datatype']]) for s in model['signals'])
+
+
+def _manifest_ok(manifest,lab_model):
+    if (manifest.get('status')!='LAB_SIMULATED_NOT_SITE_VERIFIED' or
+            manifest.get('namespaceUri')!=LAB_NAMESPACE or
+            type(manifest.get('tagCount')) is not int or
+            manifest['tagCount']!=len(lab_model['signals'])):
+        return False
+    items=manifest.get('items')
+    if not isinstance(items,list):return False
+    received=sorted((r.get('path'),r.get('dataType')) for r in items if isinstance(r,dict))
+    return received==_expected(lab_model)
+
+
+def _same_session(session,state):
+    return bool(session and session.get('revision')==state['customer']['revision'] and
+            session.get('endpoint')==state['opc_endpoint'] and
+            abs(float(session.get('started',-1))-(time.time()-float(state['uptime_seconds'])))<5)
+
+
+def import_tags(workspace,project_id,port:int,state,session):
+    model=load_project(workspace,project_id)
+    if session:raise LabHold('STUDIO_ALREADY_IMPORTED_THIS_SESSION')
+    if state['customer']['tag_count']!=0:
+        raise LabHold('STUDIO_HAS_EXISTING_TAGS_REQUIRE_FRESH_ISOLATED_LAB')
+    labdir=project_lab_dir(workspace,project_id)
+    if not labdir.is_dir():raise LabHold('PREPARE_LAB_FIRST')
+    lab_model=verify_prepared_model(workspace,project_id,model)
+    raw=(labdir/'studio-tags.csv').read_bytes()
+    result=studio_request(port,'POST','/api/upload-tags',raw)
+    if result.get('status')!='IMPORTED':raise LabHold('STUDIO_IMPORT_NOT_CONFIRMED')
+    updated=studio_state(port)
+    manifest=studio_request(port,'GET','/api/manifest')
+    if not _manifest_ok(manifest,lab_model):raise LabHold('STUDIO_IMPORT_MANIFEST_MISMATCH')
+    session={'revision':updated['customer']['revision'],'endpoint':updated['opc_endpoint'],
+            'started':time.time()-float(updated['uptime_seconds']),'mapping_digest':mapping_digest(model),
+            'lab_mapping_digest':mapping_digest(lab_model)}
+    return {'status':'LAB_TAGS_IMPORTED_NOT_IGNITION_VERIFIED','imported':len(lab_model['signals']),
+            'lab_namespace':LAB_NAMESPACE},session
+
+
+def require_session(workspace,project_id,port,session):
+    model=load_project(workspace,project_id)
+    state=studio_state(port)
+    if not _same_session(session,state) or session['mapping_digest']!=mapping_digest(model):
+        raise LabHold('NO_ACTIVE_PROJECT_BOUND_STUDIO_SESSION')
+    labdir=project_lab_dir(workspace,project_id)
+    lab_model=verify_prepared_model(workspace,project_id,model)
+    if session['lab_mapping_digest']!=mapping_digest(lab_model):raise LabHold('LAB_MODEL_DIGEST_MISMATCH')
+    if not _manifest_ok(studio_request(port,'GET','/api/manifest'),lab_model):
+        raise LabHold('STUDIO_MANIFEST_CHANGED_HOLD')
+    return state,model,lab_model
+
+
+def write_evidence(workspace,project_id,basename,data):
+    if basename not in ('protocol-probe','isolated-fault-scenario'):raise LabHold('INVALID_EVIDENCE_TYPE')
+    path=project_lab_dir(workspace,project_id)/(basename+'-'+__import__('uuid').uuid4().hex[:12]+'.json')
+    with path.open('x',encoding='utf-8') as output:json.dump(data,output,indent=2)
+    return path.name
+
+
+def protocol_probe(workspace,project_id,port,session):
+    state,model,lab=require_session(workspace,project_id,port,session)
+    result=studio_request(port,'POST','/api/probe',b'{"source":"customer"}')
+    if result.get('status')!='PASS' or result.get('verified')!=len(lab['signals']) or result.get('total')!=len(lab['signals']):
+        raise LabHold('OPC_LAB_READBACK_NOT_PASS')
+    evidence={'status':'PASS_STUDIO_LAB_PROTOCOL_ONLY','studio_protocol':result,
+              'customer_mapping_digest':mapping_digest(model), 'lab_mapping_digest':mapping_digest(lab),
+              'mapping_to_physical_plc':'NOT_VERIFIED','hmi_perspective_binding':'NOT_VERIFIED',
+              'production':'HOLD','time_utc':__import__('datetime').datetime.now(__import__('datetime').timezone.utc).isoformat()}
+    name=write_evidence(workspace,project_id,'protocol-probe',evidence)
+    return {'status':evidence['status'],'verified_nodes':result['verified'],'total_nodes':result['total'],
+            'evidence_file':name,'ignition':'NOT_VERIFIED','production':'HOLD'}
+
+
+def _set_customer(port,node,value):
+    result=studio_request(port,'POST','/api/command',json.dumps({'op':'set','source':'customer','path':node,'value':value}).encode())
+    if result.get('status')!='APPLIED':raise LabHold('STUDIO_FAULT_STIMULUS_REJECTED')
+
+
+def run_fault_scenario(workspace,project_id,port,session):
+    state,model,lab=require_session(workspace,project_id,port,session)
+    signal=next((s for s in lab['signals'] if s['role']=='fault' and s['datatype']=='Boolean'),None)
+    if signal is None:raise LabHold('NO_BOOLEAN_FAULT_SIGNAL_FOR_SCENARIO')
+    if signal.get('polarity','')=='active_low':raise LabHold('ACTIVE_LOW_FAULT_SCENARIO_NEEDS_SPECIFIC_ADAPTER')
+    path=signal['source']['node_id']
+    endpoint=state['opc_endpoint']
+    # Only the approved loopback/Docker lab OPC endpoint; never physical equipment.
+    from .opc_snapshot import allow_lab_endpoint
+    allow_lab_endpoint(endpoint)
+    rows=[];cleared=False
+    try:
+        for expected in (False,True,False):
+            _set_customer(port,path,expected)
+            snapshot=asyncio.run(capture_lab(lab,endpoint,samples=1))[0]
+            match=next((o for o in snapshot['observations'] if o['signal_id']==signal['id']),None)
+            if not match or match['quality']!='GOOD' or match['value'] is not expected:
+                raise LabHold('INDEPENDENT_OPC_READBACK_VALUE_MISMATCH')
+            rows.append(snapshot)
+        cleared=True
+    finally:
+        if not cleared:
+            try:_set_customer(port,path,False)
+            except (LabHold,OSError):raise LabHold('LAB_FAULT_RESET_NOT_CONFIRMED')
+    receipt=evaluate(lab,rows,origin='ISOLATED_LAB_OPC_READ_ONLY')
+    events=[x['kind'] for x in receipt['events'] if x.get('signal_id')==signal['id']]
+    if events!=['ASSERTED','CLEARED']:raise LabHold('FAULT_ASSERT_CLEAR_EVENTS_NOT_CONFIRMED')
+    evidence={'status':'PASS_ISOLATED_STUDIO_FAULT_READBACK_ONLY',
+              'test_signal_id':signal['id'],'asset_id':signal['asset_id'],'node_id':path,
+              'test_sequence':['CLEAR','ASSERT','CLEAR'],'independent_opc_readback':True,
+              'alarm_events':events,'receipt':receipt,
+              'ignition_hmi_binding':'NOT_TESTED','physical_plc':'NOT_VERIFIED','production':'HOLD'}
+    name=write_evidence(workspace,project_id,'isolated-fault-scenario',evidence)
+    return {'status':evidence['status'],'asset_id':signal['asset_id'],'node_id':path,
+            'alarm_events':events,'evidence_file':name,'ignition':'NOT_VERIFIED','production':'HOLD'}
+
+
+def readonly_probe_existing_unbound(workspace, project_id, port):
+    """Read only; no import, simulated stimulus, or adoption of unknown Studio tags.
+
+    Enables protocol-only coverage when another Creator session left customer lab
+    nodes behind. Exact manifest is verified before and after probing. The lab
+    remains UNBOUND and cannot run any writes/fault scenario through this path.
+    """
+    model=load_project(workspace,project_id)
+    state=studio_state(port)
+    if state['customer']['tag_count']!=len(model['signals']) or not model['signals']:
+        raise LabHold('EXISTING_STUDIO_TAG_COUNT_MISMATCH')
+    lab=copy.deepcopy(model)
+    for s in lab['signals']:
+        s['source']['namespace_uri']=LAB_NAMESPACE
+    if not _manifest_ok(studio_request(port,'GET','/api/manifest'),lab):
+        raise LabHold('EXISTING_STUDIO_MANIFEST_NOT_PROJECT_MATCHED')
+    result=studio_request(port,'POST','/api/probe',b'{"source":"customer"}')
+    updated=studio_state(port)
+    if (updated['opc_endpoint']!=state['opc_endpoint'] or
+        updated['customer']['revision']!=state['customer']['revision'] or
+        updated['customer']['tag_count']!=state['customer']['tag_count'] or
+        abs((time.time()-updated['uptime_seconds'])-(time.time()-state['uptime_seconds']))>5 or
+        not _manifest_ok(studio_request(port,'GET','/api/manifest'),lab)):
+        raise LabHold('STUDIO_CHANGED_DURING_READONLY_PROBE')
+    if (result.get('status')!='PASS' or result.get('verified')!=len(lab['signals']) or
+        result.get('total')!=len(lab['signals'])):
+        raise LabHold('READONLY_STUDIO_PROBE_NOT_PASS')
+    return {'status':'PASS_UNBOUND_READONLY_LAB_PROTOCOL_ONLY',
+        'verified_nodes':result['verified'],'total_nodes':result['total'],
+        'mapping_digest':mapping_digest(model),
+        'studio_identity':{'revision':updated['customer']['revision'],
+                           'endpoint':updated['opc_endpoint'],
+                           'started':time.time()-float(updated['uptime_seconds'])},
+        'session_authority':'UNBOUND_READONLY_ONLY',
+        'simulated_fault':'NOT_ALLOWED_UNBOUND',
+        'physical_plc':'NOT_VERIFIED','ignition':'NOT_VERIFIED','production':'HOLD'}

devagent_spatial/test_reporting.py

@@ -0,0 +1,87 @@
+"""Read-only, project-bound Studio test coverage for a compact engineering UX.
+
+Only a same-process, same-project, manifest-matched Studio session can retain lab
+results. Aggregate probe results are not mislabeled per-signal physical proofs.
+No HMI, PLC, Studio or project files are modified by report generation.
+"""
+from __future__ import annotations
+from .generator import fat_inventory
+import time
+import copy
+from .operations import mapping_digest
+from .studio_workflow import (load_project,studio_state,require_session,LabHold,LAB_NAMESPACE,_manifest_ok,studio_request)
+
+
+def summarize(workspace, pid, port, session=None, recorded=None):
+    model=load_project(workspace,pid)
+    recorded=recorded or {}
+    active=False
+    reason='Lab results have not been run for this project.'
+    if session and session.get('mapping_digest')==mapping_digest(model):
+        try:
+            require_session(workspace,pid,port,session)
+            active=True
+            reason='Creator project lab session and Studio manifest verified.'
+        except (LabHold,ValueError,OSError,KeyError,TypeError):
+            reason='Lab source changed, is offline or cannot be verified. Previous results are not current.'
+    unbound=False
+    ub=recorded.get('unbound_probe')
+    if not active and isinstance(ub,dict) and ub.get('status')=='PASS_UNBOUND_READONLY_LAB_PROTOCOL_ONLY' and ub.get('mapping_digest')==mapping_digest(model):
+        try:
+            state=studio_state(port)
+            identity=ub.get('studio_identity',{})
+            lab=copy.deepcopy(model)
+            for sig in lab['signals']:sig['source']['namespace_uri']=LAB_NAMESPACE
+            if (state['customer']['revision']==identity['revision'] and
+                state['opc_endpoint']==identity['endpoint'] and
+                abs((time.time()-state['uptime_seconds'])-identity['started'])<5 and
+                state['customer']['tag_count']==len(lab['signals']) and
+                _manifest_ok(studio_request(port,'GET','/api/manifest'),lab)):
+                unbound=True
+                reason='Unbound existing Studio nodes matched for READ-ONLY batch probe. No fault authority.'
+        except (LabHold,ValueError,OSError,KeyError,TypeError):pass
+    probe=recorded.get('probe') if active else None
+    fault=recorded.get('fault') if active else None
+    probe_pass=isinstance(probe,dict) and probe.get('status')=='PASS_STUDIO_LAB_PROTOCOL_ONLY' and probe.get('verified_nodes')==len(model['signals']) and probe.get('total_nodes')==len(model['signals'])
+    fault_pass=isinstance(fault,dict) and fault.get('status')=='PASS_ISOLATED_STUDIO_FAULT_READBACK_ONLY' and fault.get('alarm_events')==['ASSERTED','CLEARED']
+    if fault_pass and not probe_pass:
+        fault_pass=False  # Cannot claim standalone full coverage when source gate is unproven.
+    signals=[]
+    for s in model['signals']:
+        signals.append({'id':s['id'],'asset_id':s['asset_id'],'role':s['role'],
+           'datatype':s['datatype'],'node_id':s['source']['node_id'],
+           'namespace_uri':s['source']['namespace_uri'],
+           'protocol':'INCLUDED_IN_BATCH' if probe_pass else 'UNBOUND_READONLY_BATCH' if unbound else 'PENDING',
+           'individual_evidence':'NOT_AVAILABLE', 'physical_source':'NOT_VERIFIED'})
+    cases=[];lab_fault_count=0
+    for row in fat_inventory(model):
+        c=dict(row)
+        if fault_pass and c.get('asset_id')==fault.get('asset_id') and c.get('signal_id') and c['id'].endswith('_FAULT') and any(sig['id']==c['signal_id'] and sig['source']['node_id']==fault.get('node_id') for sig in model['signals']):
+            c['lab']='LAB_FAULT_PASS'
+            lab_fault_count+=1
+        elif probe_pass and c.get('signal_id'):
+            c['lab']='PROTOCOL_BATCH_ONLY'
+        else:c['lab']='NOT_RUN'
+        c['hmi']='NOT_VERIFIED'
+        c['result']='HOLD_NOT_FULL_FAT'
+        cases.append(c)
+    return {'schema':'devagent.studio.test-coverage.v1','project_id':pid,'project_name':model['name'],
+      'source':'ISOLATED_STUDIO_LAB_ONLY', 'mapping_digest':mapping_digest(model),
+      'session_verified':active,'unbound_readonly':unbound,'message':reason,
+      'totals':{'assets':len(model['equipment']),'signals':len(signals),
+                'fat_cases':len(cases),'protocol_batch_checked':len(signals) if (probe_pass or unbound) else 0,
+                'individual_signal_receipts':0,'lab_behavior_cases_pass':lab_fault_count,
+                'hmi_cases_pass':0,'fully_qualified_cases':0},
+      'gates':{'G1_customer_mapping':'NOT_PHYSICALLY_VERIFIED',
+               'G2_lab_opc_readback':'PASS_LAB_ONLY' if probe_pass else 'READONLY_UNBOUND_LAB_ONLY' if unbound else 'PENDING',
+               'G3_lab_fault':'PASS_LAB_ONLY' if fault_pass else 'PENDING',
+               'G4_ignition_hmi':'NOT_IMPLEMENTED_NOT_VERIFIED',
+               'G5_production':'HOLD'},
+      'signals':signals,'test_cases':cases,
+      'evidence':{'protocol':probe.get('evidence_file') if probe_pass else None,
+                  'fault':fault.get('evidence_file') if fault_pass else None},
+      'demo':recorded.get('sample',{'status':'NOT_RUN'}),
+      'limitations':['Studio probe returns batch totals, not individual per-signal receipts.',
+            'One declared simulated Boolean fault transition is exercised when available.',
+            'Other FAT cases, actual Perspective behavior and physical PLC mapping remain HOLD.'],
+      'production':'HOLD'}

devagent_spatial/v076_opc_fat.py

@@ -0,0 +1,180 @@
+"""V0.7.6 isolated fake OPC UA protocol FAT (never physical PLC or Ignition FAT).
+
+The simulated namespace deliberately differs from every customer-supplied namespace.
+No client-writable nodes or machine commands are exposed.  The independent
+observer uses a fresh OPC UA TCP client, not the server's in-memory values.
+
+Only an actual asyncua server/client connection may return PASS_LAB_OPC_ONLY.
+A manifest or deterministic test-plan alone ALWAYS remains NOT_EXECUTED.
+"""
+from __future__ import annotations
+import asyncio
+import datetime as dt
+import hashlib
+import json
+import re
+from pathlib import Path
+from .model import qualify
+
+MAX_LAB_SIGNALS=200
+MAX_LAB_STEPS=3
+LAB_URI_PREFIX='urn:devagent:isolated:fake-opcua:v076:'
+TYPES={'Boolean':'Boolean','Double':'Double','Int32':'Int32','String':'String'}
+
+class LabHold(ValueError):pass
+
+def model_hash(model):
+    return hashlib.sha256(json.dumps(model,sort_keys=True,ensure_ascii=False,separators=(',',':')).encode()).hexdigest()
+
+def lab_manifest(model):
+    """Generate a separate synthetic mapping, never overwrite customer OPC identities."""
+    if qualify(model)['status']=='HOLD':raise LabHold('ENGINEERING_MODEL_HOLD')
+    signals=model['signals']
+    if not signals:raise LabHold('LAB_HAS_NO_DECLARED_SIGNALS')
+    if len(signals)>MAX_LAB_SIGNALS:raise LabHold('LAB_LIMIT_200_SIGNALS')
+    digest=model_hash(model)
+    uri=LAB_URI_PREFIX+digest[:16]
+    rows=[]
+    for signal in signals:
+        if signal['datatype'] not in TYPES:raise LabHold('LAB_UNSUPPORTED_DATATYPE')
+        if signal.get('write_authorized') is True:raise LabHold('WRITABLE_CUSTOMER_SIGNALS_PROHIBITED')
+        rows.append({'signal_id':signal['id'],'equipment_id':signal['asset_id'],
+                     'role':signal['role'],'datatype':signal['datatype'],
+                     'lab_namespace_uri':uri,'lab_node_id':'LAB/'+signal['id'],
+                     'ignition_lab_tag_path':None,
+                     'production_namespace_uri':None,'production_node_id':None,
+                     'binding_review':'PENDING_ENGINEER_REVIEW',
+                     'source':'GENERATED_SYNTHETIC_LAB_NOT_CUSTOMER_MAPPING'})
+    return {'schema':'devagent.opc.synthetic_manifest.v076','status':'PLAN_ONLY_NOT_EXECUTED',
+            'model_sha256':digest,'lab_namespace_uri':uri,'signals':rows,
+            'physical_mapping':'NOT_VERIFIED','ignition_binding':'NOT_CONFIGURED',
+            'production_release':'HOLD','write_authority':'DISABLED'}
+
+def scenario_value(signal,step):
+    """Type-preserving fixture, explicitly NOT derived from machinery speeds or states."""
+    datatype=signal['datatype'];role=signal['role']
+    if datatype=='Boolean':return step==1
+    if datatype=='Int32':return 1 if step==1 else 0
+    if datatype=='String':return 'LAB_EXERCISE' if step==1 else 'LAB_IDLE'
+    if datatype=='Double':
+        if step!=1:return 0.0
+        return {'vfd_frequency':25.0,'tank_level':50.0,'pressure':1.0,
+                'flow':1.0,'motor_speed':0.5}.get(role,1.0)
+    raise LabHold('LAB_UNSUPPORTED_DATATYPE')
+
+def plan(model):
+    manifest=lab_manifest(model)
+    return {'schema':'devagent.fat.plan.v076','status':'NOT_EXECUTED',
+            'model_sha256':manifest['model_sha256'],'lab_manifest':manifest,
+            'steps':['BASELINE','EXERCISE','RESTORE'],
+            'cases_planned':len(manifest['signals'])*MAX_LAB_STEPS,
+            'opc_protocol':'NOT_RUN','ignition_gateway':'NOT_VERIFIED',
+            'perspective_hmi':'NOT_VERIFIED','customer_plc':'NOT_VERIFIED',
+            'production_release':'HOLD'}
+
+def _verified_phase(manifest,step,readbacks):
+    """Independent evaluator used with values obtained from OPC TCP client."""
+    failures=[];cases=[]
+    for row in manifest['signals']:
+        sid=row['signal_id'];rec=readbacks.get(sid)
+        expected=scenario_value(row,step)
+        dtype=row['datatype']
+        ok=(isinstance(rec,dict) and rec.get('namespace_uri')==row['lab_namespace_uri']
+            and rec.get('node_id')==row['lab_node_id']
+            and rec.get('datatype')==dtype and rec.get('good') is True
+            and type(rec.get('value')) == {'Boolean':bool,'Int32':int,'Double':float,'String':str}[dtype]
+            and rec['value']==expected)
+        if not ok:failures.append(sid)
+        cases.append({'signal_id':sid,'phase':('BASELINE','EXERCISE','RESTORE')[step],
+                      'result':'PASS_SYNTHETIC_OPC_READBACK_ONLY' if ok else 'FAIL',
+                      'expected_datatype':dtype,'quality_good':bool(rec.get('good')) if isinstance(rec,dict) else False,
+                      'actual_value_recorded':False})
+    return cases,failures
+
+async def run_loopback_fat(model,port:int=4898):
+    """Create OPC UA server on loopback, stimulate synthetic signals, read with a client.
+
+    All nodes are read-only to clients; writes only occur from this server process.
+    Does not import to Ignition or touch any customer PLC.  Returns fail-closed.
+    """
+    if type(port) is not int or not 1024<=port<=65535:raise LabHold('LAB_PORT_INVALID')
+    manifest=lab_manifest(model)
+    try:
+        from asyncua import Client, Server, ua
+    except ImportError as exc:raise LabHold('ASYNCUA_NOT_INSTALLED') from exc
+    server=Server()
+    await server.init()
+    endpoint=f'opc.tcp://127.0.0.1:{port}/devagent-v076-lab/'
+    server.set_endpoint(endpoint)
+    server.set_server_name('DevAgent V076 ISOLATED SYNTHETIC LAB ONLY')
+    # Anonymous no-security endpoint is only allowed on 127.0.0.1.
+    # This is a diagnostic lab server, NEVER expose to external interfaces.
+    from asyncua import ua
+    server.set_security_policy([ua.SecurityPolicyType.NoSecurity])
+    ns=await server.register_namespace(manifest['lab_namespace_uri'])
+    root=await server.nodes.objects.add_object(ns,'DevAgentSyntheticLab')
+    nodes={}
+    for row in manifest['signals']:
+        variant_type=getattr(ua.VariantType,row['datatype'])
+        nid=ua.NodeId(row['lab_node_id'],ns)
+        nodes[row['signal_id']]=await root.add_variable(nid,row['signal_id'],
+                                ua.Variant(scenario_value(row,0),variant_type))
+        # Intentionally DO NOT call set_writable: client writes are prohibited.
+    cases=[];issues=[]
+    try:
+        async with server:
+            # Independent TCP connection and OPC UA Session; not in-memory validation.
+            client=Client(endpoint,timeout=4)
+            async with client:
+                namespaces=await client.get_namespace_array()
+                if manifest['lab_namespace_uri'] not in namespaces:
+                    raise LabHold('LAB_NAMESPACE_NOT_REGISTERED')
+                observed_ns=namespaces.index(manifest['lab_namespace_uri'])
+                for step in range(MAX_LAB_STEPS):
+                    for row in manifest['signals']:
+                        await nodes[row['signal_id']].write_value(
+                          ua.Variant(scenario_value(row,step),getattr(ua.VariantType,row['datatype'])))
+                    reads={}
+                    for row in manifest['signals']:
+                        name=row['signal_id']
+                        remote=client.get_node(ua.NodeId(row['lab_node_id'],observed_ns))
+                        try:
+                            dv=await asyncio.wait_for(remote.read_data_value(raise_on_bad_status=False),timeout=3)
+                            reads[name]={'namespace_uri':manifest['lab_namespace_uri'],
+                                'node_id':row['lab_node_id'],
+                                'datatype':dv.Value.VariantType.name if dv.Value is not None else 'NONE',
+                                'good':dv.StatusCode.is_good(),
+                                'value':dv.Value.Value if dv.Value is not None else None}
+                        except Exception as e:
+                            reads[name]={'error_class':type(e).__name__}
+                    phase,failed=_verified_phase(manifest,step,reads)
+                    cases.extend(phase)
+                    issues.extend(failed)
+    except LabHold:raise
+    except Exception as exc:
+        # Do not leak network/host details or vendor strings in persistent reports.
+        raise LabHold('ISOLATED_OPC_PROTOCOL_'+type(exc).__name__.upper()) from exc
+    passed=not issues and len(cases)==len(manifest['signals'])*3
+    return {'schema':'devagent.fat.lab_run.v076',
+            'status':'PASS_LAB_OPC_PROTOCOL_ONLY' if passed else 'FAIL_LAB_OPC_PROTOCOL',
+            'model_sha256':manifest['model_sha256'],
+            'lab_namespace_uri':manifest['lab_namespace_uri'],
+            'opc_endpoint_scope':'LOOPBACK_ONLY','source':'SYNTHETIC_NOT_CUSTOMER',
+            'cases_planned':len(manifest['signals'])*3,
+            'cases_checked':len(cases),
+            'cases_passed':sum(c['result']=='PASS_SYNTHETIC_OPC_READBACK_ONLY' for c in cases),
+            'issues_signal_ids':sorted(set(issues)),'cases':cases,
+            'independent_client_tcp_session':True,
+            'client_write_authority':'DISABLED',
+            'ignition_gateway':'NOT_VERIFIED','perspective_hmi':'NOT_VERIFIED',
+            'physical_mapping':'NOT_VERIFIED','production_release':'HOLD',
+            'recorded_utc':dt.datetime.now(dt.timezone.utc).isoformat(),
+            'qualification_boundary':'OPC protocol synthetic fixtures only; no machine process, Ignition FAT or PLC proof.'}
+
+def save_new(path:Path,data:dict):
+    path=Path(path)
+    path.parent.mkdir(parents=True,exist_ok=True)
+    with path.open('x',encoding='utf8') as f:
+        json.dump(data,f,ensure_ascii=False,indent=2)
+        f.write('\n')
+    return path