devagent-ignition 0.1.0__py3-none-any.whl

devagent_spatial/model.py

@@ -0,0 +1,297 @@
+"""Fail-closed, non-operational customer project contracts for Spatial HMI V0.2."""
+from __future__ import annotations
+import copy
+import json
+import math
+import re
+from dataclasses import dataclass, asdict
+from typing import Any
+
+ID = re.compile(r'^[A-Z][A-Z0-9_]{1,31}$')
+KINDS = frozenset('conveyor spiral sorter motor vfd photoeye scanner tank pump valve robot junction room other'.split())
+LAYOUTS = frozenset(('spatial_overview', 'process_flow', 'standard_2d_flow', 'machine_detail', 'multi_zone'))
+ROLES = {
+    'run_feedback': ('Boolean', None),
+    'run_command': ('Boolean', None),
+    'fault': ('Boolean', None),
+    'fault_code': ('String', None),
+    'photoeye_blocked': ('Boolean', None),
+    'photoeye_count': ('Int32', 'count'),
+    'scanner_result': ('String', None),
+    'scanner_barcode': ('String', None),
+    'scan_count': ('Int32', 'count'),
+    'delivered_count': ('Int32', 'count'),
+    'in_transit_count': ('Int32', 'count'),
+    'no_read_count': ('Int32', 'count'),
+    'motor_speed': ('Double', 'm/s'),
+    'vfd_frequency': ('Double', 'Hz'),
+    'tank_level': ('Double', '%'),
+    'pressure': ('Double', 'bar'),
+    'flow': ('Double', 'm3/h'),
+    'valve_open': ('Boolean', None),
+    'mode': ('String', None),
+    'status': ('String', None),
+}
+NUMERIC = {'Int32', 'Double'}
+MAX_EQUIPMENT, MAX_SIGNALS, MAX_CONNECTIONS, MAX_REQUIREMENTS = 150, 1200, 400, 200
+PALETTES = frozenset({'r9_cyan', 'steel_blue', 'teal', 'warm_amber'})
+ALLOWED_ROOT = {'schema_version','name','industry','description','layout','theme','palette','equipment','connections','signals','requirements'}
+ALLOWED_EQUIPMENT = {'id','name','kind','floor','zone','position','dimensions'}
+ALLOWED_SIGNAL = {'id','asset_id','role','datatype','unit','polarity','source','write_authorized'}
+ALLOWED_SOURCE = {'namespace_uri','node_id'}
+ALLOWED_CONNECTION = {'from','to'}
+ALLOWED_REQUIREMENT = {'id','text'}
+
+
+def check_fields(value, allowed, issues, path):
+    if isinstance(value, dict):
+        for key in value:
+            if key not in allowed:
+                issue(issues,'HOLD','UNRECOGNIZED_FIELD',f'{path}.{key}',
+                      'Unknown field not accepted; explicit schema review required')
+
+DEFAULT_SIZES = {
+    'conveyor': (4.5, 0.4, 1.1), 'spiral': (3, 4.5, 3), 'sorter': (4, .8, 3),
+    'motor': (.8, .7, .9), 'vfd': (.8, 1.8, .5), 'photoeye': (.3, 1.1, .3),
+    'scanner': (.7, 1.4, .6), 'tank': (3, 5, 3), 'pump': (1.6, 1, 1.3),
+    'valve': (.6, .7, .6), 'robot': (2, 2.8, 2), 'junction': (1.8, .4, 1.8),
+    'room': (4, 3, 4), 'other': (2, 1, 2),
+}
+
+
+@dataclass(frozen=True)
+class Issue:
+    severity: str
+    code: str
+    path: str
+    message: str
+
+    def dump(self):
+        return asdict(self)
+
+
+def issue(items, severity, code, path, message):
+    items.append(Issue(severity, code, path, message))
+
+
+def clean_project(data: Any) -> tuple[dict, list[Issue]]:
+    """Return normalized copy + issues. HOLDs prevent build. Never infer source identities."""
+    problems = []
+    if not isinstance(data, dict):
+        return {}, [Issue('HOLD', 'INVALID_ROOT', '$', 'Expected project JSON object')]
+    data = copy.deepcopy(data)
+    # Reject text that cannot be serialized to UTF-8.  A malformed customer
+    # label must never crash generation or leave a partially published project.
+    pending = [data]
+    examined = 0
+    while pending:
+        item = pending.pop()
+        examined += 1
+        if examined > 20000:
+            issue(problems, 'HOLD', 'MODEL_NESTING_LIMIT', '$', 'Input has excessive nested elements')
+            break
+        if isinstance(item, dict):
+            pending.extend(item.values())
+        elif isinstance(item, list):
+            pending.extend(item)
+        elif isinstance(item, str):
+            try:
+                item.encode('utf-8', 'strict')
+            except UnicodeEncodeError:
+                issue(problems, 'HOLD', 'INVALID_UNICODE', '$', 'Input text contains invalid Unicode')
+                break
+    check_fields(data,ALLOWED_ROOT,problems,'$')
+    if data.get('schema_version') != 1:
+        issue(problems, 'HOLD', 'UNSUPPORTED_SCHEMA', 'schema_version', 'Expected integer schema_version=1')
+    for key in ('name', 'industry'):
+        v = data.get(key)
+        if not isinstance(v, str) or not 2 <= len(v.strip()) <= 90:
+            issue(problems, 'HOLD', 'INVALID_TEXT', key, 'Required text length 2–90')
+    description = data.get('description', '')
+    if not isinstance(description, str) or len(description) > 4000:
+        issue(problems, 'HOLD', 'INVALID_DESCRIPTION', 'description', 'Maximum length 4000')
+    if not isinstance(data.get('layout'),str) or data.get('layout') not in LAYOUTS:
+        issue(problems, 'HOLD', 'LAYOUT_INVALID', 'layout', f'Choose one of {sorted(LAYOUTS)}')
+    if data.get('theme', 'devagent_spatial_v1') != 'devagent_spatial_v1':
+        issue(problems, 'HOLD', 'UNAPPROVED_THEME', 'theme', 'V0.1 supports devagent_spatial_v1 only')
+    data['theme'] = 'devagent_spatial_v1'
+    palette = data.get('palette', 'r9_cyan')
+    if not isinstance(palette, str) or palette not in PALETTES:
+        issue(problems, 'HOLD', 'UNAPPROVED_BRAND_PALETTE', 'palette', 'Only validated DevAgent branding palettes are allowed')
+    else:
+        data['palette'] = palette
+    eq = data.get('equipment', [])
+    if not isinstance(eq, list) or not 1 <= len(eq) <= MAX_EQUIPMENT:
+        issue(problems, 'HOLD', 'EQUIPMENT_COUNT', 'equipment', f'Require 1–{MAX_EQUIPMENT} assets')
+        eq = []
+    ids = set()
+    floors = set()
+    layout_auto = 0
+    for i, e in enumerate(eq):
+        path = f'equipment[{i}]'
+        if not isinstance(e, dict):
+            issue(problems, 'HOLD', 'INVALID_EQUIPMENT', path, 'Expected object')
+            continue
+        check_fields(e,ALLOWED_EQUIPMENT,problems,path)
+        eid, kind = e.get('id'), e.get('kind')
+        if not isinstance(eid, str) or not ID.fullmatch(eid):
+            issue(problems, 'HOLD', 'INVALID_ASSET_ID', path+'.id', 'Use 2–32 uppercase letters, digits, underscores, starting with letter')
+        elif eid in ids:
+            issue(problems, 'HOLD', 'DUPLICATE_ASSET_ID', path+'.id', 'Asset ID must be unique')
+        else:
+            ids.add(eid)
+        if not isinstance(kind, str) or kind not in KINDS:
+            issue(problems, 'HOLD', 'INVALID_EQUIPMENT_KIND', path+'.kind', f'Choose {sorted(KINDS)}')
+        if not isinstance(e.get('name'), str) or not 1 <= len(e['name'].strip()) <= 100:
+            issue(problems, 'HOLD', 'INVALID_ASSET_NAME', path+'.name', 'Require name length 1–100')
+        if not isinstance(e.get('zone', ''), str) or len(e.get('zone', '')) > 70:
+            issue(problems, 'HOLD', 'INVALID_ZONE', path+'.zone', 'Zone must be text up to 70 chars')
+        floor = e.get('floor', 1)
+        if type(floor) is not int or not 1 <= floor <= 20:
+            issue(problems, 'HOLD', 'INVALID_FLOOR', path+'.floor', 'Floor must be integer 1–20')
+        else:
+            floors.add(floor)
+        pos = e.get('position')
+        if pos is None:
+            layout_auto += 1
+        elif not isinstance(pos, dict) or set(pos) != {'x','y','z'} or not all(k in pos and type(pos[k]) in (int, float) and math.isfinite(pos[k]) and -500 <= pos[k] <= 500 for k in ('x', 'y', 'z')):
+            issue(problems, 'HOLD', 'INVALID_POSITION', path+'.position', 'Use finite x,y,z in range ±500 meters')
+        dims = e.get('dimensions')
+        if dims is not None and (not isinstance(dims, dict) or set(dims) != {'x','y','z'} or not all(k in dims and type(dims[k]) in (int, float) and math.isfinite(dims[k]) and .15 <= dims[k] <= 50 for k in ('x', 'y', 'z'))):
+            issue(problems, 'HOLD', 'INVALID_DIMENSIONS', path+'.dimensions', 'Use finite positive x,y,z (0.15–50)')
+    connections = data.get('connections', [])
+    if not isinstance(connections, list) or len(connections) > MAX_CONNECTIONS:
+        issue(problems, 'HOLD', 'CONNECTIONS_COUNT', 'connections', f'Maximum {MAX_CONNECTIONS} connections')
+        connections = []
+    links = set()
+    for i, c in enumerate(connections):
+        path = f'connections[{i}]'
+        check_fields(c,ALLOWED_CONNECTION,problems,path)
+        if (not isinstance(c, dict) or not isinstance(c.get('from'), str) or
+                not isinstance(c.get('to'), str) or c.get('from') not in ids or c.get('to') not in ids):
+            issue(problems, 'HOLD', 'DANGLING_CONNECTION', path, 'Connection must refer to known equipment')
+        elif c['from'] == c['to'] or (c['from'], c['to']) in links:
+            issue(problems, 'HOLD', 'INVALID_CONNECTION', path, 'Self-loop or duplicate connection')
+        else:
+            links.add((c['from'], c['to']))
+    signals = data.get('signals', [])
+    if not isinstance(signals, list) or len(signals) > MAX_SIGNALS:
+        issue(problems, 'HOLD', 'SIGNAL_COUNT', 'signals', f'Maximum {MAX_SIGNALS} signals')
+        signals = []
+    signal_ids, identities, asset_roles = set(), set(), set()
+    for i, s in enumerate(signals):
+        path = f'signals[{i}]'
+        if not isinstance(s, dict):
+            issue(problems, 'HOLD', 'SIGNAL_INVALID', path, 'Expected object')
+            continue
+        check_fields(s,ALLOWED_SIGNAL,problems,path)
+        sid, eid, role = s.get('id'), s.get('asset_id'), s.get('role')
+        if not isinstance(sid, str) or not ID.fullmatch(sid) or sid in signal_ids:
+            issue(problems, 'HOLD', 'SIGNAL_ID_INVALID', path+'.id', 'Unique uppercase signal ID required')
+        else:
+            signal_ids.add(sid)
+        if not isinstance(eid, str) or eid not in ids:
+            issue(problems, 'HOLD', 'SIGNAL_UNKNOWN_ASSET', path+'.asset_id', 'Signal must link to an existing asset')
+        if not isinstance(role, str) or role not in ROLES:
+            issue(problems, 'HOLD', 'SIGNAL_ROLE_UNSUPPORTED', path+'.role', f'Supported: {sorted(ROLES)}')
+            continue
+        dt, default_unit = ROLES[role]
+        if s.get('datatype') != dt:
+            issue(problems, 'HOLD', 'SIGNAL_DATATYPE_MISMATCH', path+'.datatype', f'{role} must be {dt}')
+        actual_unit = s.get('unit', '')
+        if not isinstance(actual_unit, str) or len(actual_unit) > 24:
+            issue(problems, 'HOLD', 'UNIT_INVALID', path+'.unit', 'Unit must be short text')
+        if role in ('motor_speed', 'vfd_frequency', 'tank_level', 'pressure', 'flow') and not actual_unit:
+            issue(problems, 'HOLD', 'UNIT_REQUIRED', path+'.unit', f'{role} requires engineering units (e.g. {default_unit})')
+        elif default_unit is not None and actual_unit != default_unit:
+            issue(problems, 'HOLD', 'UNIT_SCALE_NOT_DEFINED', path+'.unit', f'{role} requires {default_unit}; supply approved scaling before alternate units')
+        elif default_unit is None and actual_unit:
+            issue(problems, 'HOLD', 'UNEXPECTED_SIGNAL_UNIT', path+'.unit', f'{role} must not claim engineering units')
+        polarity = s.get('polarity', '')
+        if role in ('photoeye_blocked', 'run_feedback', 'fault'):
+            if polarity not in ('active_high', 'active_low'):
+                issue(problems, 'HOLD', 'POLARITY_REQUIRED', path+'.polarity',
+                      'Boolean signal must declare active_high or active_low')
+        elif polarity != '':
+            issue(problems, 'HOLD', 'UNEXPECTED_SIGNAL_POLARITY', path+'.polarity',
+                  'Polarity applies only to supported boolean feedback/fault roles')
+        source = s.get('source', {})
+        if not isinstance(source, dict):
+            issue(problems, 'HOLD', 'INVALID_SOURCE', path+'.source', 'Expected source object')
+            continue
+        check_fields(source,ALLOWED_SOURCE,problems,path+'.source')
+        ns, node = source.get('namespace_uri'), source.get('node_id')
+        if not isinstance(ns, str) or not 8 <= len(ns) <= 240 or any(ord(ch)<32 for ch in ns) or not (ns.startswith('urn:') or ns.startswith('http:') or ns.startswith('https:')):
+            issue(problems, 'HOLD', 'NAMESPACE_UNRESOLVED', path+'.source.namespace_uri', 'Explicit namespace URI required; never guess namespace index')
+        if not isinstance(node, str) or not 1 <= len(node) <= 160 or any(ord(x) < 32 for x in node):
+            issue(problems, 'HOLD', 'NODE_UNRESOLVED', path+'.source.node_id', 'Explicit OPC UA NodeId identifier required')
+        if isinstance(ns, str) and isinstance(node, str):
+            if (ns, node) in identities:
+                issue(problems, 'HOLD', 'DUPLICATE_OPC_SOURCE', path+'.source', 'Multiple signals point at the same OPC source')
+            identities.add((ns, node))
+        if not isinstance(eid, str):
+            continue  # Unknown asset already HOLD; do not hash arbitrary JSON
+        if (eid, role) in asset_roles:
+            issue(problems, 'HOLD', 'DUPLICATE_ASSET_ROLE', path, 'Same asset and role mapped more than once')
+        asset_roles.add((eid, role))
+        if s.get('write_authorized', False) is not False:
+            issue(problems, 'HOLD', 'WRITE_AUTHORITY_NOT_ALLOWED', path+'.write_authorized', 'V0.1 generated views are read-only')
+    requirements = data.get('requirements', [])
+    if not isinstance(requirements, list) or len(requirements) > MAX_REQUIREMENTS:
+        issue(problems, 'HOLD', 'REQUIREMENTS_INVALID', 'requirements', f'Maximum {MAX_REQUIREMENTS} requirements')
+    else:
+        seen = set()
+        for i, r in enumerate(requirements):
+            check_fields(r,ALLOWED_REQUIREMENT,problems,f'requirements[{i}]')
+            if not isinstance(r, dict) or not isinstance(r.get('id'), str) or not ID.fullmatch(r['id']) or not isinstance(r.get('text'), str) or not 5 <= len(r['text']) <= 500:
+                issue(problems, 'HOLD', 'REQUIREMENT_INVALID', f'requirements[{i}]', 'Unique ID and 5–500 characters of text required')
+            elif r['id'] in seen:
+                issue(problems, 'HOLD', 'REQUIREMENT_DUPLICATE', f'requirements[{i}].id', 'Duplicate ID')
+            else:
+                seen.add(r['id'])
+    if data.get('industry') == 'Unspecified Industry':
+        issue(problems, 'WARNING', 'INDUSTRY_NOT_SPECIFIED', 'industry',
+              'Generic design only until the customer confirms the process domain')
+    if any(isinstance(e,dict) and e.get('zone') == 'FLOOR_UNSPECIFIED_PREVIEW_F1' for e in eq):
+        issue(problems, 'WARNING', 'FLOOR_ASSUMED_FOR_PREVIEW', 'equipment',
+              'Floor 1 is a conceptual display default, not verified facility floor count')
+    if any(isinstance(e,dict) and e.get('zone') == 'INFERRED_FROM_TAGS_REVIEW_REQUIRED' for e in eq):
+        issue(problems, 'WARNING', 'EQUIPMENT_INFERRED_FROM_TAGS', 'equipment',
+              'Equipment and kind are display candidates inferred from tag asset IDs; customer confirmation required')
+    if any(isinstance(e,dict) and e.get('kind') == 'other' for e in eq):
+        issue(problems, 'WARNING', 'GENERIC_EQUIPMENT_SYMBOL', 'equipment',
+              'Some equipment kinds are unspecified; generic symbols are conceptual, not machine identification')
+    from .engineering_expertise import review as expert_review
+    expert=expert_review(data)
+    for mismatch in expert['role_asset_mismatches']:
+        issue(problems, 'HOLD', 'ROLE_ASSET_KIND_MISMATCH', 'signals',
+              f"{mismatch['signal_id']}: role {mismatch['role']} is not appropriate for {mismatch['actual_kind']} ({mismatch['asset_id']})")
+    if not signals:
+        issue(problems, 'WARNING', 'NO_SIGNAL_MAPPINGS', 'signals', 'Preview works; no live signal mappings supplied')
+    if layout_auto:
+        issue(problems, 'WARNING', 'CONCEPTUAL_GEOMETRY', 'equipment', f'{layout_auto} assets require conceptual auto-layout; not an as-built representation')
+    if not connections and len(eq) > 1:
+        issue(problems, 'WARNING', 'TOPOLOGY_MISSING', 'connections', 'No equipment connections provided')
+    if signals:
+        issue(problems, 'WARNING', 'OPC_NOT_LIVE_VERIFIED', 'signals', 'All supplied mappings are proposed until read back from a verified OPC UA source')
+    if not requirements:
+        issue(problems, 'WARNING', 'REQUIREMENTS_NOT_PROVIDED', 'requirements', 'Generated FAT inventory cannot prove missing customer requirements')
+    return data, problems
+
+
+def qualify(data: dict) -> dict:
+    normalized, issues = clean_project(data)
+    holds = [x for x in issues if x.severity == 'HOLD']
+    return {'status': 'HOLD' if holds else 'PASS_STATIC_CONTRACT_ONLY',
+            'schema': 'devagent.spatial.contract_review.v1',
+            'issues': [x.dump() for x in issues],
+            'equipment_count': len(normalized.get('equipment', [])) if isinstance(normalized.get('equipment'), list) else 0,
+            'signals_proposed': len(normalized.get('signals', [])) if isinstance(normalized.get('signals'), list) else 0,
+            'live_opcua': 'NOT_VERIFIED', 'ignition_runtime': 'NOT_VERIFIED',
+            'physical_mapping': 'NOT_VERIFIED', 'hmi_visual_acceptance': 'NOT_VERIFIED',
+            'write_capability': 'DISABLED'}
+
+
+def json_embed(data: dict) -> str:
+    """Safe for embedding inside HTML <script> text."""
+    return json.dumps(data, ensure_ascii=False, separators=(',', ':'), sort_keys=True).replace('<', r'\u003c').replace('>', r'\u003e').replace('&', r'\u0026')

