devagent-ignition 0.1.0__py3-none-any.whl

devagent_spatial/v07_native.py

@@ -0,0 +1,318 @@
+"""V0.7: create-only, offline, read-only Perspective candidate + route.
+
+DOES NOT import to Gateway, connect to PLC, certify physical mappings or execute FAT.
+Binding source is the explicit engineer-owned lab manifest; no NodeId -> tag path inference.
+All generated resources are sanitized: no scripts, events, outputs, commands, or writes.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+import tempfile
+import zipfile
+from copy import deepcopy
+from pathlib import Path
+
+from .generator import fat_inventory, slugify, ROOT
+from .ignition_native import NativeHold, _j, _label, _flex, build_view, _template_reference, native_member_names, sha, VIEW_PATH
+from .ignition_project import _project_blob, _zip_blob
+from .model import qualify
+from .strict_json import loads as strict_loads
+
+SCHEMA = 'devagent.ignition.v07.lab_compiler.v1'
+MANIFEST_SCHEMA = 'devagent.ignition.v07.lab_bindings.v1'
+CONFIRM = 'ISOLATED_OFFLINE_COMPILER_ONLY'
+PAGE_CONFIG = 'com.inductiveautomation.perspective/page-config/config.json'
+PAGE_RESOURCE = 'com.inductiveautomation.perspective/page-config/resource.json'
+LAB_PATH = re.compile(r'^\[DevAgentLab[A-Za-z0-9_]{0,32}\](?:[A-Za-z0-9_][A-Za-z0-9_ -]{0,59}/)*[A-Za-z0-9_][A-Za-z0-9_ -]{0,59}$')
+H64 = re.compile(r'^[0-9a-f]{64}$')
+
+
+def canonical(obj: dict) -> bytes:
+    return (json.dumps(obj, sort_keys=True, ensure_ascii=False, separators=(',', ':'))+'\n').encode('utf-8')
+
+
+def model_sha(model: dict) -> str:
+    return hashlib.sha256(canonical(model)).hexdigest()
+
+
+def manifest_skeleton(model: dict) -> dict:
+    if qualify(model)['status'] != 'PASS_STATIC_CONTRACT_ONLY':
+        raise NativeHold('CUSTOMER_MODEL_HOLD')
+    return {'schema': MANIFEST_SCHEMA, 'model_sha256': model_sha(model),
+            'scope': 'ISOLATED_TEST_GATEWAY_ONLY', 'engineer': '',
+            'bindings': [{'signal_id':s['id'],'asset_id':s['asset_id'],'role':s['role'],
+                          'source':deepcopy(s['source']),'tag_path':'',
+                          'approval':'PENDING_ENGINEER_REVIEW'} for s in model.get('signals',[])],
+            'note':'No tag paths are inferred. Provide only isolated DevAgentLab provider paths from reviewed test Gateway.'}
+
+
+def validate_manifest(model: dict, manifest: dict) -> dict:
+    if qualify(model)['status']!='PASS_STATIC_CONTRACT_ONLY':raise NativeHold('CUSTOMER_MODEL_HOLD')
+    if not isinstance(manifest,dict) or set(manifest)!={'schema','model_sha256','scope','engineer','bindings','note'}:
+        raise NativeHold('BINDING_MANIFEST_SCHEMA_INVALID')
+    if manifest['schema']!=MANIFEST_SCHEMA or manifest['model_sha256']!=model_sha(model):
+        raise NativeHold('BINDING_MANIFEST_MODEL_IDENTITY_MISMATCH')
+    if manifest['scope']!='ISOLATED_TEST_GATEWAY_ONLY':raise NativeHold('BINDING_SCOPE_NOT_ISOLATED')
+    if not isinstance(manifest['engineer'],str) or not 3<=len(manifest['engineer'].strip())<=120:
+        raise NativeHold('ENGINEER_ID_REQUIRED')
+    if not isinstance(manifest['note'],str) or len(manifest['note'])>600:
+        raise NativeHold('BINDING_MANIFEST_NOTE_INVALID')
+    bindings=manifest['bindings']
+    signals={s['id']:s for s in model['signals']}
+    if not signals or not isinstance(bindings,list) or len(bindings)!=len(signals):
+        raise NativeHold('ALL_DECLARED_SIGNALS_REQUIRE_EXPLICIT_DISPOSITION')
+    seen,paths,approved=set(),set(),{}
+    for entry in bindings:
+        if not isinstance(entry,dict) or set(entry)!={'signal_id','asset_id','role','source','tag_path','approval'}:
+            raise NativeHold('BINDING_ENTRY_SCHEMA_INVALID')
+        sid=entry['signal_id']
+        if not isinstance(sid,str) or sid not in signals or sid in seen:raise NativeHold('BINDING_SIGNAL_ID_UNKNOWN_OR_DUPLICATE')
+        seen.add(sid);s=signals[sid]
+        if any(entry[f]!=s[f] for f in ('asset_id','role','source')):
+            raise NativeHold('BINDING_SOURCE_OR_ASSET_MISMATCH: '+sid)
+        path=entry['tag_path']; decision=entry['approval']
+        if decision=='PENDING_ENGINEER_REVIEW':
+            if path!='':raise NativeHold('PENDING_BINDING_CANNOT_HAVE_PATH: '+sid)
+        elif decision=='APPROVED_FOR_ISOLATED_FAT_ONLY':
+            if not isinstance(path,str) or len(path)>220 or not LAB_PATH.fullmatch(path):
+                raise NativeHold('UNSAFE_OR_NON_LAB_TAG_PATH: '+sid)
+            if path in paths:raise NativeHold('DUPLICATE_LAB_TAG_PATH: '+sid)
+            paths.add(path);approved[sid]=path
+        else:
+            raise NativeHold('BINDING_APPROVAL_INVALID: '+sid)
+    if seen!=set(signals):raise NativeHold('BINDING_SIGNAL_COVERAGE_MISMATCH')
+    # Zero independently approved paths is a valid commissioning state. The
+    # generated HMI must show NOT MAPPED rather than invent a Gateway binding.
+    return approved
+
+
+def _walk(component):
+    yield component
+    for child in component.get('children',[]):yield from _walk(child)
+
+
+def _bound_display(signal:dict, path: str | None):
+    label=_label('UNKNOWN' if path else 'NOT MAPPED',13,True,
+                 '#e6bd70' if path is None else '#ecf5ff',name='LiveValue')
+    if path:
+        # Perspective defaults must retain BAD/STALE quality overlays (no opt-out).
+        label['propConfig']={'props.text':{'binding':{'type':'tag',
+                         'config':{'mode':'direct','tagPath':path}}}}
+    return _flex([
+        _label('RAW '+signal['role'].replace('_',' ').upper(),11,False,'#82a6b9',name='SignalRole'),
+        label,
+        _label(signal.get('unit','') or ' ',10,False,'#82a6b9',name='EngineeringUnit')
+    ],name='SignalRow',direction='row',style={'alignItems':'center','justifyContent':'space-between',
+                  'gap':12,'borderTop':'1px solid #294b61','paddingTop':7,'paddingBottom':3})
+
+
+def bound_view(model:dict,manifest:dict):
+    approved=validate_manifest(model,manifest)
+    view=build_view(model)
+    # Preserve R9 geometry and safety semantics while applying approved brand palette.
+    design=strict_loads((ROOT/'design-system.json').read_text(encoding='utf8'))
+    brand=design['palettes'][model.get('palette','r9_cyan')]
+    token_map={'#07131f':brand['background'], '#0e2638':brand['panel'],
+               '#294b61':brand['border'], '#58c1dc':brand['accent'],
+               '#82a6b9':brand['muted']}
+    # Replace the conceptual rows, never reuse untrusted reference scripts.
+    signals={s['id']:s for s in model['signals']}
+    by_asset={e['id']:[] for e in model['equipment']}
+    for s in model['signals']:by_asset[s['asset_id']].append(s)
+    for comp in _walk(view['root']):
+        if comp.get('meta',{}).get('name')!='AssetCard':continue
+        idlabels=[c for c in comp['children'] if c.get('meta',{}).get('name')=='AssetId']
+        if len(idlabels)!=1:raise NativeHold('NATIVE_ASSET_CARD_ID_INVALID')
+        eid=idlabels[0]['props']['text']
+        static=[c for c in comp['children'] if c.get('meta',{}).get('name') in ('AssetId','AssetName','AssetDetail')]
+        comp['children']=static+[_bound_display(s,approved.get(s['id']))
+                  for s in sorted(by_asset[eid],key=lambda item:item['role'])]
+        if not by_asset[eid]:comp['children'].append(_label('NOT MAPPED',12,True,'#e6bd70',name='UnmappedAsset'))
+    # VIEW BUILD: Never present unverified values as real PLC telemetry.
+    for comp in _walk(view['root']):
+        if comp.get('meta',{}).get('name')=='ReleaseNotice':
+            comp['props']['text']='ISOLATED LAB CANDIDATE • BINDINGS NOT PHYSICALLY VERIFIED • READ ONLY'
+    def repaint(value):
+        if isinstance(value,dict):return {k:repaint(v) for k,v in value.items()}
+        if isinstance(value,list):return [repaint(x) for x in value]
+        if isinstance(value,str):
+            for old,new in token_map.items():value=value.replace(old,new)
+        return value
+    view=repaint(view)
+    if sum(1 for _ in _walk(view['root']))>1600:raise NativeHold('NATIVE_VIEW_COMPLEXITY_LIMIT')
+    return view
+
+
+def _page_resource(reference:Path,template_view:str):
+    match=VIEW_PATH.fullmatch(template_view)
+    if not match:raise NativeHold('TEMPLATE_VIEW_PATH_UNSUPPORTED')
+    prefix=match.group('prefix')
+    pc,pr=prefix+PAGE_CONFIG,prefix+PAGE_RESOURCE
+    with zipfile.ZipFile(reference) as z:
+        names=set(z.namelist())
+        if pc not in names or pr not in names:
+            raise NativeHold('REAL_REFERENCE_PAGE_CONFIG_REQUIRED')
+        config=_j(z.read(pc),'REFERENCE_PAGE_CONFIG')
+        resource=_j(z.read(pr),'REFERENCE_PAGE_RESOURCE')
+    if not isinstance(config,dict) or not isinstance(config.get('pages'),dict):
+        raise NativeHold('REFERENCE_PAGE_CONFIG_SHAPE_UNSUPPORTED')
+    if not isinstance(resource,dict) or 'config.json' not in resource.get('files',[]):
+        raise NativeHold('REFERENCE_PAGE_RESOURCE_SHAPE_UNSUPPORTED')
+    return pc,pr,resource
+
+
+def expected_members(model:dict,manifest:dict,reference:Path,template_view:str,
+                     reference_sha256:str,new_project_name:str,*,project_enabled:bool=True):
+    approved=validate_manifest(model,manifest)
+    if not H64.fullmatch(reference_sha256):raise NativeHold('EXACT_REFERENCE_SHA256_REQUIRED')
+    reference=Path(reference)
+    index,base_resource=_template_reference(reference,template_view,reference_sha256)
+    # This routed lab artifact is executable only as a new isolated project.
+    # It remains read-only and production-held. The older generic project
+    # candidate API stays disabled by default.
+    project_path,project_blob,project_info=_project_blob(
+        reference,template_view,new_project_name,enabled=project_enabled)
+    pc,pr,page_res=_page_resource(reference,template_view)
+    name=slugify(model['name']).replace('-','_')
+    view_path,res_path=native_member_names(template_view,name)
+    if view_path in index['views']:raise NativeHold('TARGET_VIEW_ALREADY_EXISTS_IN_REFERENCE')
+    if len(model.get('equipment',[]))>150:raise NativeHold('EQUIPMENT_LIMIT')
+    def resource_from(template,filename):
+        metadata={k:deepcopy(template[k]) for k in ('scope','version','restricted','overridable') if k in template}
+        metadata['attributes']={}
+        metadata['files']=[filename]
+        return metadata
+    view=bound_view(model,manifest)
+    route={'pages':{'/':{'viewPath':'DevAgentGenerated/'+name,
+                         'title':'DevAgent • '+model['name'][:85]}},'sharedDocks':{}}
+    members={project_path:project_blob,
+             view_path:canonical(view),res_path:canonical(resource_from(base_resource,'view.json')),
+             pc:canonical(route),pr:canonical(resource_from(page_res,'config.json'))}
+    if len(members)!=5:raise NativeHold('NATIVE_MEMBER_COLLISION')
+    return members,{'approved_bindings':len(approved),'signals':len(model['signals']),
+                    'unmapped_signals':len(model['signals'])-len(approved),
+                    'project_source_info':project_info,'page_route':'/',
+                    'fat_signal_coverage':len([c for c in fat_inventory(model) if c.get('signal_id')])}
+
+
+def _verify_resource_safety(members:dict,signal_count:int,approved_count:int):
+    if len(members)!=5:raise NativeHold('PROJECT_RESOURCE_COUNT_INVALID')
+    views=[k for k in members if k.endswith('/view.json')]
+    if len(views)!=1:raise NativeHold('VIEW_COUNT_INVALID')
+    v=strict_loads(members[views[0]].decode('utf8'))
+    count=0;names=[]
+    def walk(c):
+        nonlocal count
+        count+=1
+        if not isinstance(c,dict) or c.get('type') not in ('ia.container.flex','ia.display.label'):
+            raise NativeHold('NON_ALLOWLISTED_COMPONENT')
+        if any(k in c for k in ('events','customMethods','scripts','onChange')):
+            raise NativeHold('ACTIVE_COMPONENT_FEATURE_PROHIBITED')
+        for binding in c.get('propConfig',{}).values():
+            if set(binding)!={'binding'} or set(binding['binding'])!={'type','config'}:
+                raise NativeHold('BINDING_FEATURE_NOT_ALLOWLISTED')
+            if binding['binding']['type']!='tag':raise NativeHold('NON_TAG_BINDING_DISALLOWED')
+            cfg=binding['binding']['config']
+            if set(cfg)!={'mode','tagPath'} or cfg['mode']!='direct' or not LAB_PATH.fullmatch(cfg['tagPath']):
+                raise NativeHold('NON_LAB_BINDING_REJECTED')
+            names.append(cfg['tagPath'])
+        for child in c.get('children',[]):walk(child)
+    walk(v['root'])
+    if count>1600 or len(names)!=approved_count or len(names)!=len(set(names)) or len(names)>signal_count:
+        raise NativeHold('COMPILER_BINDING_COUNT_OR_COMPLEXITY_MISMATCH')
+    # Sanity guard for serialized write/script tokens, even if injected in innocuous attributes.
+    serialized=json.dumps(v).lower()
+    for token in ('writeblocking','writeasync','system.opc.write','onactionperformed','"bidirectional": true',
+                  '"overlayoptout": true','"script"'):
+        if token in serialized:raise NativeHold('FORBIDDEN_RUNTIME_FEATURE: '+token)
+    return names
+
+
+def compile_lab(model,manifest,reference,template_view,reference_sha256,new_project_name,out,confirm):
+    if confirm!=CONFIRM:raise NativeHold('EXPLICIT_ISOLATED_COMPILER_CONFIRMATION_REQUIRED')
+    target=Path(out).expanduser().absolute()
+    if target.suffix.lower()!='.zip' or not target.parent.is_dir() or target.exists() or target.is_symlink():
+        raise NativeHold('NEW_ZIP_OUTPUT_REQUIRED_CREATE_ONLY')
+    reference=Path(reference).expanduser().absolute()
+    before=sha(reference)
+    members,meta=expected_members(model,manifest,reference,template_view,reference_sha256,new_project_name)
+    if before!=sha(reference):raise NativeHold('REFERENCE_CHANGED_DURING_COMPILATION')
+    _verify_resource_safety(members,meta['signals'],meta['approved_bindings'])
+    payload=_zip_blob(members)
+    fd,temp=tempfile.mkstemp(prefix='.devagent-v07-',suffix='.zip',dir=str(target.parent))
+    try:
+        with os.fdopen(fd,'wb') as f:
+            f.write(payload);f.flush();os.fsync(f.fileno())
+        if Path(temp).read_bytes()!=payload:raise NativeHold('STAGED_PROJECT_BYTES_CHANGED')
+        try:os.link(temp,target)
+        except FileExistsError:raise NativeHold('OUTPUT_ALREADY_EXISTS_AT_PUBLISH') from None
+        try:os.chmod(target,0o600)
+        except OSError:pass
+    finally:Path(temp).unlink(missing_ok=True)
+    return {'schema':SCHEMA,'status':'PASS_OFFLINE_BOUND_PROJECT_CANDIDATE_ONLY',
+            'project_zip':str(target),'project_sha256':sha(target),
+            'reference_sha256':before,'model_sha256':model_sha(model),
+            'manifest_sha256':hashlib.sha256(canonical(manifest)).hexdigest(),
+            'native_view':'GENERATED','native_page_routing':'GENERATED_UNTESTED',
+            'tag_bindings':'GENERATED_UNTESTED',**meta,
+            'project_enabled_for_isolated_test':True,
+            'unmapped_display_policy':'NOT MAPPED',
+            'runtime_import':'NOT_TESTED','gateway_fat':'NOT_EXECUTED',
+            'physical_mapping':'NOT_VERIFIED','production_release':'HOLD'}
+
+
+def verify_lab(model,manifest,reference,template_view,reference_sha256,new_project_name,candidate):
+    target=Path(candidate)
+    if not target.is_file() or target.is_symlink():raise NativeHold('CANDIDATE_NOT_SAFE_FILE')
+    members,meta=expected_members(model,manifest,Path(reference),template_view,reference_sha256,new_project_name)
+    if target.stat().st_size>4_000_000:raise NativeHold('CANDIDATE_TOO_LARGE')
+    try:
+        with zipfile.ZipFile(target) as z:
+            actual=z.infolist()
+            if len(actual)!=5 or set(z.namelist())!=set(members) or z.testzip():
+                raise NativeHold('CANDIDATE_RESOURCE_ALLOWLIST_HOLD')
+            for item in actual:
+                if item.flag_bits&1 or stat.S_IFMT((item.external_attr>>16)&0xffff)==stat.S_IFLNK:
+                    raise NativeHold('CANDIDATE_SYMLINK_OR_ENCRYPTED')
+                if z.read(item)!=members[item.filename]:raise NativeHold('CANDIDATE_REPRODUCIBILITY_MISMATCH')
+    except zipfile.BadZipFile:raise NativeHold('CANDIDATE_ZIP_INVALID') from None
+    if target.read_bytes()!=_zip_blob(members):raise NativeHold('CANDIDATE_NOT_BYTE_REPRODUCIBLE')
+    _verify_resource_safety(members,meta['signals'],meta['approved_bindings'])
+    return {'schema':SCHEMA,'status':'PASS_OFFLINE_RESOURCE_REPRODUCIBILITY_ONLY',
+            'project_sha256':sha(target),**meta,'gateway_fat':'NOT_EXECUTED',
+            'project_enabled_for_isolated_test':True,
+            'unmapped_display_policy':'NOT MAPPED',
+            'runtime_import':'NOT_TESTED','production_release':'HOLD'}
+
+
+def fat_plan(model:dict,manifest:dict) -> dict:
+    approved=validate_manifest(model,manifest)
+    inventory=fat_inventory(model)
+    per_signal={s['id']:[] for s in model['signals']}
+    for case in inventory:
+        if case.get('signal_id') in per_signal:per_signal[case['signal_id']].append(case['id'])
+    if any(len(cases)!=1 for cases in per_signal.values()):
+        raise NativeHold('FAT_INVENTORY_LACKS_EXACTLY_ONE_CASE_PER_SIGNAL')
+    cases=[]
+    for s in model['signals']:
+        cases.append({'id':per_signal[s['id']][0], 'signal_id':s['id'],
+          'equipment_id':s['asset_id'],'role':s['role'],
+          'tag_binding':'LAB_DECLARED_NOT_GATEWAY_VERIFIED' if s['id'] in approved else 'NOT_MAPPED',
+          'phases':['VALID_SOURCE_IDENTITY','OPC_READBACK','IGNITION_QUALIFIED_VALUE',
+                    'PERSPECTIVE_RENDER','GOOD_TO_BAD_QUALITY','STALE_OR_COMMS_LOSS'],
+          'result':'HOLD_NOT_EXECUTED','evidence':[], 'plc_write_allowed':False})
+    requirements=[{'id':'REQ_'+r['id'],'requirement_id':r['id'],
+                   'text':r['text'],'result':'HOLD_NOT_EXECUTED',
+                   'reason':'ACCEPTANCE_CRITERIA_AND_SIGNAL_TRACEABILITY_REQUIRE_ENGINEER_APPROVAL',
+                   'required_evidence':['APPROVED_ACCEPTANCE_CRITERIA','IGNITION_HMI_FAT','ENGINEER_SIGNOFF']}
+                  for r in model.get('requirements',[])]
+    return {'schema':'devagent.fat.v07.execution_plan.v1',
+            'model_sha256':model_sha(model),'signal_count':len(model['signals']),
+            'individual_signal_coverage':len(cases),
+            'mapping_coverage':len(approved),'requirements_count':len(model.get('requirements',[])),
+            'cases':cases,'requirement_cases':requirements,'gateway_fat':'NOT_EXECUTED','physical_mapping':'NOT_VERIFIED',
+            'production_release':'HOLD'}