devagent-ignition 0.1.0__py3-none-any.whl

devagent_spatial/operations.py

@@ -0,0 +1,284 @@
+"""Deterministic customer-mapping keyed operational KPI and alarm FAT replay.
+
+This module does NOT verify PLC identity, provide live HMI bindings, acknowledge
+real alarms or authorize writes. All resulting evidence is LAB REPLAY ONLY.
+"""
+from __future__ import annotations
+
+import copy
+import datetime as dt
+import hashlib
+import json
+import math
+from collections import Counter
+from .model import qualify
+
+MAX_FRAMES = 120
+MAX_RECORDS = 200
+MAX_AGE_SECONDS = 15
+
+
+class OperationsHold(ValueError):
+    pass
+
+
+def _date(value):
+    if not isinstance(value, str) or len(value) > 40:
+        raise OperationsHold('INVALID_SOURCE_TIMESTAMP')
+    try:
+        t = dt.datetime.fromisoformat(value.replace('Z', '+00:00'))
+    except ValueError as exc:
+        raise OperationsHold('INVALID_SOURCE_TIMESTAMP') from exc
+    if t.tzinfo is None or t.utcoffset() is None:
+        raise OperationsHold('TIMESTAMP_MUST_HAVE_TIMEZONE')
+    return t.astimezone(dt.timezone.utc)
+
+
+def mapping_digest(model):
+    """Content-addressed signal-to-asset binding contract, independent of layout."""
+    signals = model.get('signals', [])
+    rows = sorted((s['id'], s['asset_id'], s['role'], s['datatype'],
+                   s['source']['namespace_uri'], s['source']['node_id'],
+                   s.get('unit', ''), s.get('polarity', '')) for s in signals)
+    return hashlib.sha256(json.dumps(rows, ensure_ascii=False, separators=(',', ':')).encode()).hexdigest()
+
+
+def policy(model):
+    if qualify(model)['status'] != 'PASS_STATIC_CONTRACT_ONLY':
+        raise OperationsHold('INVALID_CUSTOMER_MAPPING_CONTRACT')
+    roles = Counter(s['role'] for s in model['signals'])
+    features = {
+        'equipment_running': 'run_feedback',
+        'active_faults': 'fault',
+        'photoeyes_blocked': 'photoeye_blocked',
+        'total_scans': 'scan_count',
+        'no_reads': 'no_read_count',
+        'delivered': 'delivered_count',
+        'parcels_in_transit': 'in_transit_count',
+        'last_scan_result': 'scanner_result',
+        'last_barcode': 'scanner_barcode',
+    }
+    return {
+        'schema': 'devagent.operations.policy.v1',
+        'status': 'STATIC_PROPOSAL_ONLY',
+        'mapping_digest': mapping_digest(model),
+        'signal_count': len(model['signals']),
+        'assets_count': len(model['equipment']),
+        'metrics': {key: {
+            'role': role, 'sources': roles[role],
+            'supported': roles[role] > 0,
+            'requirement': 'ALL_DECLARED_SOURCES_GOOD_AND_FRESH',
+        } for key, role in features.items()},
+        'alarm_roles': ['fault', 'photoeye_blocked'],
+        'unsupported_values': 'N/A — SOURCE NOT CONFIGURED',
+        'live_opc_verified': False,
+        'ignition_runtime_verified': False,
+    }
+
+
+def _value_ok(s, value):
+    dtype = s['datatype']
+    if dtype == 'Boolean': return type(value) is bool
+    if dtype == 'Int32': return type(value) is int and -(2**31) <= value <= (2**31-1)
+    if dtype == 'Double': return type(value) in (int, float) and math.isfinite(value)
+    if dtype == 'String': return isinstance(value, str) and len(value) <= 160
+    return False
+
+
+def _signal_state(s, obs, at):
+    if obs is None:
+        return {'signal_id': s['id'], 'asset_id': s['asset_id'], 'role': s['role'],
+                'quality': 'MISSING', 'valid': False, 'value': None, 'source_timestamp': None}
+    required = {'signal_id', 'namespace_uri', 'node_id', 'datatype', 'quality',
+                'source_timestamp', 'value'}
+    if not isinstance(obs, dict) or set(obs) != required:
+        raise OperationsHold('UNRECOGNIZED_OR_MISSING_OBSERVATION_FIELDS')
+    if (obs['signal_id'] != s['id'] or obs['namespace_uri'] != s['source']['namespace_uri'] or
+        obs['node_id'] != s['source']['node_id'] or obs['datatype'] != s['datatype']):
+        raise OperationsHold('SOURCE_IDENTITY_OR_TYPE_MISMATCH:'+s['id'])
+    if obs['quality'] not in ('GOOD', 'BAD', 'UNCERTAIN'):
+        raise OperationsHold('INVALID_OPC_QUALITY')
+    timestamp = _date(obs['source_timestamp'])
+    age = (at-timestamp).total_seconds()
+    if age < -2:
+        raise OperationsHold('SOURCE_TIMESTAMP_IN_FUTURE:'+s['id'])
+    if not _value_ok(s, obs['value']):
+        raise OperationsHold('OBSERVED_VALUE_TYPE_MISMATCH:'+s['id'])
+    quality = 'STALE' if age > MAX_AGE_SECONDS else obs['quality']
+    good = quality == 'GOOD'
+    return {'signal_id': s['id'], 'asset_id': s['asset_id'], 'role': s['role'],
+            'quality': quality, 'valid': good, 'value': obs['value'] if good else None, 'source_timestamp': obs['source_timestamp']}
+
+
+def _metric(signals, role):
+    matched = [x for x in signals if x['role'] == role]
+    if not matched: return {'value': None, 'status': 'NOT_CONFIGURED', 'sources': 0}
+    valid = [x for x in matched if x['valid']]
+    if len(valid) != len(matched):
+        return {'value': None, 'status': 'SOURCE_UNAVAILABLE', 'sources': len(matched), 'good': len(valid)}
+    if role in ('scanner_result','scanner_barcode'):
+        latest=max(matched,key=lambda x:(x['source_timestamp'] or '',x['signal_id']))
+        return {'value': latest['value'],'status':'LAB_REPLAY','sources':len(matched),'asset_id':latest['asset_id']}
+    if role in ('run_feedback', 'fault', 'photoeye_blocked'):
+        return {'value': sum(x.get('active', x['value']) is True for x in matched), 'status': 'LAB_REPLAY', 'sources': len(matched)}
+    if role in ('scan_count', 'no_read_count', 'delivered_count', 'in_transit_count'):
+        if any(x['value'] < 0 for x in matched):
+            return {'value':None,'status':'COUNTER_INVALID_NEGATIVE','sources':len(matched)}
+        if any(x.get('counter_reset') for x in matched):
+            return {'value':None,'status':'COUNTER_RESET_REVIEW','sources':len(matched)}
+        return {'value': sum(x['value'] for x in matched), 'status': 'LAB_REPLAY', 'sources': len(matched)}
+    return {'value': None, 'status': 'UNSUPPORTED_METRIC', 'sources': len(matched)}
+
+
+def _bool_active(s, state):
+    if not state['valid']: return None
+    polarity = s.get('polarity', '')
+    # Polarity is only interpreted when explicitly present in the customer contract.
+    if polarity in ('active_low', 'ACTIVE_LOW'):
+        return not state['value']
+    if polarity in ('', 'active_high', 'ACTIVE_HIGH'):
+        return bool(state['value'])
+    raise OperationsHold('UNAPPROVED_SIGNAL_POLARITY:'+s['id'])
+
+
+def evaluate(model, frames, *, origin='SYNTHETIC_OFFLINE_FIXTURE'):
+    """Fail closed on ambiguous identity; label every derived result as lab-only."""
+    operations_policy = policy(model)
+    if origin not in ('SYNTHETIC_OFFLINE_FIXTURE', 'ISOLATED_LAB_OPC_READ_ONLY'):
+        raise OperationsHold('UNSUPPORTED_REPLAY_ORIGIN')
+    if not isinstance(frames, list) or not 1 <= len(frames) <= MAX_FRAMES:
+        raise OperationsHold('INVALID_FRAME_COUNT')
+    signals = {s['id']: s for s in model['signals']}
+    if len(signals) != len(model['signals']) or len(signals) > MAX_RECORDS:
+        raise OperationsHold('INVALID_SIGNAL_INVENTORY')
+    prev_at = None
+    previous = {}
+    last_counter_values = {}
+    all_events = []
+    results = []
+    known_assets = {e['id'] for e in model['equipment']}
+    for ix, frame in enumerate(frames):
+        if not isinstance(frame, dict) or set(frame) != {'at', 'observations'}:
+            raise OperationsHold('INVALID_FRAME_SCHEMA')
+        at = _date(frame['at'])
+        if prev_at is not None and at <= prev_at:
+            raise OperationsHold('NON_MONOTONIC_FRAME_TIMESTAMPS')
+        prev_at = at
+        rows = frame['observations']
+        if not isinstance(rows, list) or len(rows) > len(signals):
+            raise OperationsHold('INVALID_OBSERVATION_COUNT')
+        seen = {}
+        for row in rows:
+            if not isinstance(row, dict) or not isinstance(row.get('signal_id'), str):
+                raise OperationsHold('INVALID_OBSERVATION')
+            sid = row['signal_id']
+            if sid not in signals: raise OperationsHold('UNDECLARED_SIGNAL:'+sid[:50])
+            if sid in seen: raise OperationsHold('DUPLICATE_SIGNAL:'+sid)
+            seen[sid] = row
+        states = [_signal_state(s, seen.get(sid), at) for sid, s in signals.items()]
+        by_id = {s['signal_id']: s for s in states}
+        for declared in model['signals']:
+            if declared['role'] in ('fault', 'photoeye_blocked') and by_id[declared['id']]['valid']:
+                by_id[declared['id']]['active'] = _bool_active(declared, by_id[declared['id']])
+        counter_events=[]
+        for declared in model['signals']:
+            sid=declared['id'];state=by_id[sid]
+            if declared['role'] not in ('scan_count','no_read_count','delivered_count','photoeye_count','in_transit_count'):
+                continue
+            if not state['valid']:continue
+            old=last_counter_values.get(sid)
+            if old is not None and state['value']<old and declared['role']!='in_transit_count':
+                state['counter_reset']=True
+                counter_events.append({'kind':'COUNTER_RESET','severity':'WARNING',
+                                       'signal_id':sid,'asset_id':declared['asset_id'],
+                                       'role':declared['role'], 'message':'Counter decreased: reset or rollover needs review',
+                                       'at':frame['at'],'source':'LAB_REPLAY'})
+            last_counter_values[sid]=state['value']
+        metrics = {name: _metric(states, role) for name, role in [
+            ('equipment_running', 'run_feedback'), ('active_faults','fault'),
+            ('photoeyes_blocked','photoeye_blocked'), ('total_scans','scan_count'),
+            ('no_reads','no_read_count'), ('delivered','delivered_count'),
+            ('parcels_in_transit','in_transit_count'), ('last_scan_result','scanner_result'),
+            ('last_barcode','scanner_barcode')]}
+        metrics['signal_health'] = {'value': sum(s['valid'] for s in states),
+                                    'total': len(states), 'status':'LAB_REPLAY'}
+        current = {}
+        frame_events = list(counter_events)
+        for s in model['signals']:
+            state = by_id[s['id']]
+            if s['role'] not in ('fault', 'photoeye_blocked', 'scanner_result'): continue
+            active = (state['valid'] and state['value'].upper()=='NO_READ') if s['role']=='scanner_result' and state['valid'] else (None if s['role']=='scanner_result' else _bool_active(s, state))
+            # Unknown must not be cleared and must not infer normal operation.
+            current[s['id']] = active
+            old = previous.get(s['id'], None)
+            if active is True and old is not True:
+                frame_events.append({'kind': 'ASSERTED', 'severity': 'CRITICAL' if s['role']=='fault' else 'WARNING',
+                                     'signal_id':s['id'],'asset_id':s['asset_id'], 'role':s['role'],
+                                     'message': ('Equipment fault' if s['role']=='fault' else 'Scanner NO_READ' if s['role']=='scanner_result' else 'Photoeye blocked'),
+                                     'at':frame['at'], 'source':'LAB_REPLAY'})
+            elif active is False and old is True:
+                frame_events.append({'kind':'CLEARED','severity':'INFO','signal_id':s['id'],
+                                     'asset_id':s['asset_id'], 'role':s['role'],
+                                     'message':'Condition cleared in replay', 'at':frame['at'],
+                                     'source':'LAB_REPLAY'})
+        # Unknown-quality transitions are surfaced separately, without creating fake equipment faults.
+        for asset in known_assets:
+            asset_states=[x for x in states if x['asset_id']==asset]
+            bad=bool(asset_states and any(not x['valid'] for x in asset_states))
+            key='QUALITY:'+asset
+            old=previous.get(key, None)
+            current[key]=bad
+            if bad and old is not True:
+                frame_events.append({'kind':'DATA_QUALITY','severity':'WARNING',
+                                     'signal_id':None,'asset_id':asset,'role':'quality',
+                                     'message':'Signal missing, stale or bad quality',
+                                     'at':frame['at'],'source':'LAB_REPLAY'})
+            elif not bad and old is True:
+                frame_events.append({'kind':'QUALITY_RECOVERED','severity':'INFO',
+                                     'signal_id':None,'asset_id':asset,'role':'quality',
+                                     'message':'Replay signal quality restored','at':frame['at'],
+                                     'source':'LAB_REPLAY'})
+        previous = current
+        all_events.extend(frame_events)
+        results.append({'at':frame['at'],'index':ix+1,'signals':states,'metrics':metrics,
+                        'new_events':frame_events,
+                        'active_alarms':[{'signal_id':s['id'],'asset_id':s['asset_id'], 'role':s['role'],
+                                         'severity':'CRITICAL' if s['role']=='fault' else 'WARNING'}
+                                         for s in model['signals'] if s['role'] in ('fault','photoeye_blocked','scanner_result')
+                                         and current.get(s['id']) is True],
+                        'quality_issues':[s['signal_id'] for s in states if not s['valid']]})
+    return {'schema':'devagent.operations.replay.v1', 'status':'LAB_REPLAY_ONLY_NOT_VERIFIED',
+            'origin':origin, 'mapping_digest': operations_policy['mapping_digest'],
+            'project_name':model['name'], 'frames': results, 'events': all_events,
+            'evidence':{'mapping_identity':'MATCHED_TO_DECLARED_CONTRACT_ONLY',
+                        'opc_source_identity':'NOT_PHYSICALLY_VERIFIED',
+                        'studio_trigger_evidence':'NOT_VERIFIED_BY_THIS_REPORT',
+                        'ignition_perspective':'NOT_EXECUTED',
+                        'plc_physical_mapping':'NOT_VERIFIED',
+                        'production':'HOLD', 'plc_writes':'DISABLED'},
+            'notification_acknowledgment':'BROWSER_SESSION_VISUAL_ONLY'}
+
+
+def make_synthetic_frames(model):
+    """Deterministic demo, not evidence of independent simulator behavior."""
+    policy(model)
+    t0=dt.datetime(2026,1,1,12,0,tzinfo=dt.timezone.utc)
+    frames=[]
+    alarm_targets=[s['id'] for s in model['signals'] if s['role'] in ('fault','photoeye_blocked','scanner_result')]
+    trigger=alarm_targets[:1]
+    for i in range(3):
+        at=(t0+dt.timedelta(seconds=i*3)).isoformat()
+        rows=[]
+        for s in model['signals']:
+            dtype=s['datatype']
+            val=False if dtype=='Boolean' else 0 if dtype=='Int32' else 0.0 if dtype=='Double' else 'GOOD_READ'
+            if s['role']=='run_feedback': val=(i!=0)
+            if s['role']=='no_read_count': val=i
+            if s['id'] in trigger and i==1:val=True
+            if s.get('polarity','').lower()=='active_low' and s['role'] in ('fault','photoeye_blocked'):
+                val=not val
+            rows.append({'signal_id':s['id'],'namespace_uri':s['source']['namespace_uri'],
+                         'node_id':s['source']['node_id'],'datatype':dtype,'quality':'GOOD',
+                         'source_timestamp':at, 'value':val})
+        frames.append({'at':at,'observations':rows})
+    return frames

