devagent-ignition 0.1.0__py3-none-any.whl

devagent_spatial/ignition_native.py

@@ -0,0 +1,234 @@
+"""Guarded native Perspective VIEW RESOURCE candidate compiler.
+
+Generated from customer models and a user-supplied *real* Perspective export.
+It never reaches a Gateway, invents tag-provider paths, or claims Ignition import.
+Only a new, read-only Perspective view is emitted. No scripts, events, or writes.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import tempfile
+import zipfile
+from collections import defaultdict
+from copy import deepcopy
+from pathlib import Path, PurePosixPath
+
+from .model import qualify
+from .native_reference import audit_ignition_archive
+from .generator import slugify
+from .strict_json import loads as strict_loads
+
+VIEW_PATH = re.compile(r'^(?P<prefix>(?:[^/]+/)*)com\.inductiveautomation\.perspective/views/(?P<name>.+)/view\.json$')
+CANDIDATE_SCHEMA = 'devagent.ignition.native_candidate.v0.3'
+MAX_NATIVE_COMPONENTS = 1600
+
+class NativeHold(ValueError):
+    pass
+
+
+def sha(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _j(blob: bytes, label: str):
+    if len(blob) > 3_000_000: raise NativeHold(f'{label}_TOO_LARGE')
+    try:
+        return strict_loads(blob.decode('utf-8'))
+    except (ValueError, UnicodeDecodeError, RecursionError):
+        raise NativeHold(f'{label}_NOT_VALID_JSON') from None
+
+
+def find_views(path: Path) -> dict:
+    """Safety inspect a project export and enumerate candidate template resources."""
+    audit = audit_ignition_archive(path)
+    if audit['status'] != 'PASS_ZIP_SAFETY_ONLY':
+        raise NativeHold('REFERENCE_ARCHIVE_HOLD: '+','.join(audit['issues']))
+    with zipfile.ZipFile(path) as z:
+        members = set(z.namelist())
+        viewfiles = []
+        for name in sorted(members):
+            match = VIEW_PATH.fullmatch(name)
+            if match and (name[:-len('view.json')]+'resource.json') in members:
+                viewfiles.append(name)
+        if not viewfiles:
+            raise NativeHold('NO_PERSPECTIVE_VIEWS_WITH_RESOURCE_METADATA')
+        projects = [n for n in sorted(members) if n == 'project.json' or n.endswith('/project.json')]
+        return {'status':'PASS_REFERENCE_STRUCTURE_ONLY','sha256':audit['sha256'],
+                'views':viewfiles,'project_json_candidates':projects,
+                'ignition_version':'NOT_ATTESTED','runtime_import':'NOT_TESTED'}
+
+
+def _label(text: str, size=14, bold=False, color='#ecf5ff', *, name='Label', pad=None) -> dict:
+    style = {'color':color,'fontSize':f'{size}px','fontFamily':'Arial, sans-serif',
+             'fontWeight':700 if bold else 400, 'whiteSpace':'normal'}
+    if pad: style['padding'] = pad
+    return {'type':'ia.display.label', 'version':0, 'meta':{'name':name},
+            'props':{'text':str(text)[:320], 'style':style},
+            'position':{'basis':'auto','grow':0,'shrink':0}}
+
+
+def _flex(children, *, name, direction='column', style=None, grow=0) -> dict:
+    return {'type':'ia.container.flex','version':0,'meta':{'name':name},
+            'props':{'direction':direction,'wrap':'wrap' if direction=='row' else 'nowrap',
+                     'style':style or {}},
+            'position':{'basis':'auto','grow':grow,'shrink':1},'children':children}
+
+
+def build_view(model: dict) -> dict:
+    """Native read-only view tree; asset and mapping identities are *not* live tag bindings."""
+    report = qualify(model)
+    if report['status'] != 'PASS_STATIC_CONTRACT_ONLY':
+        raise NativeHold('CUSTOMER_CONTRACT_HOLD')
+    palette = {'bg':'#07131f','panel':'#0e2638','border':'#294b61',
+               'accent':'#58c1dc','text':'#ecf5ff','muted':'#82a6b9','warning':'#e6bd70'}
+    by_asset = defaultdict(list)
+    for s in model.get('signals', []):by_asset[s['asset_id']].append(s)
+    floors = defaultdict(list)
+    for e in model['equipment']:floors[e.get('floor',1)].append(e)
+    top = _flex([
+        _label('DEVAGENT  /  SPATIAL OPERATIONS',13,True,palette['accent'],name='Brand'),
+        _label(model['name'],27,True,name='ProjectName'),
+        _label('READ-ONLY ENGINEERING CANDIDATE  •  ALL SIGNALS NOT LIVE VERIFIED',12,True,palette['warning'],name='ReleaseNotice')
+    ],name='Header',style={'backgroundColor':palette['panel'], 'borderBottom':'1px solid '+palette['border'], 'padding':18,'gap':5})
+    stats = _flex([
+        _label(f'{len(floors)} FLOOR(S)',15,True,palette['accent'],name='FloorCount'),
+        _label(f'{len(model["equipment"])} ASSETS',15,True,palette['accent'],name='AssetCount'),
+        _label(f'{len(model.get("signals",[]))} PROPOSED SIGNALS',15,True,palette['accent'],name='SignalCount'),
+        _label(f'{len(model.get("connections",[]))} CONNECTIONS',15,True,palette['accent'],name='ConnectionCount')
+    ],name='Summary',direction='row',style={'gap':28,'padding':16,'backgroundColor':palette['bg']})
+    group_views=[]
+    for floor, equip in sorted(floors.items()):
+        cards=[]
+        for e in equip:
+            rows=[_label(e['id'],16,True,palette['accent'],name='AssetId'),
+                  _label(e['name'],14,True,name='AssetName'),
+                  _label(f'{e["kind"]}   •   {e.get("zone") or "UNASSIGNED ZONE"}',11,color=palette['muted'],name='AssetDetail')]
+            asset_signals=sorted(by_asset[e['id']],key=lambda s:s['role'])
+            rows.extend(_label(f'{s["role"]}  /  {s["datatype"]}  /  NOT VERIFIED',11,
+                               color=palette['muted'],name='ProposedSignal') for s in asset_signals[:8])
+            if len(asset_signals)>8:
+                rows.append(_label(f'+{len(asset_signals)-8} additional proposed signals',11,color=palette['muted'],name='MoreSignals'))
+            if not asset_signals: rows.append(_label('NO SIGNAL MAPPING PROVIDED',11,color=palette['warning'],name='NoSignals'))
+            cards.append(_flex(rows,name='AssetCard',style={'backgroundColor':palette['panel'],'border':'1px solid '+palette['border'],
+                'borderRadius':8,'padding':14,'minWidth':235,'maxWidth':330,'gap':5}))
+        group_views.append(_flex([
+            _label('FLOOR '+str(floor),20,True,palette['accent'],name='FloorHeading'),
+            _flex(cards,name='EquipmentGrid',direction='row',style={'gap':12,'paddingTop':10})
+        ],name='FloorGroup',style={'padding':16,'gap':4}))
+    footer = _label('Engineer review required: verify equipment topology, tag providers, live OPC data, and Ignition runtime before deployment.',
+                    13,color=palette['warning'],name='QualificationFooter',pad=12)
+    root = _flex([top,stats,*group_views,footer],name='DevAgentRoot',
+                 style={'backgroundColor':palette['bg'],'color':palette['text'],
+                        'minHeight':650,'overflow':'auto','gap':2})
+    root.pop('position',None)  # a Perspective view's root has no parent container
+    # These standard view-envelope fields and component versions are present in
+    # genuine Ignition 8.3 Perspective exports. Keep them explicit so the
+    # generated resource is native Perspective rather than browser-preview JSON.
+    view = {'custom':{},'params':{},'propConfig':{},
+            'props':{'defaultSize':{'width':1440,'height':900}},'root':root}
+    def walk(c):
+        yield c
+        for ch in c.get('children',[]): yield from walk(ch)
+    count=sum(1 for _ in walk(root))
+    if count>MAX_NATIVE_COMPONENTS: raise NativeHold('NATIVE_VIEW_COMPLEXITY_LIMIT')
+    return view
+
+
+def _template_reference(reference_zip:Path, template_view:str, expected_sha256:str):
+    index = find_views(reference_zip)
+    if not re.fullmatch('[0-9a-f]{64}', expected_sha256):
+        raise NativeHold('EXACT_REFERENCE_SHA256_REQUIRED')
+    if index['sha256']!=expected_sha256:
+        raise NativeHold('NATIVE_REFERENCE_SHA256_MISMATCH')
+    if template_view not in index['views']:
+        raise NativeHold('TEMPLATE_VIEW_NOT_FOUND_IN_REFERENCE')
+    with zipfile.ZipFile(reference_zip) as z:
+        refview = _j(z.read(template_view),'REFERENCE_VIEW')
+        resource = _j(z.read(template_view[:-len('view.json')]+'resource.json'),'REFERENCE_RESOURCE')
+        # Deliberately do not execute, copy, or re-use a template component event/script.
+        if not isinstance(refview,dict) or not isinstance(refview.get('root'),dict) or not str(refview['root'].get('type','')).startswith('ia.container.'):
+            raise NativeHold('REFERENCE_VIEW_ENVELOPE_UNSUPPORTED')
+        if not isinstance(resource,dict) or 'view.json' not in resource.get('files',[]):
+            raise NativeHold('REFERENCE_RESOURCE_METADATA_UNSUPPORTED')
+        if any(not isinstance(k,str) for k in resource):raise NativeHold('REFERENCE_RESOURCE_METADATA_UNSUPPORTED')
+        return index,resource
+
+
+def native_member_names(template_view:str, target_name:str):
+    match=VIEW_PATH.fullmatch(template_view)
+    if not match:raise NativeHold('TEMPLATE_PATH_UNSUPPORTED')
+    base=match.group('prefix')+'com.inductiveautomation.perspective/views/DevAgentGenerated/'+target_name+'/'
+    return base+'view.json',base+'resource.json'
+
+
+def _candidate_resources(model,reference,template_view,reference_sha256):
+    index,base_resource=_template_reference(reference,template_view,reference_sha256)
+    view=build_view(model)
+    target = slugify(model['name']).replace('-','_')
+    viewpath,respath=native_member_names(template_view,target)
+    if viewpath in index['views']: raise NativeHold('TARGET_VIEW_ALREADY_EXISTS_IN_SOURCE')
+    # Construct fresh minimal resource metadata from the verified template.
+    # Do NOT clone UUIDs, attributes, secrets, or opaque template identity fields.
+    metadata={key:deepcopy(base_resource[key]) for key in ('scope','version','restricted','overridable') if key in base_resource}
+    # Match the standard reference envelope. Ignition 8.3's deserializer also
+    # accepts omitted attributes; this is not a fix for missing resource data.
+    # Never copy unreviewed source attributes.
+    metadata['attributes']={}
+    metadata['files']=['view.json']
+    # Do not carry template scripts, bindings, or extra files into a new view.
+    return {viewpath:(json.dumps(view,indent=2,ensure_ascii=False)+'\n').encode(),
+            respath:(json.dumps(metadata,indent=2,ensure_ascii=False)+'\n').encode()},index
+
+
+def compile_candidate(model:dict,reference:Path,template_view:str,expected_sha256:str,output:Path):
+    """Publish only NEW resources in a separate ZIP (not a full project export)."""
+    out=Path(output).expanduser().resolve()
+    if out.exists(): raise NativeHold('OUTPUT_ALREADY_EXISTS')
+    if out.suffix.lower()!='.zip' or not out.parent.is_dir():raise NativeHold('OUTPUT_MUST_BE_ZIP_IN_EXISTING_FOLDER')
+    before=sha(Path(reference))
+    resources,index=_candidate_resources(model,Path(reference),template_view,expected_sha256)
+    fd,tmp=tempfile.mkstemp(prefix='.devagent-native-',suffix='.zip',dir=str(out.parent))
+    os.close(fd)
+    try:
+        with zipfile.ZipFile(tmp,'w',compression=zipfile.ZIP_DEFLATED) as z:
+            for name,blob in sorted(resources.items()):
+                # No additional ZIP entries, metadata, tag provider, script, or control.
+                z.writestr(name,blob)
+        if before!=sha(Path(reference)):raise NativeHold('REFERENCE_MUTATED_DURING_GENERATION')
+        # Audit the actual staged candidate content before publish.
+        with zipfile.ZipFile(tmp) as z:
+            if set(z.namelist())!=set(resources):raise NativeHold('STAGED_NATIVE_FILES_MISMATCH')
+            if z.testzip():raise NativeHold('STAGED_NATIVE_CRC_ERROR')
+            for name,blob in resources.items():
+                if z.read(name)!=blob:raise NativeHold('STAGED_NATIVE_RESOURCE_CHANGED')
+        try: os.link(tmp,out)  # create-only atomic publication; existing output never overwritten
+        except FileExistsError: raise NativeHold('OUTPUT_ALREADY_EXISTS_AT_PUBLISH') from None
+        try:
+            os.chmod(out,0o600)
+        except OSError:pass
+    finally:
+        Path(tmp).unlink(missing_ok=True)
+    return {'schema':CANDIDATE_SCHEMA,'status':'PASS_OFFLINE_NATIVE_VIEW_CANDIDATE_ONLY',
+            'path':str(out),'sha256':sha(out),'reference_sha256':before,
+            'members':sorted(resources),'asset_count':len(model['equipment']),
+            'signal_count':len(model.get('signals',[])),
+            'native_view':'GENERATED_READ_ONLY','live_tag_bindings':'NOT_IMPLEMENTED',
+            'ignition_import':'NOT_TESTED','runtime_fat':'NOT_EXECUTED',
+            'production_release':'HOLD'}
+
+
+def verify_candidate(model,reference,template_view,expected_sha256,candidate):
+    path=Path(candidate)
+    if not path.is_file() or path.is_symlink():raise NativeHold('CANDIDATE_NOT_SAFE_REGULAR_FILE')
+    expected,index=_candidate_resources(model,Path(reference),template_view,expected_sha256)
+    with zipfile.ZipFile(path) as z:
+        if len(z.infolist()) != len(expected) or set(z.namelist())!=set(expected):
+            raise NativeHold('CANDIDATE_FILE_ALLOWLIST_MISMATCH')
+        if z.testzip():raise NativeHold('CANDIDATE_CRC_FAILURE')
+        for name,blob in expected.items():
+            if z.read(name)!=blob:raise NativeHold('CANDIDATE_CONTENT_NOT_REPRODUCIBLE')
+    return {'status':'PASS_OFFLINE_NATIVE_VIEW_CANDIDATE_ONLY','sha256':sha(path),
+            'ignition_import':'NOT_TESTED','live_bindings':'NOT_IMPLEMENTED','production_release':'HOLD'}

devagent_spatial/ignition_project.py

@@ -0,0 +1,144 @@
+"""Conservative *offline* native Ignition project-candidate packager.
+
+A project candidate contains only a scrubbed project.json + new generated
+Perspective view resource. It is NOT a Gateway-qualified project export.
+No original scripts, Perspective page routes, tags, bindings, or controls are copied.
+This module never communicates with or modifies an Ignition Gateway.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+import tempfile
+import zipfile
+from pathlib import Path
+from .ignition_native import (_candidate_resources, NativeHold, sha, _j, VIEW_PATH)
+from .native_reference import audit_ignition_archive
+from .model import qualify
+
+SCHEMA='devagent.ignition.isolated_project_candidate.v0.4'
+PROJECT_ID=re.compile(r'[A-Za-z][A-Za-z0-9_]{2,49}\Z')
+CONFIRM='OFFLINE_CANDIDATE_NO_GATEWAY_IMPORT'
+MAX_CANDIDATE_BYTES=4_000_000
+
+
+def _project_blob(reference:Path, template_view:str, name:str, *, enabled:bool=False) -> tuple[str,bytes,dict]:
+    if not PROJECT_ID.fullmatch(name):
+        raise NativeHold('NEW_PROJECT_NAME_INVALID_USE_ASCII_LETTER_DIGIT_UNDERSCORE')
+    # A single explicit project.json must correspond to the view's envelope.
+    with zipfile.ZipFile(reference) as z:
+        names=set(z.namelist())
+        prefix=VIEW_PATH.fullmatch(template_view)
+        if prefix is None:raise NativeHold('TEMPLATE_VIEW_PATH_UNSUPPORTED')
+        project_path=prefix.group('prefix')+'project.json'
+        projects={n for n in names if n=='project.json' or n.endswith('/project.json')}
+        if projects!={project_path}:
+            raise NativeHold('REFERENCE_PROJECT_ROOT_AMBIGUOUS')
+        existing=_j(z.read(project_path),'PROJECT_PROPERTIES')
+    if not isinstance(existing,dict):raise NativeHold('REFERENCE_PROJECT_PROPERTIES_INVALID')
+    if not isinstance(existing.get('title',''),str):raise NativeHold('REFERENCE_PROJECT_TITLE_INVALID')
+    if existing.get('title','').casefold()==name.casefold():
+        raise NativeHold('NEW_PROJECT_NAME_MATCHES_SOURCE_TITLE')
+    # Importing a project may support naming at the Gateway rather than from title;
+    # this is intentionally only a display-title hint for an isolated NEW project.
+    # Never copy source project scripts, parent inheritance, or opaque metadata.
+    if not isinstance(enabled,bool):raise NativeHold('PROJECT_ENABLED_FLAG_INVALID')
+    properties={'title':name,'description':'DevAgent offline candidate — review and isolated Gateway qualification required',
+                'enabled':enabled,'inheritable':False,'parent':''}
+    return project_path,(json.dumps(properties,sort_keys=True,indent=2)+'\n').encode(),{
+        'source_title':existing.get('title','UNSPECIFIED'),
+        'discarded_project_fields':sorted(set(existing)-set(properties)),
+        'enabled':enabled,
+    }
+
+
+def expected_files(model:dict, reference:Path,template_view:str,expected_sha256:str,name:str):
+    if qualify(model)['status']!='PASS_STATIC_CONTRACT_ONLY':
+        raise NativeHold('CUSTOMER_MODEL_HOLD')
+    reference=Path(reference)
+    resources,index=_candidate_resources(model,reference,template_view,expected_sha256)
+    project_path,properties,project_info=_project_blob(reference,template_view,name)
+    members={project_path:properties,**resources}
+    if len(members)!=3:raise NativeHold('CANDIDATE_MEMBER_COLLISION')
+    return members,project_info
+
+
+def _zip_blob(members:dict)->bytes:
+    import io
+    buffer=io.BytesIO()
+    with zipfile.ZipFile(buffer,'w',zipfile.ZIP_DEFLATED,compresslevel=9) as z:
+        for name,payload in sorted(members.items()):
+            info=zipfile.ZipInfo(name,date_time=(2020,1,1,0,0,0))
+            info.compress_type=zipfile.ZIP_DEFLATED
+            info.external_attr=(0o100600<<16)
+            z.writestr(info,payload)
+    result=buffer.getvalue()
+    if len(result)>MAX_CANDIDATE_BYTES:raise NativeHold('CANDIDATE_TOO_LARGE')
+    return result
+
+
+def compile_project(model:dict,reference:Path,template_view:str,expected_sha256:str,
+                    name:str,out:Path,confirm:str):
+    if confirm!=CONFIRM:raise NativeHold('OFFLINE_CANDIDATE_CONFIRMATION_REQUIRED')
+    out=Path(out).expanduser().absolute()
+    if out.suffix.lower()!='.zip' or not out.parent.is_dir() or out.is_symlink():
+        raise NativeHold('OUTPUT_MUST_BE_NEW_ZIP_IN_EXISTING_FOLDER')
+    if out.exists():raise NativeHold('OUTPUT_ALREADY_EXISTS')
+    src=Path(reference).expanduser().absolute()
+    original_sha=sha(src)
+    members,source_info=expected_files(model,src,template_view,expected_sha256,name)
+    content=_zip_blob(members)
+    if original_sha!=sha(src):raise NativeHold('SOURCE_CHANGED_DURING_BUILD')
+    fd,temp=tempfile.mkstemp(prefix='.devagent-project-',suffix='.zip',dir=str(out.parent))
+    try:
+        with os.fdopen(fd,'wb') as f:
+            f.write(content)
+            f.flush()
+            os.fsync(f.fileno())
+        # Full staged artifact must match independent generated expectation.
+        with zipfile.ZipFile(temp) as z:
+            if set(z.namelist())!=set(members) or z.testzip():
+                raise NativeHold('STAGED_PROJECT_INVALID')
+            for path,payload in members.items():
+                if z.read(path)!=payload:raise NativeHold('STAGED_PROJECT_MISMATCH')
+        try:os.link(temp,out)
+        except FileExistsError:raise NativeHold('OUTPUT_ALREADY_EXISTS_AT_PUBLISH') from None
+        try:os.chmod(out,0o600)
+        except OSError:pass
+    finally:Path(temp).unlink(missing_ok=True)
+    return {'schema':SCHEMA,'status':'PASS_OFFLINE_ISOLATED_PROJECT_CANDIDATE_ONLY',
+            'candidate_path':str(out),'candidate_sha256':sha(out),
+            'reference_sha256':original_sha,'generated_files':sorted(members),
+            'source_project_properties':source_info,
+            'source_resources_inherited':0,'gateway_scripts_inherited':0,
+            'generated_write_actions':0,'native_page_routing':'NOT_GENERATED',
+            'live_bindings':'NOT_GENERATED','ignition_import':'NOT_TESTED',
+            'ignition_runtime':'NOT_TESTED','production_release':'HOLD'}
+
+
+def verify_project(model:dict,reference:Path,template_view:str,expected_sha256:str,
+                   name:str,out:Path):
+    out=Path(out)
+    if not out.is_file() or out.is_symlink():raise NativeHold('CANDIDATE_NOT_SAFE_FILE')
+    members,source_info=expected_files(model,Path(reference),template_view,expected_sha256,name)
+    try:
+        if out.stat().st_size>MAX_CANDIDATE_BYTES:raise NativeHold('CANDIDATE_TOO_LARGE')
+        with zipfile.ZipFile(out) as z:
+            entries=z.infolist()
+            if len(entries)!=3 or set(z.namelist())!=set(members):
+                raise NativeHold('CANDIDATE_ALLOWLIST_VIOLATION')
+            if z.testzip():raise NativeHold('CANDIDATE_CRC_ERROR')
+            for e in entries:
+                if e.flag_bits & 1 or stat.S_IFMT(e.external_attr>>16)==stat.S_IFLNK:
+                    raise NativeHold('CANDIDATE_UNSAFE_ZIP_ENTRY')
+                if e.file_size>3_000_000:raise NativeHold('CANDIDATE_RESOURCE_TOO_LARGE')
+                if z.read(e)!=members[e.filename]:raise NativeHold('CANDIDATE_REPRODUCIBILITY_MISMATCH')
+    except zipfile.BadZipFile:raise NativeHold('CANDIDATE_BAD_ZIP') from None
+    if out.read_bytes()!=_zip_blob(members):raise NativeHold('CANDIDATE_ZIP_BYTES_NOT_REPRODUCIBLE')
+    return {'schema':SCHEMA,'status':'PASS_OFFLINE_ISOLATED_PROJECT_CANDIDATE_ONLY',
+            'candidate_sha256':sha(out),'reference_sha256':sha(Path(reference)),
+            'members_verified':len(members),'ignition_import':'NOT_TESTED',
+            'live_bindings':'NOT_GENERATED','production_release':'HOLD'}

