devagent-ignition 0.1.0__py3-none-any.whl

devagent_spatial/contract_opc_fat.py

@@ -0,0 +1,216 @@
+"""Isolated OPC UA FAT using the customer's declared signal address contract.
+
+This is an independent, read-only protocol test, NOT physical PLC verification.
+It mirrors customer NamespaceURI + NodeId identifier + Variant datatype under a
+SEPARATE loopback server identity. No Ignition imports, endpoint switching, or
+production/PLC writes are performed. The original V076 synthetic lab remains
+available for its own protocol tests.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import re
+import sys
+
+from .model import qualify
+from .v076_opc_fat import LabHold, model_hash, scenario_value
+
+MAX_SIGNALS = 200
+TYPES = {"Boolean": bool, "Double": float, "Int32": int, "String": str}
+
+
+def _runtime_version():
+    return sys.version_info[:2]
+
+
+def require_compatible_opc_runtime():
+    """Fail closed before any socket/import on known asyncua 1.1.8 + Python 3.14 breakage.
+
+    GitHub upstream FreeOpcUa/opcua-asyncio issue #1880 documents the
+    identical ua_binary.create_type_serializer issubclass TypeError.
+    Python 3.13 is the exact version validated by the project OPC CI job.
+    Never mark skipped/incompatible protocol execution as FAT PASS.
+    """
+    if _runtime_version() >= (3, 14):
+        raise LabHold("ASYNCUA_1_1_8_PYTHON_3_14_PLUS_INCOMPATIBLE_USE_PYTHON_3_13")
+
+
+
+def _node_kind(identifier: str) -> tuple[str, str | int]:
+    """Preserve the declared identifier; never infer a namespace index."""
+    if not isinstance(identifier, str) or not identifier:
+        raise LabHold("CUSTOMER_NODE_ID_REQUIRED")
+    if identifier.startswith(("ns=", "nsu=", "g=", "b=")):
+        raise LabHold("FULL_OR_UNSUPPORTED_NODE_ID_NEEDS_ENGINEER_NORMALIZATION")
+    if identifier.startswith("i="):
+        digits = identifier[2:]
+        if not re.fullmatch(r"0|[1-9][0-9]*", digits) or int(digits) > 2**32 - 1:
+            raise LabHold("INVALID_NUMERIC_NODE_IDENTIFIER")
+        return "Numeric", int(digits)
+    if identifier.startswith("s="):
+        if not identifier[2:]:
+            raise LabHold("EMPTY_STRING_NODE_IDENTIFIER")
+        return "String", identifier[2:]
+    return "String", identifier
+
+
+def contract_manifest(model: dict) -> dict:
+    """Use exactly the signal identities from customer input, without remapping."""
+    result = qualify(model)
+    if result["status"] != "PASS_STATIC_CONTRACT_ONLY":
+        raise LabHold("CUSTOMER_ENGINEERING_CONTRACT_HOLD")
+    signals = model["signals"]
+    if not signals or len(signals) > MAX_SIGNALS:
+        raise LabHold("CONTRACT_LAB_REQUIRES_1_TO_200_SIGNALS")
+    rows = []
+    identities = set()
+    for s in signals:
+        if s["datatype"] not in TYPES or s.get("write_authorized", False) is not False:
+            raise LabHold("UNSUPPORTED_OR_WRITABLE_CUSTOMER_SIGNAL")
+        ns = s["source"]["namespace_uri"]
+        identifier = s["source"]["node_id"]
+        kind, raw_id = _node_kind(identifier)
+        pair = (ns, kind, raw_id)
+        if pair in identities:
+            raise LabHold("DUPLICATE_CUSTOMER_NODE_IDENTITY")
+        identities.add(pair)
+        rows.append({"signal_id": s["id"], "asset_id": s["asset_id"],
+                     "role": s["role"], "namespace_uri": ns,
+                     "node_id": identifier, "node_id_type": kind,
+                     "datatype": s["datatype"], "write_authorized": False})
+    return {"schema": "devagent.contract_opc_fat.v1", "model_sha256": model_hash(model),
+            "source": "CUSTOMER_DECLARED_UNVERIFIED",
+            "namespace_uris": sorted({r["namespace_uri"] for r in rows}),
+            "signals": sorted(rows, key=lambda x: x["signal_id"]),
+            "opc_server_identity": "ISOLATED_FAKE_SERVER_NOT_PHYSICAL",
+            "ignition": "NOT_VERIFIED", "production": "HOLD"}
+
+
+async def run_contract_loopback_fat(model: dict, *, port: int = 4897) -> dict:
+    """Exercise all declared nodes using an independent OPC UA TCP client.
+
+    No external endpoint is an input; intentionally impossible to contact a PLC.
+    This does not verify the original declared physical identity or simulate
+    process interlocks. Command tests remain a separate approved lab workflow.
+    """
+    if type(port) is not int or not 1024 <= port <= 65535:
+        raise LabHold("CONTRACT_LAB_PORT_INVALID")
+    manifest = contract_manifest(model)
+    require_compatible_opc_runtime()
+    try:
+        from asyncua import Client, Server, ua
+    except ImportError as exc:
+        raise LabHold("ASYNCUA_NOT_INSTALLED_PROTOCOL_FAT_NOT_EXECUTED") from exc
+
+    server = Server()
+    await server.init()
+    endpoint = "opc.tcp://127.0.0.1:%d/devagent-customer-contract-fake/" % port
+    server.set_endpoint(endpoint)
+    server.set_server_name("DevAgent CUSTOMER CONTRACT Fake OPC UA - LAB ONLY")
+    server.set_security_policy([ua.SecurityPolicyType.NoSecurity])
+    indexes = {}
+    for uri in manifest["namespace_uris"]:
+        indexes[uri] = await server.register_namespace(uri)
+    root = await server.nodes.objects.add_object(0, "DevAgentCustomerContractLAB")
+    nodes = {}
+    source_rows = {s["id"]: s for s in model["signals"]}
+    for row in manifest["signals"]:
+        kind, node_id = _node_kind(row["node_id"])
+        type_enum = getattr(ua.NodeIdType, kind)
+        ua_id = ua.NodeId(node_id, indexes[row["namespace_uri"]], type_enum)
+        dtype = getattr(ua.VariantType, row["datatype"])
+        nodes[row["signal_id"]] = await root.add_variable(
+            ua_id, row["signal_id"], ua.Variant(scenario_value(source_rows[row["signal_id"]], 0), dtype))
+        # No set_writable: clients cannot mutate a telemetry signal.
+    cases = []
+    try:
+        async with server:
+            async with Client(endpoint, timeout=4) as client:
+                ns_array = await client.get_namespace_array()
+                for row in manifest["signals"]:
+                    if row["namespace_uri"] not in ns_array:
+                        raise LabHold("CUSTOMER_NAMESPACE_URI_MISSING_IN_FAKE")
+                for phase in range(3):
+                    for row in manifest["signals"]:
+                        s = source_rows[row["signal_id"]]
+                        await nodes[row["signal_id"]].write_value(
+                            ua.Variant(scenario_value(s, phase), getattr(ua.VariantType, s["datatype"])))
+                    for row in manifest["signals"]:
+                        kind, node_id = _node_kind(row["node_id"])
+                        ns_index = ns_array.index(row["namespace_uri"])
+                        remote = client.get_node(ua.NodeId(node_id, ns_index, getattr(ua.NodeIdType, kind)))
+                        dv = await asyncio.wait_for(remote.read_data_value(raise_on_bad_status=False), timeout=3)
+                        expected = scenario_value(source_rows[row["signal_id"]], phase)
+                        actual = dv.Value.Value if dv.Value is not None else None
+                        ok = (dv.StatusCode.is_good() and dv.Value is not None
+                              and dv.Value.VariantType.name == row["datatype"]
+                              and type(actual) is TYPES[row["datatype"]]
+                              and actual == expected)
+                        cases.append({"signal_id": row["signal_id"],
+                                      "asset_id": row["asset_id"], "phase": ("BASELINE", "EXERCISE", "RESTORE")[phase],
+                                      "namespace_uri": row["namespace_uri"],
+                                      "node_id": row["node_id"], "datatype": row["datatype"],
+                                      "status": "PASS_LAB_ONLY" if ok else "FAIL"})
+                        if not ok:
+                            raise LabHold("CUSTOMER_CONTRACT_READBACK_MISMATCH")
+                # Verify a remote OPC client cannot write a telemetry node.
+                sample = manifest["signals"][0]
+                kind, node_id = _node_kind(sample["node_id"])
+                remote = client.get_node(ua.NodeId(node_id,
+                    ns_array.index(sample["namespace_uri"]), getattr(ua.NodeIdType, kind)))
+                try:
+                    await remote.write_value(scenario_value(source_rows[sample["signal_id"]], 1))
+                except ua.UaStatusCodeError:
+                    pass
+                else:
+                    raise LabHold("FAKE_TELEMETRY_CLIENT_WRITE_UNEXPECTEDLY_AUTHORIZED")
+    except LabHold:
+        raise
+    except Exception as exc:
+        raise LabHold("CUSTOMER_CONTRACT_OPC_FAT_" + type(exc).__name__.upper()) from exc
+    expected_count = 3 * len(manifest["signals"])
+    if len(cases) != expected_count or any(c["status"] != "PASS_LAB_ONLY" for c in cases):
+        raise LabHold("CUSTOMER_CONTRACT_FAT_COVERAGE_HOLD")
+    return {"schema": "devagent.contract_opc_fat.run.v1",
+            "status": "PASS_CUSTOMER_CONTRACT_FAKE_OPC_PROTOCOL_ONLY",
+            "model_sha256": manifest["model_sha256"],
+            "signals_checked": len(manifest["signals"]), "cases_checked": len(cases),
+            "cases": cases, "independent_opc_tcp_client": True,
+            "customer_nodeids_mirrored": True, "client_telemetry_writes": "DENIED",
+            "endpoint_scope": "127.0.0.1_ONLY",
+            "fake_server_identity": "NOT_CUSTOMER_SERVER",
+            "physical_node_identity": "NOT_VERIFIED",
+            "ignition_gateway": "NOT_TESTED", "perspective_hmi": "NOT_TESTED",
+            "command_fat": "NOT_EXECUTED", "production": "HOLD",
+            "recorded_utc": datetime.now(timezone.utc).isoformat()}
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Local customer-tag-contract fake OPC UA protocol FAT; NEVER production")
+    p.add_argument("--model", type=Path, required=True)
+    p.add_argument("--port", type=int, default=4897)
+    p.add_argument("--report", type=Path, required=True, help="New create-only JSON report path")
+    args = p.parse_args()
+    from .strict_json import loads as strict_loads
+    data = strict_loads(args.model.read_text(encoding="utf8"))
+    try:
+        result = asyncio.run(run_contract_loopback_fat(data, port=args.port))
+    except LabHold as exc:
+        print("FAT_STATUS=HOLD " + str(exc), file=sys.stderr)
+        print("REMEDIATION=RUN_USING_SEPARATE_PYTHON_3_13_VENV", file=sys.stderr)
+        print("PRODUCTION=HOLD", file=sys.stderr)
+        return 2
+    with args.report.open("x", encoding="utf8") as handle:
+        json.dump(result, handle, indent=2, ensure_ascii=False)
+        handle.write("\n")
+    print(result["status"])
+    print("PRODUCTION=HOLD")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devagent_spatial/contract_opc_source.py

@@ -0,0 +1,265 @@
+"""Persistent customer-tag-contract Fake OPC UA source — isolated lab only.
+
+Unlike contract_opc_fat (which closes its server after the test), this source
+remains online until Ctrl+C or a bounded duration. It does NOT verify an
+Ignition Gateway, physical PLC, safety interlocks or HMI command handling.
+Fixture values are NOT valid machine-state simulation. No telemetry writes
+from clients are permitted. Default bind is strictly 127.0.0.1.
+An exact host docker0 bridge IP requires explicit isolated-lab confirmation.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import errno
+from datetime import datetime, timezone
+import ipaddress
+import json
+import math
+import subprocess
+import sys
+from pathlib import Path
+
+from .contract_opc_fat import _node_kind, contract_manifest, require_compatible_opc_runtime, TYPES
+from .v076_opc_fat import LabHold, scenario_value
+
+LAB_DOCKER_CONFIRM = "ISOLATED_FAKE_OPCUA_DOCKER_BRIDGE_ONLY"
+LOOPBACK = "127.0.0.1"
+ENDPOINT_SUFFIX = "/devagent-customer-contract-fake/"
+
+
+def _read_docker0_ipv4() -> str:
+    """Fail closed unless docker0 reports exactly one explicit IPv4 address."""
+    try:
+        cmd = ["ip", "-j", "-4", "addr", "show", "dev", "docker0"]
+        out = subprocess.run(cmd, capture_output=True, text=True, check=True, timeout=4)
+        items = json.loads(out.stdout)
+        if type(items) is not list or len(items) != 1 or items[0].get("ifname") != "docker0":
+            raise LabHold("DOCKER0_INTERFACE_IDENTITY_UNVERIFIED")
+        ips = [x.get("local") for x in items[0].get("addr_info", [])
+               if x.get("family") == "inet" and x.get("scope") == "global"]
+        if len(ips) != 1:
+            raise LabHold("DOCKER0_INTERFACE_IPV4_AMBIGUOUS")
+        return str(ipaddress.IPv4Address(ips[0]))
+    except LabHold:
+        raise
+    except (OSError, ValueError, KeyError, TypeError, subprocess.SubprocessError) as exc:
+        raise LabHold("DOCKER0_INTERFACE_NOT_VERIFIED") from exc
+
+
+def validate_bind(host: str, *, confirm: str = "", docker_ip: str | None = None) -> str:
+    """Deny wildcard/public/listening on non-docker0 interfaces."""
+    if type(host) is not str:
+        raise LabHold("INVALID_FAKE_OPC_BIND")
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError as exc:
+        raise LabHold("INVALID_FAKE_OPC_BIND") from exc
+    if ip.version != 4 or ip.is_unspecified or ip.is_multicast:
+        raise LabHold("EXTERNAL_OR_WILDCARD_FAKE_OPC_BIND_PROHIBITED")
+    if host == LOOPBACK:
+        if confirm:
+            raise LabHold("LOOPBACK_MUST_NOT_USE_DOCKER_CONFIRM")
+        return host
+    if not ip.is_private or ip.is_loopback or ip.is_link_local:
+        raise LabHold("NONPRIVATE_FAKE_OPC_BIND_PROHIBITED")
+    if confirm != LAB_DOCKER_CONFIRM:
+        raise LabHold("DOCKER_BRIDGE_EXPLICIT_CONFIRM_REQUIRED")
+    actual = docker_ip if docker_ip is not None else _read_docker0_ipv4()
+    if actual != host:
+        raise LabHold("BIND_NOT_EXACT_DOCKER0_INTERFACE_ADDRESS")
+    return host
+
+
+def validate_settings(*, port: int, interval: float, duration: float):
+    if type(port) is not int or not 1024 <= port <= 65535:
+        raise LabHold("FAKE_OPC_SOURCE_PORT_INVALID")
+    if type(interval) not in (float, int) or not math.isfinite(interval) or not 0.1 <= interval <= 60:
+        raise LabHold("FAKE_OPC_SOURCE_INTERVAL_INVALID")
+    if type(duration) not in (float, int) or not math.isfinite(duration) or not 0 <= duration <= 86400:
+        raise LabHold("FAKE_OPC_SOURCE_DURATION_INVALID")
+
+
+async def probe_contract_source(endpoint: str, manifest: dict, signals: dict,
+                                phase: int, *, timeout: float = 12.0) -> dict:
+    """Independent real OPC UA TCP client, not server-memory introspection.
+
+    Checks the HEL/ACK/open session, customer NamespaceURI, every NodeId,
+    returned Variant datatype, Good quality and exact synthetic phase value.
+    Never substitutes TCP reachability for an OPC handshake.
+    """
+    from asyncua import Client, ua
+
+    async def read_all():
+        async with Client(endpoint, timeout=min(timeout, 5)) as client:
+            namespace_array = await client.get_namespace_array()
+            rows = manifest["signals"]
+            for row in rows:
+                if row["namespace_uri"] not in namespace_array:
+                    raise LabHold("FAKE_OPC_PROBE_NAMESPACE_MISSING")
+                kind, identifier = _node_kind(row["node_id"])
+                node = client.get_node(ua.NodeId(
+                    identifier, namespace_array.index(row["namespace_uri"]),
+                    getattr(ua.NodeIdType, kind)))
+                dv = await node.read_data_value(raise_on_bad_status=False)
+                actual = dv.Value.Value if dv.Value is not None else None
+                expected = scenario_value(signals[row["signal_id"]], phase)
+                if (not dv.StatusCode.is_good() or dv.Value is None
+                        or dv.Value.VariantType.name != row["datatype"]
+                        or type(actual) is not TYPES[row["datatype"]]
+                        or actual != expected):
+                    raise LabHold("FAKE_OPC_PROBE_READBACK_MISMATCH")
+        return {"status": "PASS_FAKE_OPC_TCP_HELLO_AND_CUSTOMER_SIGNAL_READBACK_ONLY",
+                "signals_checked": len(rows), "phase": phase}
+
+    try:
+        return await asyncio.wait_for(read_all(), timeout=timeout)
+    except LabHold:
+        raise
+    except (asyncio.TimeoutError, TimeoutError) as exc:
+        raise LabHold("FAKE_OPC_PROBE_HELLO_OR_READBACK_TIMEOUT") from exc
+    except Exception as exc:
+        raise LabHold("FAKE_OPC_PROBE_CLIENT_" + type(exc).__name__.upper()) from exc
+
+
+async def serve_contract_source(
+    model: dict, *, host: str = LOOPBACK, port: int = 4897,
+    interval: float = 3.0, duration: float = 0, confirm: str = "",
+    started: asyncio.Event | None = None, stop: asyncio.Event | None = None,
+    on_ready=None
+) -> None:
+    """A real OPC UA server exposing customer-declared nodes with lab-only data.
+
+    Positive duration is bounded for tests; zero runs until Ctrl+C or stop event.
+    Ready callback/event is dispatched only AFTER an independent OPC UA TCP
+    client successfully reads every customer-declared signal. Continued
+    liveness is checked after every fixture phase update. Any failure closes
+    the server and returns HOLD (no Ignition PASS).
+    """
+    validate_settings(port=port, interval=interval, duration=duration)
+    manifest = contract_manifest(model)
+    require_compatible_opc_runtime()
+    bind = validate_bind(host, confirm=confirm)
+    try:
+        from asyncua import Server, ua
+    except ImportError as exc:
+        raise LabHold("ASYNCUA_NOT_INSTALLED_PROTOCOL_SOURCE_NOT_STARTED") from exc
+
+    server = Server()
+    await server.init()
+    endpoint = f"opc.tcp://{bind}:{port}{ENDPOINT_SUFFIX}"
+    server.set_endpoint(endpoint)
+    server.set_server_name("DevAgent CUSTOMER CONTRACT FAKE OPC — ISOLATED TEST ONLY")
+    server.set_security_policy([ua.SecurityPolicyType.NoSecurity])
+    ns_map = {uri: await server.register_namespace(uri) for uri in manifest["namespace_uris"]}
+    root = await server.nodes.objects.add_object(0, "DevAgentCustomerContractLAB")
+    sources = {s["id"]: s for s in model["signals"]}
+    nodes = {}
+    for row in manifest["signals"]:
+        kind, identifier = _node_kind(row["node_id"])
+        nodeid = ua.NodeId(identifier, ns_map[row["namespace_uri"]],
+                           getattr(ua.NodeIdType, kind))
+        variant = ua.Variant(scenario_value(sources[row["signal_id"]], 0),
+                             getattr(ua.VariantType, row["datatype"]))
+        nodes[row["signal_id"]] = await root.add_variable(nodeid, row["signal_id"], variant)
+        # Never call set_writable. Anonymous clients may READ but not WRITE.
+
+    try:
+        async with server:
+            # CRITICAL: successful TCP bind does not imply OPC UA HEL/ACK
+            # or data availability. Fail closed before saying RUNNING.
+            await probe_contract_source(endpoint, manifest, sources, 0)
+            info = {
+                "status": "FAKE_OPC_SOURCE_RUNNING_NOT_FAT",
+                "schema": "devagent.contract_opc_source.v1",
+                "endpoint": endpoint, "source": "CUSTOMER_DECLARED_UNVERIFIED",
+                "model_sha256": manifest["model_sha256"],
+                "namespace_uris": manifest["namespace_uris"],
+                "signals": len(nodes),
+                "startup_opc_tcp_handshake": "INDEPENDENT_CLIENT_PASS_LAB_ONLY",
+                "startup_all_signals_readback": "INDEPENDENT_CLIENT_PASS_LAB_ONLY",
+                "ongoing_opc_tcp_health": "CHECKED_EACH_SYNTHETIC_PHASE",
+                "source_values": "CYCLING_TYPE_PRESERVING_FIXTURES_NOT_MACHINE_PROCESS",
+                "security": "NO_SECURITY_ISOLATED_LAB_ONLY",
+                "client_telemetry_write_authority": "NONE",
+                "real_ignition": "NOT_VERIFIED", "physical_opc_source": "NOT_VERIFIED",
+                "production": "HOLD", "utc": datetime.now(timezone.utc).isoformat(),
+            }
+            if on_ready:
+                on_ready(info)
+            if started is not None:
+                started.set()
+            loop = asyncio.get_running_loop()
+            deadline = loop.time() + duration if duration else None
+            phase = 0
+            while stop is None or not stop.is_set():
+                if deadline is not None and loop.time() >= deadline:
+                    break
+                timeout = min(interval, deadline-loop.time()) if deadline is not None else interval
+                if timeout <= 0:
+                    break
+                if stop is None:
+                    await asyncio.sleep(timeout)
+                else:
+                    try:
+                        await asyncio.wait_for(stop.wait(), timeout=timeout)
+                    except asyncio.TimeoutError:
+                        pass
+                    if stop.is_set():
+                        break
+                if deadline is not None and loop.time() >= deadline:
+                    break
+                phase = (phase + 1) % 3
+
+                async def update_fixture_values():
+                    for row in manifest["signals"]:
+                        source = sources[row["signal_id"]]
+                        await nodes[row["signal_id"]].write_value(
+                            ua.Variant(scenario_value(source, phase),
+                                       getattr(ua.VariantType, row["datatype"])))
+
+                try:
+                    await asyncio.wait_for(update_fixture_values(), timeout=8)
+                except asyncio.TimeoutError as exc:
+                    raise LabHold("FAKE_OPC_FIXTURE_UPDATE_TIMEOUT") from exc
+                # Reconnect with a new TCP client and verify all signals.
+                # A hung accept queue / silent OPC server is not healthy.
+                await probe_contract_source(endpoint, manifest, sources, phase)
+    except OSError as exc:
+        if exc.errno == errno.EADDRINUSE:
+            raise LabHold("FAKE_OPC_SOURCE_PORT_ALREADY_IN_USE_DO_NOT_START_DUPLICATE") from exc
+        raise LabHold("FAKE_OPC_SOURCE_BIND_OR_SESSION_FAILED") from exc
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Persistent fake OPC source — NOT Ignition/PLC FAT")
+    p.add_argument("--model", required=True, type=Path, help="Qualified customer model JSON")
+    p.add_argument("--port", type=int, default=4897)
+    p.add_argument("--interval", type=float, default=3.0)
+    p.add_argument("--duration", type=float, default=0, help="0 means until Ctrl+C")
+    p.add_argument("--bind", default=LOOPBACK, help="127.0.0.1 or exact host docker0 IP")
+    p.add_argument("--confirm", default="", help="Required for isolated docker0 binding")
+    args = p.parse_args()
+    from .strict_json import loads as strict_loads
+    try:
+        model = strict_loads(args.model.read_text(encoding="utf8"))
+        asyncio.run(serve_contract_source(
+            model, host=args.bind, port=args.port, interval=args.interval,
+            duration=args.duration, confirm=args.confirm,
+            on_ready=lambda data: print(json.dumps(data, sort_keys=True), flush=True)))
+    except KeyboardInterrupt:
+        print("FAKE_OPC_SOURCE_STOPPED_BY_OPERATOR", flush=True)
+        print("PRODUCTION=HOLD", flush=True)
+        return 0
+    except (LabHold, OSError, ValueError, TypeError) as exc:
+        reason = str(exc) if isinstance(exc, LabHold) else "FAKE_OPC_SOURCE_STARTUP_HOLD"
+        print("FAKE_OPC_SOURCE=HOLD " + reason, file=sys.stderr, flush=True)
+        print("PRODUCTION=HOLD", file=sys.stderr, flush=True)
+        return 2
+    print("FAKE_OPC_SOURCE_STOPPED", flush=True)
+    print("PRODUCTION=HOLD", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devagent_spatial/control_intents.py

@@ -0,0 +1,38 @@
+"""Versioned operator intent catalog; candidates are always read-only / never PLC-write capable."""
+from __future__ import annotations
+
+CATALOG_VERSION = "devagent.operator-intents.v1"
+INTENTS = {
+    "conveyor": ("START", "STOP", "RESET", "ACK"),
+    "spiral": ("START", "STOP", "RESET", "ACK"),
+    "sorter": ("START", "STOP", "RESET", "ACK"),
+    "motor": ("START", "STOP", "RESET", "ACK"),
+    "vfd": ("START", "STOP", "RESET", "ACK"),
+    "pump": ("START", "STOP", "RESET", "ACK"),
+    "valve": ("OPEN", "CLOSE", "ACK"),
+    "robot": ("START", "HOLD", "RESET", "ACK"),
+    "scanner": ("TRIGGER", "RESET", "ACK"),
+    "photoeye": (), "tank": (), "junction": (), "room": (), "other": (),
+}
+RELEASE_GATES = (
+    "command identity and source approved",
+    "per-device role and session authorization verified",
+    "permissives, interlocks and handshake independently verified",
+    "Gateway command audit and simulation/field FAT executed",
+    "engineer/customer approval and rollback plan",
+)
+
+def control_plan(model: dict) -> dict:
+    """Only control *intents* for UI review. Never a writable binding or grant."""
+    return {
+        "schema": CATALOG_VERSION,
+        "production_release": "HOLD",
+        "runtime_command_authority": "NONE",
+        "plc_opcua_writes": "DISABLED",
+        "required_gates": list(RELEASE_GATES),
+        "devices": [
+            {"asset_id": e["id"], "kind": e["kind"], "intents": list(INTENTS[e["kind"]]),
+             "enabled": False, "reason": "NO_VERIFIED_DEVICE_COMMAND_CONTRACT"}
+            for e in model["equipment"]
+        ],
+    }