devagent_spatial/operations_capture.py

@@ -0,0 +1,47 @@
+"""Read-only isolated-lab OPC UA observations, no writes or physical claim.
+
+Verified endpoint identity, source timestamps and binding to a live Ignition HMI
+require separate commissioning; this only captures OPC reads in an approved lab.
+"""
+from __future__ import annotations
+import asyncio
+import datetime as dt
+from .opc_snapshot import allow_lab_endpoint
+from .operations import OperationsHold, policy
+
+async def capture_lab(model, endpoint, samples=3):
+    policy(model)
+    allow_lab_endpoint(endpoint)
+    if not 1<=samples<=12:raise OperationsHold('UNSAFE_CAPTURE_SAMPLE_COUNT')
+    try:from asyncua import Client
+    except ImportError as exc:raise OperationsHold('ASYNCUA_OPTIONAL_DEPENDENCY_MISSING') from exc
+    async def do():
+        async with Client(endpoint, timeout=3) as client:
+            namespaces=await client.get_namespace_array()
+            for s in model['signals']:
+                if s['source']['namespace_uri'] not in namespaces:
+                    raise OperationsHold('CUSTOMER_NAMESPACE_NOT_FOUND:'+s['id'])
+            frames=[]
+            for _ in range(samples):
+                observations=[]
+                at=dt.datetime.now(dt.timezone.utc)
+                for s in model['signals']:
+                    ns=namespaces.index(s['source']['namespace_uri'])
+                    node=f'ns={ns};s={s["source"]["node_id"]}'
+                    data=await client.get_node(node).read_data_value()
+                    if data.Value is None:raise OperationsHold('MISSING_DATAVALUE:'+s['id'])
+                    variant=data.Value.VariantType.name
+                    if variant!=s['datatype']:raise OperationsHold('OBSERVED_DATATYPE_MISMATCH:'+s['id'])
+                    stamp=data.SourceTimestamp or data.ServerTimestamp
+                    if stamp is None:raise OperationsHold('OPC_TIMESTAMP_REQUIRED:'+s['id'])
+                    if stamp.tzinfo is None:stamp=stamp.replace(tzinfo=dt.timezone.utc)
+                    observations.append({'signal_id':s['id'],'namespace_uri':s['source']['namespace_uri'],
+                                         'node_id':s['source']['node_id'],'datatype':s['datatype'],
+                                         'quality':'GOOD' if data.StatusCode.is_good() else 'BAD',
+                                         'source_timestamp':stamp.isoformat(), 'value':data.Value.Value})
+                frames.append({'at':dt.datetime.now(dt.timezone.utc).isoformat(), 'observations':observations})
+                if len(frames)<samples:await asyncio.sleep(1)
+            return frames
+    try:return await asyncio.wait_for(do(),timeout=max(40,samples*35))
+    except (OSError,TimeoutError,RuntimeError,ValueError) as exc:
+        raise OperationsHold('LAB_OPC_CAPTURE_HOLD:'+type(exc).__name__) from exc

