@h2loop/autosar 1.0.1 → 1.2.0

package/python/ecuc_engine/verify_rte.py

@@ -0,0 +1,445 @@
+"""Verify Rte_* calls in C against the SW-C's expected RTE API (rte_api), per runnable.
+
+Each call (found with the audit's call scanner) is mapped to its enclosing function, then to every runnable whose
+entry point (the RUNNABLE-ENTITY SYMBOL) reaches that function through the local call graph, and classified:
+  OK           the runnable has the access point for the API
+  NOT-ALLOWED  the API exists for the SW-C (port/element/IRV/... declared) but this runnable has no access point
+  INVENTED     no such API for the SW-C (unknown port, element, runnable, wrong direction/semantics, ...)
+For NOT-ALLOWED and INVENTED it proposes the exact ARXML change as arxml_edit ops (checked with a dry run).
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from typing import Optional
+
+from . import paths
+from .csrc import CIndex
+from .rte_api import (COLLECTION, PER_RUNNABLE, ApiEntry, ArIndex, SwcModel, build_all, find_swc, needed_role,
+                      split_name)
+
+PROVIDE_KINDS = {"Write", "Send", "Invalidate", "Feedback", "IWrite", "IWriteRef", "IInvalidate", "Switch", "SwitchAck",
+                 "Trigger"}
+REQUIRE_KINDS = {"Read", "Receive", "DRead", "IsUpdated", "IRead", "IReadRef", "IStatus", "Call", "Result", "Prm", "Mode"}
+SR_KINDS = {"Write", "Send", "Invalidate", "Feedback", "IWrite", "IWriteRef", "IInvalidate", "Read", "Receive", "DRead",
+            "IsUpdated", "IRead", "IReadRef", "IStatus"}
+KIND_ROLE = {"Write": "dataSendPoint", "Send": "dataSendPoint", "Read": "dataReceivePointByArgument",
+             "Receive": "dataReceivePointByArgument", "DRead": "dataReceivePointByValue", "IRead": "dataReadAccess",
+             "IReadRef": "dataReadAccess", "IWrite": "dataWriteAccess", "IWriteRef": "dataWriteAccess",
+             "Call": "serverCallPoint", "Mode": "modeAccessPoint", "Switch": "modeSwitchPoint", "Prm": "parameterAccess",
+             "IrvRead": "readLocalVariable", "IrvIRead": "readLocalVariable", "IrvIReadRef": "readLocalVariable",
+             "IrvWrite": "writtenLocalVariable", "IrvIWrite": "writtenLocalVariable",
+             "IrvIWriteRef": "writtenLocalVariable"}
+PREFIX = {"dataSendPoint": "SEND", "dataReceivePointByArgument": "REC", "dataReceivePointByValue": "RBV",
+          "dataReadAccess": "IREAD", "dataWriteAccess": "IWRITE", "serverCallPoint": "SCP",
+          "modeAccessPoint": "MAP", "modeSwitchPoint": "MSP", "parameterAccess": "PA", "readLocalVariable": "IRVR",
+          "writtenLocalVariable": "IRVW"}
+# Not SW-C APIs: RTE lifecycle / BSW-facing / callbacks (SWS_RTE 5.8, 5.9) — left to the integration code
+LIFECYCLE = re.compile(r"^Rte_(Start|Stop|Init|StartTiming|PartitionTerminated|PartitionRestarting|RestartPartition|"
+                       r"COMCbk|ComCbk|SetMetaDataItem|GetMetaDataItem|GetMetaDataLength|MainFunction|"
+                       r"ComDataMainFunction|Ports|NPorts|Port)\w*$")
+
+
+# ---------------------------------------------------------------- git helpers
+def changed_lines(root: str, ref: str) -> tuple:
+    """{abs file: set(lines) | None (=whole file)} of C changes in the work tree since ``ref``; error text."""
+    try:
+        r = subprocess.run(["git", "-C", root, "diff", "-U0", "--no-color", "--no-ext-diff", ref, "--"],
+                           capture_output=True, text=True, timeout=120)
+    except (OSError, subprocess.TimeoutExpired) as e:
+        return {}, f"git diff failed: {e}"
+    if r.returncode != 0:
+        return {}, f"git diff {ref} failed: {r.stderr.strip()[:300]}"
+    top = subprocess.run(["git", "-C", root, "rev-parse", "--show-toplevel"], capture_output=True, text=True).stdout.strip() or root
+    out: dict = {}
+    cur = None
+    for ln in r.stdout.splitlines():
+        if ln.startswith("+++ "):
+            p = ln[4:].strip()
+            cur = None if p == "/dev/null" else os.path.join(top, p[2:] if p.startswith("b/") else p)
+            if cur and paths.is_c(cur):
+                out.setdefault(cur, set())
+            else:
+                cur = None
+        elif ln.startswith("@@") and cur:
+            m = re.search(r"\+(\d+)(?:,(\d+))?", ln)
+            if m:
+                a, n = int(m.group(1)), int(m.group(2) or 1)
+                out[cur].update(range(a, a + n))
+    u = subprocess.run(["git", "-C", root, "ls-files", "--others", "--exclude-standard"], capture_output=True, text=True)
+    for p in u.stdout.splitlines():
+        if paths.is_c(p):
+            out[os.path.join(root, p)] = None
+    return out, None
+
+
+# ---------------------------------------------------------------- suggestions
+class Suggest:
+    def __init__(self, ix: ArIndex, models: list):
+        self.ix, self.models = ix, models
+
+    def _type_ref(self, element: Optional[str]) -> tuple:
+        """A type for a new data element: the type of a same-named element elsewhere, else the platform uint8."""
+        if element:
+            for n in self.ix.of_tag("VARIABLE-DATA-PROTOTYPE", "PARAMETER-DATA-PROTOTYPE"):
+                if n.short_name == element and n.child_text("TYPE-TREF"):
+                    return n.child_text("TYPE-TREF"), False
+        for n in self.ix.of_tag("IMPLEMENTATION-DATA-TYPE"):
+            if n.short_name == "uint8":
+                return self.ix.path(n), True
+        idts = self.ix.of_tag("IMPLEMENTATION-DATA-TYPE")
+        return (self.ix.path(idts[0]) if idts else "/AUTOSAR_Platform/ImplementationDataTypes/uint8"), True
+
+    def _unique(self, parent: str, base: str) -> str:
+        name, i = base, 2
+        while self.ix.get(f"{parent}/{name}") is not None:
+            name, i = f"{base}_{i}", i + 1
+        return name
+
+    def access_op(self, m: SwcModel, runnable: str, role: str, port_path: Optional[str], target: str,
+                  port_name: str = "", element: str = "") -> dict:
+        r = m.runnable(runnable)
+        coll = COLLECTION.get(role)
+        if role in ("readLocalVariable", "writtenLocalVariable"):
+            values = {"ACCESSED-VARIABLE": {"LOCAL-VARIABLE-REF": "->" + target}}
+            tag = "VARIABLE-ACCESS"
+        elif role == "serverCallPoint":
+            tag, values = "SYNCHRONOUS-SERVER-CALL-POINT", {"OPERATION-IREF": {"CONTEXT-R-PORT-REF": "->" + port_path,
+                                                                               "TARGET-REQUIRED-OPERATION-REF": "->" + target}}
+        elif role == "modeAccessPoint":
+            prov = any(p["path"] == port_path and p["direction"] == "P" for p in m.ports)
+            side = "P" if prov else "R"
+            tag, values = "MODE-ACCESS-POINT", {"MODE-GROUP-IREF": {f"{side}-MODE-GROUP-IN-ATOMIC-SWC-INSTANCE-REF": {
+                f"CONTEXT-{side}-PORT-REF": "->" + port_path, "TARGET-MODE-GROUP-REF": "->" + target}}}
+        elif role == "modeSwitchPoint":
+            tag, values = "MODE-SWITCH-POINT", {"MODE-GROUP-IREF": {"CONTEXT-P-PORT-REF": "->" + port_path,
+                                                                    "TARGET-MODE-GROUP-REF": "->" + target}}
+        elif role == "parameterAccess":
+            tag = "PARAMETER-ACCESS"
+            values = {"ACCESSED-PARAMETER": ({"AUTOSAR-PARAMETER-IREF": {"PORT-PROTOTYPE-REF": "->" + port_path,
+                                                                         "TARGET-DATA-PROTOTYPE-REF": "->" + target}}
+                                             if port_path else {"LOCAL-PARAMETER-REF": "->" + target})}
+        else:
+            tag, values = "VARIABLE-ACCESS", {"ACCESSED-VARIABLE": {"AUTOSAR-VARIABLE-IREF": {
+                "PORT-PROTOTYPE-REF": "->" + port_path, "TARGET-DATA-PROTOTYPE-REF": "->" + target}}}
+        op = {"op": "add", "parent_path": r.path, "element": tag, "collection": coll, "values": values}
+        if tag != "MODE-ACCESS-POINT":  # ModeAccessPoint is not identifiable
+            base = "_".join(x for x in (PREFIX.get(role, "AP"), port_name, element or target.rsplit("/", 1)[-1]) if x)
+            op["short_name"] = self._unique(r.path, base)
+        return op
+
+    def for_entry(self, m: SwcModel, e: ApiEntry, runnable: str) -> tuple:
+        role = needed_role(e)
+        if e.api in ("Enter", "Exit"):
+            r = m.runnable(runnable)
+            return [{"op": "add", "parent_path": r.path, "element": "CAN-ENTER-EXCLUSIVE-AREA-REF",
+                     "collection": "CAN-ENTER-EXCLUSIVE-AREA-REFS", "values": "->" + e.target}], None
+        if role not in COLLECTION:
+            return [], f"add a {role} for {e.target} to runnable {runnable}"
+        hint = None
+        if e.runnable and e.runnable != runnable:  # Rte_IWrite_<other re>_...: per-runnable APIs name the caller
+            fixed = e.name.replace(f"_{e.runnable}_", f"_{runnable}_", 1)
+            hint = f"{e.name} belongs to runnable {e.runnable}; from {runnable} call {fixed} (after adding the access point)"
+        return [self.access_op(m, runnable, role, e.port_path, e.target, e.port or "", e.element or "")], hint
+
+    def interfaces_with(self, kind: str, element: str) -> list:
+        tag, coll = {"sr": ("SENDER-RECEIVER-INTERFACE", "DATA-ELEMENTS"), "cs": ("CLIENT-SERVER-INTERFACE", "OPERATIONS"),
+                     "mode": ("MODE-SWITCH-INTERFACE", "MODE-GROUP"), "prm": ("PARAMETER-INTERFACE", "PARAMETERS")}[kind]
+        out = []
+        for itf in self.ix.of_tag(tag):
+            holder = itf.child(coll)
+            kids = (holder.children if holder is not None and holder.tag == coll and coll != "MODE-GROUP"
+                    else [holder] if holder is not None else [])
+            if any(k.short_name == element for k in kids):
+                out.append(self.ix.path(itf))
+        return out
+
+    def users_of(self, itf: str) -> list:
+        return sorted({f"{m.name}.{p['name']}" for m in self.models for p in m.ports if p["interface"] == itf})
+
+    def for_invented(self, m: SwcModel, name: str, runnable: Optional[str]) -> tuple:
+        """-> (ops, hint). ops create the missing port / element / IRV and the access point."""
+        kind, rest = split_name(name)
+        if kind is None:
+            return [], "not an RTE API name; use one of the allowed APIs listed by autosar_build_context"
+        run = m.runnable(runnable) if runnable else None
+        if kind in PER_RUNNABLE:
+            rn = next((r.name for r in sorted(m.runnables, key=lambda r: -len(r.name)) if rest.startswith(r.name + "_")), None)
+            if rn is None:
+                return [], f"Rte_{kind} must name the calling runnable: Rte_{kind}_{run.name if run else '<re>'}_..."
+            if run is not None and rn != run.name:
+                fixed = f"Rte_{kind}_{run.name}_{rest[len(rn) + 1:]}"
+                return [], f"names runnable {rn} but is called from {run.name}; per-runnable APIs use the caller: {fixed}"
+            rest = rest[len(rn) + 1:]
+        if run is None:
+            return [], "call site is not reachable from a runnable of this SW-C; cannot place an access point"
+        if kind.startswith("Irv"):
+            if m.behavior is None:
+                return [], f"{m.name} has no SWC-INTERNAL-BEHAVIOR"
+            implicit = kind.startswith("IrvI")
+            coll = "IMPLICIT-INTER-RUNNABLE-VARIABLES" if implicit else "EXPLICIT-INTER-RUNNABLE-VARIABLES"
+            tref, assumed = self._type_ref(rest)
+            irv = f"{m.behavior}/{rest}"
+            ops = [{"op": "add", "parent_path": m.behavior, "element": "VARIABLE-DATA-PROTOTYPE", "collection": coll,
+                    "short_name": rest, "values": {"TYPE-TREF": "->" + tref}},
+                   self.access_op(m, run.name, KIND_ROLE[kind], None, irv, "", rest)]
+            return ops, ("type assumed: " + tref + "; adjust TYPE-TREF" if assumed else None)
+        if kind in ("Enter", "Exit"):
+            ea = f"{m.behavior}/{rest}"
+            return [{"op": "add", "parent_path": m.behavior, "element": "EXCLUSIVE-AREA", "collection": "EXCLUSIVE-AREAS",
+                     "short_name": rest},
+                    {"op": "add", "parent_path": run.path, "element": "CAN-ENTER-EXCLUSIVE-AREA-REF",
+                     "collection": "CAN-ENTER-EXCLUSIVE-AREA-REFS", "values": "->" + ea}], None
+        if kind in ("Pim", "CData", "IrTrigger", "Trigger", "SwitchAck", "Feedback", "Invalidate", "IInvalidate",
+                    "IsUpdated", "IStatus", "Result"):
+            return [], explain(m, name)
+        role = KIND_ROLE.get(kind)
+        ports = [p for p in m.ports if rest.startswith(p["name"] + "_")]
+        port = max(ports, key=lambda p: len(p["name"])) if ports else None
+        if port is not None:
+            el = rest[len(port["name"]) + 1:]
+            elem = next((e for e in port["elements"] if e["name"] == el), None)
+            want_dir = "P" if kind in PROVIDE_KINDS else "R"
+            if elem is not None:  # element exists: direction or semantics do not fit
+                alt = {"Write": "Read", "Read": "Write", "Send": "Receive", "Receive": "Send", "IWrite": "IRead",
+                       "IRead": "IWrite"}.get(kind)
+                if want_dir not in port["direction"]:
+                    return [], (f"port {port['name']} is a {port['direction']}-port; Rte_{kind} needs a "
+                                f"{want_dir}-port" + (f" (on this port use Rte_{alt}_{port['name']}_{el})" if alt else ""))
+                sem = elem.get("semantics")
+                if sem == "data" and kind in ("Send", "Receive"):
+                    return [], f"{el} has data semantics: use Rte_{'Write' if kind == 'Send' else 'Read'}_{port['name']}_{el}"
+                if sem == "event" and kind in ("Write", "Read", "IWrite", "IRead", "DRead"):
+                    return [], f"{el} is queued (event semantics): use Rte_{'Send' if 'Write' in kind else 'Receive'}_{port['name']}_{el}"
+                return [], explain(m, name)
+            ik = port["interfaceKind"]
+            want = "sr" if kind in SR_KINDS else "cs" if kind == "Call" else "mode" if kind in ("Mode", "Switch") else "prm"
+            have = {"SENDER-RECEIVER-INTERFACE": "sr", "NV-DATA-INTERFACE": "sr", "CLIENT-SERVER-INTERFACE": "cs",
+                    "MODE-SWITCH-INTERFACE": "mode", "PARAMETER-INTERFACE": "prm"}.get(ik)
+            if want != have or want not in ("sr", "prm"):
+                return [], f"port {port['name']} ({ik}) has no element '{el}'; Rte_{kind} needs a {want} element"
+            ops = self.new_element(port["interface"], want, el, kind)
+            target = f"{port['interface']}/{el}"
+            ops.append(self.access_op(m, run.name, role, port["path"], target, port["name"], el))
+            users = self.users_of(port["interface"])
+            hint = (f"adds element {el} to interface {port['interface']}, which is also used by: "
+                    f"{', '.join(u for u in users if not u.startswith(m.name + '.')) or 'no other port'}")
+            return ops, hint
+        # unknown port: Rte_<k>_<port>_<element>, split at the last underscore
+        if "_" not in rest:
+            return [], f"Rte_{kind}_<port>_<element> expected, got '{rest}'"
+        pname, el = rest.rsplit("_", 1)
+        want = "sr" if kind in SR_KINDS else "cs" if kind == "Call" else "mode" if kind in ("Mode", "Switch") else "prm"
+        if role is None:
+            return [], explain(m, name)
+        cands = self.interfaces_with(want, el)
+        ops = []
+        notes = []
+        if cands:
+            itf = sorted(cands, key=lambda i: (-len(self.users_of(i)), i))[0]
+            notes.append(f"reuses existing interface {itf} (has {el}; used by {', '.join(self.users_of(itf)) or 'no port'})")
+        elif want in ("sr", "prm"):
+            pkg = self.interface_package(m)
+            iname = self._unique(pkg, f"{pname}_If")
+            itf = f"{pkg}/{iname}"
+            tref, assumed = self._type_ref(el)
+            elem = self.element_values(want, el, tref, kind)
+            ops.append({"op": "add", "parent_path": pkg, "element": "SENDER-RECEIVER-INTERFACE" if want == "sr"
+                        else "PARAMETER-INTERFACE", "short_name": iname,
+                        "values": ({"IS-SERVICE": False, "DATA-ELEMENTS": {"VARIABLE-DATA-PROTOTYPE": elem}} if want == "sr"
+                                   else {"PARAMETERS": {"PARAMETER-DATA-PROTOTYPE": elem}})})
+            if assumed:
+                notes.append(f"new interface {itf}: element type assumed {tref}; adjust TYPE-TREF")
+        else:
+            return [], f"no {want} interface with element '{el}' exists; create the interface first"
+        ptag = "P-PORT-PROTOTYPE" if kind in PROVIDE_KINDS else "R-PORT-PROTOTYPE"
+        ops.append({"op": "add", "parent_path": m.path, "element": ptag, "collection": "PORTS", "short_name": pname,
+                    "values": {("PROVIDED-INTERFACE-TREF" if ptag.startswith("P") else "REQUIRED-INTERFACE-TREF"): "->" + itf}})
+        ops.append(self.access_op(m, run.name, role, f"{m.path}/{pname}", f"{itf}/{el}", pname, el))
+        notes.append(f"split '{rest}' as port '{pname}' + element '{el}'; connect the new port in the composition "
+                     "and map it to a signal if it is inter-ECU")
+        return ops, "; ".join(notes)
+
+    def element_values(self, want: str, el: str, tref: str, kind: str) -> dict:
+        v = {"SHORT-NAME": el, "TYPE-TREF": "->" + tref}
+        if kind in ("Send", "Receive"):
+            v["SW-DATA-DEF-PROPS"] = {"SW-DATA-DEF-PROPS-VARIANTS": {"SW-DATA-DEF-PROPS-CONDITIONAL": {
+                "SW-IMPL-POLICY": "QUEUED"}}}
+        return v
+
+    def new_element(self, itf: str, want: str, el: str, kind: str) -> list:
+        tref, _assumed = self._type_ref(el)
+        v = self.element_values(want, el, tref, kind)
+        sn = v.pop("SHORT-NAME")
+        return [{"op": "add", "parent_path": itf, "element": "VARIABLE-DATA-PROTOTYPE" if want == "sr"
+                 else "PARAMETER-DATA-PROTOTYPE", "collection": "DATA-ELEMENTS" if want == "sr" else "PARAMETERS",
+                 "short_name": sn, "values": v}]
+
+    def interface_package(self, m: SwcModel) -> str:
+        for p in m.ports:
+            if p.get("interface") and self.ix.get(p["interface"]) is not None:
+                return p["interface"].rsplit("/", 1)[0]
+        return m.path.rsplit("/", 1)[0]
+
+
+def explain(m: SwcModel, name: str) -> str:
+    from .rte_api import explain_unknown
+    return explain_unknown(m, name)
+
+
+# ---------------------------------------------------------------- verify
+def _swc_by_include(models: list, includes: list) -> Optional[SwcModel]:
+    inc = {os.path.basename(i).lower() for i in includes}
+    hits = [m for m in models if f"rte_{m.name}.h".lower() in inc]
+    return hits[0] if len(hits) == 1 else None
+
+
+def verify(root: str, files: Optional[list] = None, diff_against: Optional[str] = None, swc: Optional[str] = None,
+           runnable: Optional[str] = None, check_ops: bool = True, project=None) -> dict:
+    notes: list = []
+    ix = ArIndex(root)
+    models = build_all(root, ix)
+    if not models:
+        return {"error": "no SW-COMPONENT-TYPE found in the project ARXML; nothing to verify against"}
+    only = find_swc(models, swc) if swc else None
+    if swc and only is None:
+        return {"error": f"no SW-COMPONENT-TYPE {swc!r}; known: {', '.join(m.name for m in models)}"}
+    if only and runnable and only.runnable(runnable) is None:
+        return {"error": f"{only.name} has no runnable {runnable!r}; runnables: {', '.join(r.name for r in only.runnables)}"}
+    cx = CIndex(root)
+    lines_filter: dict = {}
+    if diff_against:
+        ch, err = changed_lines(root, diff_against)
+        if err:
+            return {"error": err}
+        scan = sorted(f for f in ch if f.lower().endswith(".c"))
+        lines_filter = ch
+        if not scan:
+            notes.append(f"no C changes since {diff_against}")
+    elif files:
+        scan = sorted(f for f in paths.expand(root, files, paths.is_c) if f.lower().endswith(".c"))
+        if not scan:
+            return {"error": f"paths {files} matched no .c file under {root}"}
+    else:
+        scan = [f for f in cx.cfiles if f not in cx.generated]
+    for f in scan:  # files outside the default index (explicit generated files, new files)
+        if f not in cx.src:
+            from .csrc import functions
+            fs, raw = functions(f)
+            cx.src[f] = raw
+            cx.includes[f] = re.findall(r'^\s*#\s*include\s*[<"]([^>"]+)[>"]', raw, re.M)
+            for fn in fs:
+                cx.funcs.setdefault(fn.name, []).append(fn)
+
+    # function -> [(model, runnable)] by reachability from runnable entry points
+    reach: dict = {}
+    entry: dict = {}
+    for m in models:
+        for r in m.runnables:
+            fn = cx.get(r.symbol)
+            entry[(m.name, r.name)] = fn
+            if fn is None:
+                continue
+            for g in cx.reachable(fn):
+                reach.setdefault(id(g), []).append((m, r))
+    sugg = Suggest(ix, models)
+    findings, other = [], []
+    counts = {"OK": 0, "NOT-ALLOWED": 0, "INVENTED": 0}
+    for f in scan:
+        lf = lines_filter.get(f, None) if diff_against else None
+        for fn in sorted((g for lst in cx.funcs.values() for g in lst if g.file == f), key=lambda g: g.line):
+            owners = reach.get(id(fn), [])
+            for name, line, args in fn.rte:
+                if diff_against and lf is not None and line not in lf:
+                    continue
+                cands = owners
+                if only is not None:
+                    cands = [(m, r) for m, r in owners if m is only] or ([(only, None)] if not owners else [])
+                    if not cands:
+                        continue  # reachable only from other SW-Cs
+                if runnable:
+                    cands = [(m, r) for m, r in cands if r is not None and runnable in (r.name, r.symbol)]
+                    if not cands:
+                        continue
+                if not cands:
+                    m = _swc_by_include(models, cx.includes.get(f, [])) or next(
+                        (x for x in models if name in x.apis), None)
+                    if m is None:
+                        if LIFECYCLE.match(name):
+                            other.append({"call": name, "at": f"{cx.rel(f)}:{line}", "function": fn.name,
+                                          "why": "RTE lifecycle/BSW API, not a SW-C port API"})
+                            continue
+                        if len(models) != 1:
+                            findings.append(_finding(cx, f, line, fn, name, args, None, None, "INVENTED",
+                                                     "no SW-C in the project declares this API, and the calling "
+                                                     "function belongs to no SW-C (no runnable reaches it, no "
+                                                     "Rte_<Swc>.h include)", None))
+                            counts["INVENTED"] += 1
+                            continue
+                        m = models[0]
+                    cands = [(m, None)]
+                for m, r in cands:
+                    status, e, why = m.classify(name, r.name if r else None)
+                    if r is None:
+                        why += f"; {fn.name} is not reached from any runnable of {m.name}, checked at SW-C level"
+                    d = _finding(cx, f, line, fn, name, args, m, r, status, why, e)
+                    if status != "OK" and r is not None:
+                        ops, hint = (sugg.for_entry(m, e, r.name) if e is not None else sugg.for_invented(m, name, r.name))
+                        if ops:
+                            d["arxml_edit"] = ops
+                        if hint:
+                            d["hint"] = hint
+                    elif status == "INVENTED":
+                        _ops, hint = sugg.for_invented(m, name, None)
+                        if hint:
+                            d["hint"] = hint
+                    counts[status] += 1
+                    findings.append(d)
+    if check_ops:
+        _check_ops(root, findings, project)
+    unmapped = [{"swc": k[0], "runnable": k[1], "symbol": next(r.symbol for m in models if m.name == k[0]
+                                                                 for r in m.runnables if r.name == k[1])}
+                for k, v in entry.items() if v is None and (only is None or k[0] == only.name)]
+    res = {"scanned": {"files": [cx.rel(f) for f in scan], "functions": sum(len(v) for v in cx.funcs.values()),
+                       "calls": sum(counts.values())},
+           "counts": counts, "findings": findings,
+           "swcs": [m.name for m in ([only] if only else models)]}
+    if other:
+        res["notChecked"] = other
+    if unmapped:
+        res["runnablesWithoutCode"] = unmapped
+    if notes:
+        res["notes"] = notes
+    return res
+
+
+def _finding(cx, f, line, fn, name, args, m, r, status, why, e) -> dict:
+    d = {"status": status, "call": f"{name}({', '.join(args)})", "api": name, "at": f"{cx.rel(f)}:{line}",
+         "function": fn.name, "swc": m.name if m else None, "runnable": r.name if r else None, "why": why}
+    if e is not None:
+        d["expected"] = e.signature
+        d["cite"] = e.cite
+    return d
+
+
+def _check_ops(root: str, findings: list, project=None):
+    """Dry-run each finding's ops with arxml_edit so only ready-to-run suggestions are labelled as such."""
+    todo = [d for d in findings if d.get("arxml_edit")]
+    if not todo:
+        return
+    try:
+        from .arxml_edit import arxml_edit
+        from .model import Project
+        p = project or Project(root, load_input=True)
+    except Exception as ex:  # noqa: BLE001
+        for d in todo:
+            d["opsChecked"] = f"not checked: {ex}"
+        return
+    seen: dict = {}
+    for d in todo[:50]:
+        key = repr(d["arxml_edit"])
+        if key not in seen:
+            r = arxml_edit(p, d["arxml_edit"], dry_run=True)
+            seen[key] = True if r.get("ok") else (r.get("error") or "") + (" " + "; ".join(r.get("problems", [])) if r.get("problems") else "")
+        d["opsChecked"] = seen[key]