devagent_spatial/native_reference.py

@@ -0,0 +1,69 @@
+"""Read-only safety and structure audit for a customer-supplied Ignition native ZIP.
+
+This cannot verify the Perspective resource schema without a qualified reference.
+"""
+from __future__ import annotations
+import hashlib
+import stat
+import zipfile
+from pathlib import Path, PurePosixPath
+
+MAX_BYTES=100_000_000
+MAX_ITEM=24_000_000
+MAX_MEMBERS=12000
+MAX_RATIO=200
+
+
+def audit_ignition_archive(path:Path)->dict:
+    file=Path(path).expanduser()
+    codes=[]
+    def hold(code):codes.append(code)
+    if not file.is_file() or file.is_symlink():
+        return {'status':'HOLD','issues':['MISSING_OR_SYMLINK_NATIVE_ZIP']}
+    if file.stat().st_size>MAX_BYTES or file.stat().st_size<100:
+        return {'status':'HOLD','issues':['ZIP_SIZE_OUT_OF_BOUNDS']}
+    try:
+        digest=hashlib.sha256(file.read_bytes()).hexdigest()
+        with zipfile.ZipFile(file) as z:
+            members=z.infolist()
+            if len(members)>MAX_MEMBERS:hold('ARCHIVE_TOO_MANY_FILES')
+            if z.comment: hold('UNEXPECTED_ZIP_COMMENT')
+            names=set();total=0; native=False
+            for item in members:
+                name=item.filename
+                key=PurePosixPath(name)
+                if (not name or key.is_absolute() or '\\' in name or '..' in key.parts or
+                    name.startswith('./') or ':' in key.parts[0] or '\x00' in name):
+                    hold('UNSAFE_NATIVE_ARCHIVE_PATH')
+                if name in names:hold('DUPLICATE_NATIVE_ARCHIVE_ENTRY')
+                if item.file_size < 0 or item.compress_size < 0:hold('INVALID_NATIVE_MEMBER_SIZE')
+                names.add(name)
+                if item.flag_bits & 1:hold('ENCRYPTED_NATIVE_RESOURCE')
+                mode=(item.external_attr>>16)&0xffff
+                if mode and stat.S_IFMT(mode)==stat.S_IFLNK:hold('NATIVE_ARCHIVE_SYMLINK')
+                if not item.is_dir():
+                    total+=item.file_size
+                    if item.file_size>MAX_ITEM or (item.compress_size==0 and item.file_size>0):
+                        hold('NATIVE_RESOURCE_TOO_LARGE')
+                    elif item.file_size>MAX_RATIO*max(1,item.compress_size) and item.file_size>1_000_000:
+                        hold('SUSPICIOUS_NATIVE_COMPRESSION_RATIO')
+                if 'com.inductiveautomation.perspective' in name.lower() or '/perspective/' in name.lower():
+                    native=True
+            if total>MAX_BYTES:hold('NATIVE_UNCOMPRESSED_SIZE_EXCEEDED')
+            # Read all CRCs; refuse to execute scripts, extract, import, or parse scripts.
+            if not codes:
+                bad=z.testzip()
+                if bad:hold('NATIVE_ARCHIVE_CRC_ERROR')
+            if not native:hold('PERSPECTIVE_RESOURCE_SIGNATURE_NOT_FOUND')
+    except (OSError, zipfile.BadZipFile, RuntimeError, ValueError, EOFError):
+        hold('INVALID_NATIVE_ZIP')
+    return {
+        'schema':'devagent.ignition.native_reference_audit.v1',
+        'status':'HOLD' if codes else 'PASS_ZIP_SAFETY_ONLY',
+        'sha256':digest if 'digest' in locals() else None,
+        'issues':sorted(set(codes)),
+        'native_resource_schema':'NOT_VERIFIED',
+        'ignition_import':'NOT_TESTED',
+        'runtime_qualification':'NOT_VERIFIED',
+        'no_mutations':True,
+    }