devagent_spatial/operations_lab.py

@@ -0,0 +1,64 @@
+"""Isolated-lab-only Studio namespace adapter. Original customer model immutable.
+
+This is a proposed lab alias map, NEVER a statement that physical PLC tags
+or Ignition bindings match. Requires explicit user confirmation and new directory.
+"""
+from __future__ import annotations
+import copy
+import csv
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+from pathlib import Path
+from .operations import mapping_digest, policy, OperationsHold
+
+LAB_NAMESPACE='urn:devagent:customer-tags:lab:v1'
+TYPES={'Boolean':'Boolean','Int32':'Int4','Double':'Double','String':'String'}
+
+def create_lab_derivative(model:dict,out:Path,confirm:str)->dict:
+    if confirm!='ISOLATED_TEST_ONLY':raise OperationsHold('EXPLICIT_ISOLATED_LAB_CONFIRMATION_REQUIRED')
+    policy(model)
+    destination=out.expanduser().resolve()
+    if destination.exists():raise OperationsHold('LAB_OUTPUT_ALREADY_EXISTS')
+    if not destination.parent.is_dir():raise OperationsHold('OUTPUT_PARENT_MISSING')
+    lab=copy.deepcopy(model)
+    rows=[]
+    for source,clone in zip(model['signals'],lab['signals']):
+        orig=source['source']
+        clone['source']['namespace_uri']=LAB_NAMESPACE
+        rows.append({'signal_id':source['id'],'asset_id':source['asset_id'],'role':source['role'],
+                     'customer_namespace':orig['namespace_uri'],'lab_namespace':LAB_NAMESPACE,
+                     'node_id':orig['node_id'],'datatype':source['datatype'],
+                     'status':'PROPOSED_LAB_ALIAS_NOT_PHYSICAL_MAPPING'})
+    policy(lab)
+    temp=Path(tempfile.mkdtemp(prefix='.ops-lab-',dir=str(destination.parent)))
+    try:
+        (temp/'customer-original.json').write_text(json.dumps(model,indent=2,ensure_ascii=False)+'\n')
+        (temp/'lab-model.json').write_text(json.dumps(lab,indent=2,ensure_ascii=False)+'\n')
+        with (temp/'studio-tags.csv').open('x',newline='',encoding='utf8') as f:
+            writer=csv.writer(f);writer.writerow(['TagPath','DataType','InitialValue'])
+            for s in lab['signals']:
+                writer.writerow([s['source']['node_id'],TYPES[s['datatype']],
+                                 'false' if s['datatype']=='Boolean' else '0' if s['datatype']!='String' else ''])
+        evidence={'schema':'devagent.operations.lab-alias.v1','status':'PROPOSED_LAB_NAMESPACE_TRANSLATION_ONLY',
+                  'customer_digest':mapping_digest(model),'lab_digest':mapping_digest(lab),
+                  'customer_identity':'NOT_LIVE_VERIFIED','physical_plc':'NOT_VERIFIED',
+                  'ignition_hmi':'NOT_VERIFIED','lab_namespace':LAB_NAMESPACE,'alias_rows':rows}
+        (temp/'alias-review.json').write_text(json.dumps(evidence,indent=2)+'\n')
+        files=sorted(p for p in temp.iterdir() if p.is_file())
+        (temp/'SHA256SUMS.txt').write_text(''.join(f'{hashlib.sha256(f.read_bytes()).hexdigest()}  {f.name}\n' for f in files))
+        # Do not overwrite anything. Concurrent publishing also must be create-only.
+        if destination.exists():raise OperationsHold('LAB_OUTPUT_CREATED_CONCURRENTLY')
+        libc=__import__('ctypes').CDLL(None,use_errno=True)
+        rename=getattr(libc,'renameat2',None)
+        if rename is None:raise OperationsHold('ATOMIC_CREATE_ONLY_UNAVAILABLE')
+        rename.argtypes=[__import__('ctypes').c_int,__import__('ctypes').c_char_p,__import__('ctypes').c_int,__import__('ctypes').c_char_p,__import__('ctypes').c_uint]
+        if rename(-100,os.fsencode(temp),-100,os.fsencode(destination),1)!=0:
+            raise OperationsHold('ATOMIC_PUBLISH_HOLD')
+    finally:
+        if temp.exists():shutil.rmtree(temp)
+    return {'status':'PROPOSED_LAB_ALIAS_NOT_VERIFIED', 'path':str(destination),
+            'customer_mapping_digest':evidence['customer_digest'], 'lab_mapping_digest':evidence['lab_digest'],
+            'signals':len(rows),'node_ids_preserved':True,'customer_model':'UNCHANGED'}