package/python/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ecuc-engine"
-version = "1.0.1"
+version = "1.4.0-pre"
 description = "Load, read, edit in place, validate and diff AUTOSAR ECUC ARXML (Hydron AUTOSAR pack)"
 requires-python = ">=3.10"
 # The core is stdlib-only; autosar-data adds a strict schema check of every edited file.

package/skills/autosar/SKILL.md

@@ -23,18 +23,45 @@ in `Output/` is derived from it; in-house code in `Source/` calls the generated
    the param defs and patches only the changed bytes. Reading raw ARXML for context is fine; prefer `ecuc_read`.
 2. **Validate after every edit**: `ecuc_validate` (scoped with `files`/`module` if large). Fix
    every error you introduced before moving on; report pre-existing ones separately.
-3. **Cite** the AUTOSAR path, the DEFINITION-REF and file:line for every element you discuss or change.
+3. **Cite** the AUTOSAR path, the DEFINITION-REF and file:line for every element you discuss or change —
+   copied from tool output (see *Citations and numbers*), never estimated.
 4. **Generated code is an output.** Never edit `Output/` (or other generated files) to fix a
    problem — change the configuration and regenerate.
 5. Values come from the param defs (ranges, literals, multiplicity) and the SWS; when the defs do
-   not settle a question (cross-module consistency, handle IDs, timing), say so and cite the SWS
-   requirement rather than guessing.
+   not settle a question (cross-module consistency, handle IDs, timing), say so plainly. Quote the SWS
+   requirement only if you have its text from a tool result this session; otherwise describe the rule
+   without an ID — never fill the gap from memory.
+
+## Citations and numbers (always)
+- **Requirement IDs** (SWS_/SRS_/TPS_/ECUC_/RS_…): cite one only when it appears verbatim in a tool result
+  (e.g. the `spec:` line of `autosar_audit`, an H2L rule message, `autosar_spec_id_check`) or in spec text you
+  actually read this session. Before citing any other ID, run `autosar_spec_id_check ids=[…]`; cite it only if it
+  is DEFINED, and describe it with the returned text. If the check is unavailable or says NOT-FOUND /
+  MENTIONED-ONLY, describe the rule without an ID. An invented or misremembered ID is worse than none.
+- **No requirement IDs for plain value questions** ("what is X", "which file sets Y", "trace Z"): answer with the
+  value, its AUTOSAR path and file:line. Add an ID only when the user asks why/what the standard requires.
+- **file:line** must come from a tool result or a file you read: for a value use `"@at:<Param>"` (the VALUE
+  element) from `ecuc_read`/`ecuc_find`, or the `@ file:line` of a `VALUES` line from `autosar_trace` /
+  `autosar_config_lookup`; `@at` / `at` is the container. A graph `file:line` of an element not in the local
+  checkout is where the element starts: read the file to find the value line. Never estimate or offset a line.
+- **Numbers and units**: never convert bases or units in your head. Copy `"@hex:<Param>"` / `"@dec:<Param>"`
+  (and the `dec …, hex …` of VALUES lines, CAN IDs, audit `…Hex` evidence). For any other conversion or
+  arithmetic (bytes ↔ bits, ms ↔ s, address + offset), compute it with a tool or say it is not computed.
+- **Parameter semantics**: explain what a parameter means only from its param def (`ecuc_read schema=true`,
+  the def `DESC`) or spec text you read; if neither covers it, say the meaning is not in the loaded defs/specs
+  rather than inventing one.
+- **Simple look-ups get short, exact answers**: the value (with hex if integer), the AUTOSAR path, the
+  DEFINITION-REF and file:line — no spec background, no padding.
 
 ## Tool map
 | Need | Tool |
 |---|---|
 | What modules/files/defs exist | `ecuc_read` (no path) |
 | Values of a module/container | `ecuc_read path=… depth=…` |