devagent_spatial/opc_snapshot.py

@@ -0,0 +1,87 @@
+"""Optional read-only OPC UA protocol snapshot for isolated labs only.
+
+No server write nodes are accessed. No control commands are generated.
+An OPC read alone does not verify a physical device, trigger, or Ignition HMI.
+"""
+from __future__ import annotations
+import asyncio
+import datetime as dt
+from urllib.parse import urlsplit
+from .model import qualify, ROLES
+
+
+class SnapshotHold(ValueError):pass
+
+
+def allow_lab_endpoint(endpoint):
+    p=urlsplit(endpoint)
+    if (p.scheme!='opc.tcp' or p.hostname not in ('127.0.0.1','localhost','172.17.0.1') or
+            p.username or p.password or not p.port or not 1024<=p.port<=65535):
+        raise SnapshotHold('ONLY_APPROVED_LOOPBACK_OR_DOCKER_BRIDGE_LAB_ENDPOINT')
+    return endpoint
+
+
+async def check_reads(model:dict, namespace_array:list[str], read_node):
+    """Pure protocol verification, supports test doubles and the asyncua adapter."""
+    expected=qualify(model)
+    if expected['status']=='HOLD':raise SnapshotHold('PROJECT_CONTRACT_HOLD')
+    if len(model.get('signals',[]))>200:raise SnapshotHold('LAB_SNAPSHOT_MAX_200_SIGNALS')
+    rows=[]
+    for s in model.get('signals',[]):
+        source=s['source'];ns=source['namespace_uri']
+        row={'id':s['id'],'asset_id':s['asset_id'],'role':s['role'],
+             'namespace_uri':ns,'node_id':source['node_id'],
+             'expected_datatype':s['datatype'],'unit_contract':s.get('unit',''),
+             'polarity_contract':s.get('polarity',''),
+             'trigger':'NOT_EXERCISED','hmi':'NOT_VERIFIED','physical_mapping':'NOT_VERIFIED'}
+        if ns not in namespace_array:
+            row.update(status='HOLD_NAMESPACE_NOT_FOUND');rows.append(row);continue
+        index=namespace_array.index(ns)
+        node=f'ns={index};s={source["node_id"]}'
+        try:
+            observed=await read_node(node)
+            # Contract: transport adapter must report: good, variant type name, timestamp presence.
+            if not observed['good']:
+                row['status']='HOLD_BAD_OPC_QUALITY'
+            elif observed['type']!=s['datatype']:
+                row['status']='HOLD_DATATYPE_MISMATCH'
+            else:
+                row['status']='PASS_PROTOCOL_VALUE_ONLY'
+            row['observed_datatype']=observed['type']
+            row['timestamp_present']=bool(observed.get('timestamp_present'))
+            row['quality_good']=bool(observed['good'])
+            # Do not persist sensitive raw customer payloads in diagnostics.
+            row['value_recorded']=False
+        except Exception as exc:
+            row['status']='HOLD_READ_FAILED'
+            row['read_error_class']=type(exc).__name__
+        rows.append(row)
+    return {'schema':'devagent.spatial.opc_lab_snapshot.v1',
+            'status':'PASS_LAB_PROTOCOL_SNAPSHOT_ONLY' if rows and all(x['status']=='PASS_PROTOCOL_VALUE_ONLY' for x in rows) else 'HOLD',
+            'signals':rows,'signals_checked':len(rows),
+            'server_identity':'NOT_PROVEN_NO_SECURITY',
+            'physical_mapping':'NOT_VERIFIED','trigger':'NOT_EXERCISED','ignition_hmi':'NOT_VERIFIED',
+            'write_authority':'DISABLED'}
+
+
+async def probe_live(model,endpoint):
+    allow_lab_endpoint(endpoint)
+    try:
+        from asyncua import Client
+    except ImportError as exc:
+        raise SnapshotHold('ASYNCUA_NOT_INSTALLED_INSTALL_OPTIONAL_CLIENT_DEPENDENCY') from exc
+    async def run():
+        client=Client(endpoint,timeout=3)
+        async with client:
+            namespaces=await client.get_namespace_array()
+            async def read_node(node_id):
+                value=await client.get_node(node_id).read_data_value()
+                if value.Value is None:
+                    return {'good':False,'type':'NONE','timestamp_present':False}
+                return {'good':value.StatusCode.is_good(),
+                        'type':value.Value.VariantType.name,
+                        'timestamp_present':bool(value.SourceTimestamp or value.ServerTimestamp)}
+            return await check_reads(model,namespaces,read_node)
+    try:return await asyncio.wait_for(run(),timeout=30)
+    except (OSError,TimeoutError,RuntimeError,ValueError) as exc:
+        raise SnapshotHold('OPC_PROTOCOL_READ_UNAVAILABLE_'+type(exc).__name__) from exc