devagent_spatial/live_lab_binding.py

@@ -0,0 +1,128 @@
+"""Fail-closed read-only Studio -> generated HMI lab signal adapter.
+
+This is NOT an Ignition binding or physical PLC mapping verification. The
+sole authority is a project-scoped read-only Studio session established in the
+external Engineering test workspace. No write path exists in this module.
+"""
+from __future__ import annotations
+import asyncio
+import copy
+import time
+from threading import Lock
+from collections import deque
+from .operations import OperationsHold
+from .operations import evaluate, mapping_digest, OperationsHold
+from .operations_capture import capture_lab
+from .operations_lab import LAB_NAMESPACE
+from . import studio_workflow as wf
+
+
+class LiveLabHold(ValueError):
+    pass
+
+
+class LiveLabBridge:
+    def __init__(self):
+        self._sessions = {}
+        self._lock = Lock()
+
+    def attach(self, workspace, pid, port, *, session=None, readonly_receipt=None):
+        """Attach only after proof of exact lab namespace/NodeIds/type manifest."""
+        model=wf.load_project(workspace,pid)
+        state=wf.studio_state(port)
+        lab=copy.deepcopy(model)
+        for signal in lab['signals']:
+            signal['source']['namespace_uri']=LAB_NAMESPACE
+        if not wf._manifest_ok(wf.studio_request(port,'GET','/api/manifest'),lab):
+            raise LiveLabHold('STUDIO_MANIFEST_DOES_NOT_MATCH_PROJECT')
+        if session is not None:
+            wf.require_session(workspace,pid,port,session)
+            authority='CREATOR_LAB_SESSION_READONLY'
+        else:
+            # An unbound lab can ONLY attach after a completed, exact read-only
+            # probe; this DOES NOT authorize fault stimulation or tag writes.
+            if not isinstance(readonly_receipt,dict) or readonly_receipt.get('status')!='PASS_UNBOUND_READONLY_LAB_PROTOCOL_ONLY':
+                raise LiveLabHold('READONLY_PROJECT_PROBE_EVIDENCE_REQUIRED')
+            if (readonly_receipt.get('mapping_digest')!=mapping_digest(model) or
+                readonly_receipt.get('verified_nodes')!=len(model['signals']) or
+                readonly_receipt.get('total_nodes')!=len(model['signals'])):
+                raise LiveLabHold('READONLY_PROJECT_PROBE_IDENTITY_MISMATCH')
+            identity=readonly_receipt.get('studio_identity',{})
+            if (identity.get('revision')!=state['customer']['revision'] or
+                identity.get('endpoint')!=state['opc_endpoint'] or
+                abs(float(identity.get('started',-999999))-(time.time()-float(state['uptime_seconds'])))>5):
+                raise LiveLabHold('READONLY_PROJECT_SESSION_CHANGED')
+            authority='UNBOUND_VERIFIED_MANIFEST_READONLY'
+        binding={'project_digest':mapping_digest(model), 'lab_digest':mapping_digest(lab),
+                 'endpoint':state['opc_endpoint'], 'revision':state['customer']['revision'],
+                 'studio_started':time.time()-float(state['uptime_seconds']),
+                 'authority':authority, 'attached_at':time.monotonic(), 'observed_frames':deque(maxlen=40)}
+        with self._lock:
+            self._sessions[pid]=binding
+        return {'status':'READONLY_LAB_FEED_ATTACHED','project_id':pid,
+                'signal_count':len(model['signals']), 'authority':authority,
+                'source':'ISOLATED_STUDIO_OPC_UA','ignition':'NOT_VERIFIED','production':'HOLD'}
+
+    def enabled(self,pid):
+        with self._lock:return pid in self._sessions
+
+    def detach(self,pid):
+        with self._lock:self._sessions.pop(pid,None)
+
+    def _guard(self,workspace,pid,port,binding):
+        model=wf.load_project(workspace,pid)
+        if mapping_digest(model)!=binding['project_digest']:
+            raise LiveLabHold('PROJECT_MAPPING_CHANGED')
+        state=wf.studio_state(port)
+        if (state['customer']['revision']!=binding['revision'] or
+            state['opc_endpoint']!=binding['endpoint'] or
+            abs((time.time()-float(state['uptime_seconds']))-binding['studio_started'])>5):
+            raise LiveLabHold('STUDIO_SOURCE_SESSION_CHANGED')
+        lab=copy.deepcopy(model)
+        for signal in lab['signals']:
+            signal['source']['namespace_uri']=LAB_NAMESPACE
+        if mapping_digest(lab)!=binding['lab_digest']:
+            raise LiveLabHold('LAB_ALIAS_CHANGED')
+        if not wf._manifest_ok(wf.studio_request(port,'GET','/api/manifest'),lab):
+            raise LiveLabHold('STUDIO_TAG_MANIFEST_CHANGED')
+        return model,lab,state
+
+    def read(self,workspace,pid,port):
+        with self._lock:binding=self._sessions.get(pid)
+        if binding is None:
+            return {'status':'NO_APPROVED_LAB_SOURCE','mode':'NO_LIVE_SOURCE',
+                    'ignition':'NOT_VERIFIED','production':'HOLD'}
+        try:
+            model,lab,state=self._guard(workspace,pid,port,binding)
+            frames=asyncio.run(capture_lab(lab,state['opc_endpoint'],samples=1))
+            # Reconcile LAB namespace alias to the exact customer logical signal
+            # contract. Never modify the customer model or claim PLC identity.
+            for frame in frames:
+                for observed in frame['observations']:
+                    original=next(s for s in model['signals'] if s['id']==observed['signal_id'])
+                    observed['namespace_uri']=original['source']['namespace_uri']
+            with self._lock:
+                if self._sessions.get(pid) is not binding:
+                    raise LiveLabHold('LAB_SOURCE_DETACHED_DURING_CAPTURE')
+                # One history per exact authorized lab session: event transitions
+                # are tracked across OPC polls, never invented on each refresh.
+                observed=binding['observed_frames']
+                if observed and frames[0]['at']<=observed[-1]['at']:
+                    raise LiveLabHold('NON_MONOTONIC_LIVE_CAPTURE')
+                observed.extend(frames)
+                history=list(observed)
+            receipt=evaluate(model,history,origin='ISOLATED_LAB_OPC_READ_ONLY')
+            if receipt['mapping_digest']!=binding['project_digest']:
+                raise LiveLabHold('RECEIPT_CONTRACT_MISMATCH')
+            return {'status':'PASS_STUDIO_LAB_DISPLAY_ONLY',
+                    'source':'ISOLATED_STUDIO_OPC_UA_READONLY',
+                    'authority':binding['authority'],
+                    'studio_source_identity':'LAB_ONLY_NOT_PHYSICAL_PLC',
+                    'receipt':receipt,
+                    'ignition':'NOT_VERIFIED','production':'HOLD'}
+        except Exception as exc:
+            self.detach(pid)
+            code=str(exc) if isinstance(exc,(wf.LabHold,OperationsHold,LiveLabHold)) else 'LAB_SOURCE_READ_HOLD'
+            if len(code)>115:code='LAB_SOURCE_READ_HOLD'
+            return {'status':'HOLD','reason':code, 'mode':'SOURCE_UNKNOWN',
+                    'ignition':'NOT_VERIFIED','production':'HOLD'}