+| All containers matching a condition / referencing X / referenced by Y | `ecuc_find` |
+| Cross-check one module against the extract, C types and memory | `ecuc_crosscheck module=…` |
+| Edit System extract / SWC / interface XML | `arxml_edit` (DEST inferred, schema-ordered, refs checked) |
+| Add a signal end to end (ECUC + extract + DBC) | `autosar_add_signal` |
 | What may be set/added here (types, ranges, literals, multiplicity) | `ecuc_read path=… schema=true`, or a def path `/AUTOSAR/EcucDefs/<Mod>/…` |
 | Change config | `ecuc_edit ops=[…]` (`dry_run` first for large edits) |
 | Check config | `ecuc_validate` |
@@ -42,14 +69,39 @@ in `Output/` is derived from it; in-house code in `Source/` calls the generated
 | Which C symbols does this config produce, who calls them / where does this symbol come from | `autosar_trace query=…` |
 | Refs in/out, children of an element in the ingested repo | `autosar_config_lookup path=…` |
 | Review C code that calls Com/NvM/Dem/PduR/RTE APIs | `autosar_audit` (first), then confirm with `autosar_trace` / `ecuc_read` |
-| Regenerate code | `autosar_generate` (configured command, asks permission) |
+| Context for implementing / changing a runnable (allowed RTE API, code, callees, config, similar code/changes) | `autosar_build_context swc=… runnable=… task=…` |
+| Check that C only calls the RTE APIs its runnable may call (OK / NOT-ALLOWED / INVENTED + ARXML fix ops) | `autosar_verify_rte` (`diff_against=<ref>` for a change) |
+| Generate BSW config code ourselves (NvM/Fee/MemIf/Dem/PduR/CanIf/Port/Dio) | `autosar_codegen`, then `autosar_codegen_diff reference_dir=Output` (see `references/codegen.md`) |
+| Regenerate code with the vendor tool | `autosar_generate` (configured command, asks permission) |
 | Compile/link | `autosar_build` |