devagent_spatial/original_r9.py

@@ -0,0 +1,169 @@
+"""V0.8.2: snapshot-pinned isolated R9 concept viewer and deterministic virtual lab.
+
+This is NOT an Ignition R9 R5 export or a physical device source. All copied
+original R9 web/model and simulation files are immutable and served read-only.
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import json
+import re
+import secrets
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parent.parent
+SOURCE = ROOT / 'reference' / 'r9-original'
+SNAPSHOT_MANIFEST_SHA256 = 'c1712712ab5e35f913b27f906e23deca2cbaba9b8737d705975a648a4b49592c'
+SPIRAL_IDS = tuple(f'R9_SPIRAL_{i:02d}' for i in range(1, 5))
+
+class OriginalR9Hold(ValueError):
+    pass
+
+
+def verify_source() -> dict[str, str]:
+    manifest = SOURCE / 'SNAPSHOT_SHA256SUMS.txt'
+    if (not manifest.is_file() or manifest.is_symlink() or
+            hashlib.sha256(manifest.read_bytes()).hexdigest() != SNAPSHOT_MANIFEST_SHA256):
+        raise OriginalR9Hold('R9_SNAPSHOT_MANIFEST_HASH_MISMATCH')
+    verified = {}
+    for line in manifest.read_text(encoding='utf-8').splitlines():
+        if not re.fullmatch(r'[0-9a-f]{64}  [A-Za-z0-9_./-]+', line):
+            raise OriginalR9Hold('R9_SNAPSHOT_MANIFEST_FORMAT_INVALID')
+        sha, rel = line.split('  ', 1)
+        file = (SOURCE / rel).resolve()
+        if (not file.is_relative_to(SOURCE.resolve()) or not file.is_file()
+                or file.is_symlink() or rel in verified or
+                hashlib.sha256(file.read_bytes()).hexdigest() != sha):
+            raise OriginalR9Hold('R9_SNAPSHOT_SOURCE_MISMATCH')
+        verified[rel] = sha
+    needed = {'web/index.html','web/app.mjs','web/model.mjs',
+              'web/state_adapter.mjs','web/lab_panel.mjs','web/styles.css',
+              'web/vendor/three.module.js','web/vendor/three.core.js',
+              'web/vendor/addons/controls/OrbitControls.js','flow_routes.json',
+              'flow_sim.py','lab_control.py'}
+    if not needed <= verified.keys():
+        raise OriginalR9Hold('R9_SNAPSHOT_INCOMPLETE')
+    routes = json.loads((SOURCE/'flow_routes.json').read_text(encoding='utf-8'))
+    ids = set(routes['ids'])
+    if not set(SPIRAL_IDS) <= ids or len(routes['routes']) < 11:
+        raise OriginalR9Hold('R9_FOUR_SPIRAL_TOPOLOGY_INVALID')
+    model = (SOURCE/'web/model.mjs').read_text(encoding='utf-8')
+    if 'export const FLOORS={1:' not in model or '2:' not in model or '3:' not in model:
+        raise OriginalR9Hold('R9_THREE_FLOOR_MODEL_INVALID')
+    return verified
+
+
+def _module(name: str, filename: str):
+    spec = importlib.util.spec_from_file_location(name, SOURCE / filename)
+    if spec is None or spec.loader is None:
+        raise OriginalR9Hold('R9_MODEL_UNAVAILABLE')
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception:
+        sys.modules.pop(name, None)
+        raise
+    return module
+
+
+class OriginalR9Demo:
+    """Isolated model-backed in-memory simulation, no external connection."""
+    def __init__(self) -> None:
+        verify_source()
+        self._controller_mod = _module('_devagent_v082_r9_controller', 'lab_control.py')
+        self._flow_mod = _module('_devagent_v082_r9_flow', 'flow_sim.py')
+        self._lock = threading.RLock()
+        self._controller = self._controller_mod.LabController()
+        self._flow = self._flow_mod.ParcelFlow()
+        self._last_step = time.monotonic()
+        self._tick()
+
+    def _tick(self) -> None:
+        now = time.monotonic()
+        elapsed = min(0.5, max(0., now - self._last_step))
+        self._last_step = now
+        state = self._controller.snapshot()
+        sensors = self._flow.step(state['run_state'], state['wave'], elapsed)
+        self._controller.update_sensors(sensors)
+
+    def snapshot(self) -> dict[str, Any]:
+        with self._lock:
+            self._tick()
+            return {'enabled': True, 'source':'R9_SNAPSHOT_ISOLATED_SIMULATOR',
+                    'native_ignition_verified':False, 'opcua_connected':False,
+                    **self._controller.snapshot()}
+
+    def command(self, command: str, request_id: str) -> dict[str, Any]:
+        if not isinstance(command,str) or not isinstance(request_id,str) or not re.fullmatch(r'[A-Za-z0-9_-]{8,80}',request_id):
+            raise ValueError('R9_INVALID_COMMAND')
+        with self._lock:
+            try:
+                self._controller.command(command, request_id)
+            except self._controller_mod.CommandConflict as exc:
+                raise ValueError('R9_SIMULATOR_COMMAND_CONFLICT') from exc
+            self._tick()
+            return {'accepted':True, **self.snapshot()}
+
+    def reset(self) -> dict[str, Any]:
+        with self._lock:
+            self._controller=self._controller_mod.LabController()
+            self._flow=self._flow_mod.ParcelFlow()
+            self._last_step=time.monotonic()
+            return self.snapshot()
+
+    def info(self) -> dict[str, Any]:
+        return {'status':'SOURCE_BACKED_CONCEPT_ONLY','floors':[1,2,3],
+                'spiral_ids':list(SPIRAL_IDS),
+                'source_files':len(verify_source()),
+                'native_ignition_verified':False, 'plc_mappings_verified':False,
+                'simulation':'ISOLATED_IN_MEMORY_NO_OPCUA_OR_PLC',
+                'original_release_manifest':'PARTIAL_MISMATCH_INDEX_AND_MISSING_VENDOR_README',
+                'production':'HOLD'}
+
+
+# Render the stored R9 source with scoped URL prefixes and the Creator-only
+# fail-closed diagnostics overlay. Source bytes remain immutable; response
+# adaptations exist only in memory.
+# This prevents cross-talk with Creator/V8 and prevents V1C live bridge access.
+_URLS = {
+    'index.html': {
+      '/styles.css':'/original-r9/styles.css',
+      '/vendor/':'/original-r9/vendor/',
+      '/app.mjs':'/original-r9/app.mjs',
+      '/api/engine/status':'/api/original-r9/engine/status',
+      '/lab_panel.mjs':'/original-r9/lab_panel.mjs',
+      '</body>':'<script type="module" src="/assets/creator_r9_diagnostics.mjs"></script>\n</body>',
+    },
+    'lab_panel.mjs': {
+      '/api/lab/state':'/api/original-r9/lab/state',
+      '/api/lab/session':'/api/original-r9/lab/session',
+      '/api/lab/command':'/api/original-r9/lab/command',
+    },
+    'app.mjs': {'/api/bridge/facility/state':'/api/original-r9/bridge/facility/state'},
+}
+
+
+def web_response(relative: str) -> tuple[bytes, str]:
+    """Allowlist only R9 HTML, CSS, JS, vendor modules; no source traversal."""
+    verify_source()
+    allowed={'index.html','styles.css','app.mjs','model.mjs','state_adapter.mjs',
+             'lab_panel.mjs','vendor/three.module.js','vendor/three.core.js',
+             'vendor/addons/controls/OrbitControls.js'}
+    if relative not in allowed:
+        raise OriginalR9Hold('R9_WEB_ROUTE_NOT_ALLOWED')
+    content=(SOURCE/'web'/relative).read_bytes()
+    if relative in _URLS:
+        text=content.decode('utf-8')
+        for old,new in _URLS[relative].items():
+            if old not in text:
+                raise OriginalR9Hold('R9_URL_REWRITE_ANCHOR_MISSING')
+            text=text.replace(old,new)
+        content=text.encode('utf-8')
+    mime='text/html; charset=utf-8' if relative.endswith('.html') else ('text/css; charset=utf-8' if relative.endswith('.css') else 'text/javascript; charset=utf-8')
+    return content,mime

devagent_spatial/original_v8.py

@@ -0,0 +1,81 @@
+"""Pinned adapter for the unmodified Distribution Operations V8 demo source.
+
+The reference tree is executed in place so its topology and synthetic state
+semantics stay source-backed.  This adapter adds only integrity verification
+and synchronization for the Creator's localhost HTTP server.
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import threading
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parent.parent
+SOURCE = ROOT / "reference" / "v8-original"
+
+
+class OriginalV8Hold(ValueError):
+    """The pinned V8 source is missing, changed, or received an invalid action."""
+
+
+def verify_source() -> dict[str, str]:
+    """Verify every file from the original release manifest before execution."""
+    manifest = SOURCE / "SHA256SUMS.txt"
+    if not manifest.is_file():
+        raise OriginalV8Hold("ORIGINAL_V8_MANIFEST_MISSING")
+    verified: dict[str, str] = {}
+    try:
+        lines = manifest.read_text(encoding="utf8").splitlines()
+        for line in lines:
+            digest, rel = line.split("  ", 1)
+            path = (SOURCE / rel).resolve()
+            if not path.is_relative_to(SOURCE.resolve()) or not path.is_file() or path.is_symlink():
+                raise OriginalV8Hold("ORIGINAL_V8_SOURCE_MISSING")
+            actual = hashlib.sha256(path.read_bytes()).hexdigest()
+            if actual != digest:
+                raise OriginalV8Hold("ORIGINAL_V8_SOURCE_HASH_MISMATCH")
+            verified[rel] = digest
+    except (OSError, UnicodeError, ValueError) as exc:
+        if isinstance(exc, OriginalV8Hold):
+            raise
+        raise OriginalV8Hold("ORIGINAL_V8_MANIFEST_INVALID") from exc
+    if not {"model.py", "topology.json", "web/index.html", "web/app.js", "web/style.css"} <= verified.keys():
+        raise OriginalV8Hold("ORIGINAL_V8_SOURCE_INCOMPLETE")
+    return verified
+
+
+def _load_model() -> ModuleType:
+    verify_source()
+    spec = importlib.util.spec_from_file_location("_devagent_pinned_original_v8_model", SOURCE / "model.py")
+    if spec is None or spec.loader is None:
+        raise OriginalV8Hold("ORIGINAL_V8_MODEL_UNAVAILABLE")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class OriginalV8Demo:
+    """Independent in-memory simulator used only by the original V8 demo."""
+
+    def __init__(self) -> None:
+        self._model = _load_model()
+        self._lock = threading.Lock()
+        self._state = self._model.new_state()
+
+    def snapshot(self) -> dict[str, Any]:
+        with self._lock:
+            return self._model.view_state(self._state)
+
+    def transition(self, payload: Any) -> dict[str, Any]:
+        with self._lock:
+            self._state = self._model.transition(self._state, payload)
+            return self._model.view_state(self._state)
+
+    def reset(self) -> dict[str, Any]:
+        with self._lock:
+            self._state = self._model.new_state()
+            return self._model.view_state(self._state)