+| Is this requirement ID real, and what does it say? | `autosar_spec_id_check ids=[…]` (needs `specDocs` / `$AUTOSAR_SPEC_DOCS`) |
 | Spec questions (SWS/TPS requirement text) | the project's ingested docs search tools |
 
+## Workflow (validation and fix tasks)
+1. `ecuc_validate` unfiltered (all rules). It is **necessary but not sufficient**.
+2. Make a todo checklist with one item per module present (Com, PduR, CanIf, EcuC, NvM/Fee/Ea, Dem, Os, Rte, …)
+   and run `ecuc_crosscheck` for each; read its NOT CHECKED notes and close those gaps by hand.
+3. `autosar_audit` for how the C code uses the configuration (handles, directions, widths, RAM blocks).
+4. Fix only with `ecuc_edit` / `arxml_edit` / `autosar_add_signal`; then `autosar_generate`, `autosar_build`, and
+   re-run `ecuc_validate` (+ `checkGenerated: true` to prove `Output/` is not stale).
+5. **Never conclude "no faults" from a single validate call**, and never finish with a failing validation: after
+   ANY edit run `ecuc_validate`; if it fails, fix it before answering.
+
 ## The loop
 `ecuc_read (schema) → ecuc_edit → ecuc_validate → autosar_generate → arxml_diff / inspect Output → autosar_build → autosar_trace (impact on Source/)`.
 Details and failure handling: `references/workflow.md`.
 
+## Implement or change a runnable (SW-C application code)
+1. `autosar_build_context swc=<Swc> runnable=<Runnable> task="<the task verbatim>"` FIRST. Section 3 lists the RTE APIs
+   the runnable is ALLOWED to call, with the exact declarations from `Rte_<Swc>.h` (SWS_RTE naming and signatures);
+   sections 4–6 hold its code, callees and the Com/NvM config behind its ports; 7–8 are fuzzy hints only.
+2. Write the code using **only** the allowed APIs and their exact signatures (value vs pointer per SWS_Rte_01017/01019).
+   Never invent an `Rte_*` name; never call an API that belongs to another runnable.
+3. `autosar_verify_rte runnable=<Runnable>` (or `diff_against=<ref>` for the whole change).
+4. On INVENTED / NOT-ALLOWED: rewrite with an allowed API; or, only when the behaviour truly needs new data, apply the
+   returned `arxml_edit` ops (access point / port / data element), run `autosar_generate`, and verify again.
+5. `autosar_build`. Never finish with a failing verify or build. Details: `references/runnable-code.md`.
+
 ## Integration review recipe (C code against the configuration)
 1. `autosar_audit` (scope with `paths` if asked about specific files). It resolves every BSW call's handle
    through the ECUC and reports raw numeric handles, unknown handles, direction mismatches, C-width vs
@@ -58,9 +110,17 @@ Details and failure handling: `references/workflow.md`.
    `autosar_trace <symbol>` for the owning I-PDU, generated symbol and other callers.
 3. Review what the audit lists as *unchecked* by hand (pointer arguments, expressions as handles), and
    look for logic issues it cannot see (wrong signal chosen although types match, missing error handling).
-4. Report: file:line, the call, the configured facts (AUTOSAR paths + values), the spec ID, the fix.
+4. Report: file:line, the call, the configured facts (AUTOSAR paths + values with their `…At` lines), the spec
+   ID exactly as the audit's `spec:` line gives it (never add others), the fix.
 
-Facts that decide common review calls:
+Facts that decide common review calls (the IDs below are checked against R25-11; still cite one only when a
+tool result this session shows it, per *Citations and numbers*):
+- A Com signal's layout must match the System extract it came from (ISignalToIPduMapping startPosition /
+  packingByteOrder, ISignal length) and an EcuC Pdu's PduLength the system I-PDU length (H2L-SYS-001/002).
+- A PduR routing path forwards one I-PDU: source and destination must stand for the same system I-PDU (or the same
+  I-SIGNAL content) — a gateway destination carrying a different I-PDU is wrong (H2L-PDUR-001).
+- NvMNvBlockLength is the NV *data* length and must equal sizeof(the RAM block object); the Fee/Ea block must hold it
+  (H2L-NVM-001, sizeof measured by compiling a probe with the project's compiler and flags).
 - **Direction lives on the I-PDU**, not the signal: a ComSignal is TX or RX through the `ComIPduDirection`
   of the ComIPdu that references it (`ComIPduSignalRef`). Sending an RX signal (or receiving a TX one)
   fails at runtime (ECUC_Com_00493, SWS_Com_00197/00198).
@@ -77,8 +137,20 @@ Facts that decide common review calls:
 - `references/symbolic-names.md` — the symbolic-name rule (TPS_ECUC_02108) that links config to generated `#define`s, handle IDs.
 - `references/config-classes.md` — pre-compile / link-time / post-build config classes, variants, post-build loadable/selectable.
 - `references/project-layout.md` — Config / Input / Output / Source / Build / SIP and `.hydron/autosar.json`.
+- `references/codegen.md` — deterministic code generation, handle-ID write-back, bindings, reading the semantic diff, MCAL hook.
+- `references/runnable-code.md` — RTE API tiers (allowed / generated / derivable), naming and signature rules, verify statuses and fixes, context sections and budget.
 - `references/workflow.md` — the edit → validate → generate → build → trace loop, diagnostics rules, and what to do when a step fails.
 
+## Impact questions
+Include, besides the trace to code: the **storage capacity** check (H2L-MEM-001, NvM/Fee/Ea vs MemAcc/Mem area) and
+**NvM stored-data compatibility** — a changed RAM block size or layout makes existing NV data unreadable unless the
+block is migrated (NvMResistantToChangedSw, NvMStaticBlockIDCheck, a new block ID or a data-version field).
+
+## MCAL questions
+Public AUTOSAR documents define the MCAL interfaces and parameter definitions; vendor-specific configuration details
+(register mapping, clock trees, pin multiplexing) live in the silicon vendor's MCAL user manuals, often under NDA. When
+the ingested docs do not cover a detail, say so and point to the vendor MCAL manual instead of guessing.
+
 ## Scoping and empty results
 - Path arguments (`ecuc_validate files`, `autosar_audit paths`, `arxml_diff a/b`, `.hydron/autosar.json`
   globs) take files, directories (recursive) or globs (`**/Com*.arxml`), relative to the project root or