new learnigns

h8536/serial_pseudocode.py

@@ -385,6 +385,17 @@ def _semantics_lines(
             " * dispatch: command_low3 = RX_FRAME(0) & 0x07"
             + (f"; observed {values}" if values else ""),
         )
+        state_split = dispatch.get("state_split") or dispatch.get("dispatcher_split")
+        if isinstance(state_split, dict):
+            initial = ", ".join(str(item) for item in state_split.get("initial_idle_commands_hex", []) if item)
+            continuation = ", ".join(str(item) for item in state_split.get("continuation_commands_hex", []) if item)
+            lines.append(
+                " * dispatcher split: FAA2 == 0 accepts initial/idle commands "
+                f"{initial or 'none'}; FAA2 != 0 accepts continuation commands {continuation or 'none'}",
+            )
+            caveat = str(state_split.get("caveat") or "").strip()
+            if caveat:
+                lines.append(f" * dispatcher caveat: {_comment_text(caveat)}")
         if opts.include_evidence:
             lines.append(f" * dispatch evidence: {_hex_join(dispatch.get('evidence_addresses_hex'))}")
 
@@ -405,6 +416,11 @@ def _semantics_lines(
             handler = command.get("handler_start_hex") or "multiple"
             responses = ", ".join(str(item) for item in command.get("response_candidates", [])) or "none"
             lines.append(f" * - {value} {name}: {summary}; handler {handler}; responses {responses}")
+            availability = _comment_text(str(command.get("availability_summary") or ""))
+            if availability:
+                lines.append(f" *   availability: {availability}")
+            for note in command.get("semantic_notes", []):
+                lines.append(f" *   note: {_comment_text(str(note))}")
     lines.extend(_command_effect_comment_lines(protocol.get("command_effects"), opts, prefix=" * "))
     lines.extend(_response_schema_comment_lines(_schema_list(protocol), opts, prefix=" * "))
     lines.extend(_table_map_comment_lines(_table_map_list(protocol), opts, prefix=" * "))
@@ -458,9 +474,51 @@ def _semantics_lines(
             "    u16 logical_index = sci1_rx_candidate_logical_index();",
             "    u16 value = sci1_rx_candidate_value();",
             "",
-            "    switch (command) {",
         ],
     )
+    lines.extend(_command_dispatch_switch_lines(commands, opts))
+    return lines
+
+
+def _command_dispatch_switch_lines(commands: list[JsonObject], opts: SerialPseudocodeOptions) -> list[str]:
+    initial = [
+        command for command in commands
+        if _command_has_availability(command, "initial_idle_dispatch")
+    ]
+    continuation = [
+        command for command in commands
+        if _command_has_availability(command, "continuation_dispatch")
+    ]
+    if not initial and not continuation:
+        return _flat_command_switch_lines(commands, opts, indent="    ") + ["}", ""]
+
+    lines = [
+        "    bool session_active = MEM8[0xFAA2u] != 0u;",
+        "",
+        "    if (!session_active) {",
+        "        /* Initial/idle dispatcher: valid checksum/no RX error, FAA2 == 0. */",
+    ]
+    lines.extend(_flat_command_switch_lines(initial, opts, indent="        "))
+    lines.extend(
+        [
+            "        return;",
+            "    }",
+            "",
+            "    /* Continuation dispatcher: FAA2 != 0. */",
+        ],
+    )
+    lines.extend(_flat_command_switch_lines(continuation, opts, indent="    "))
+    lines.extend(["}", ""])
+    return lines
+
+
+def _flat_command_switch_lines(
+    commands: list[JsonObject],
+    opts: SerialPseudocodeOptions,
+    *,
+    indent: str,
+) -> list[str]:
+    lines = [f"{indent}switch (command) {{"]
     for command in commands:
         value = command.get("command_value")
         if not isinstance(value, int):
@@ -468,28 +526,50 @@ def _semantics_lines(
         name = _safe_identifier(str(command.get("name_candidate") or f"command_{value:02X}"))
         summary = _comment_text(str(command.get("summary") or "candidate command semantics unknown"))
         evidence = _hex_join(command.get("evidence_addresses_hex"))
-        lines.append(f"    case 0x{value:02X}u:")
-        lines.append(f"        /* {name}: {summary}")
+        lines.append(f"{indent}case 0x{value:02X}u:")
+        lines.append(f"{indent}    /* {name}: {summary}")
+        availability = _comment_text(str(command.get("availability_summary") or ""))
+        if availability:
+            lines.append(f"{indent}     * availability: {availability}")
+        for note in command.get("semantic_notes", []):
+            lines.append(f"{indent}     * note: {_comment_text(str(note))}")
         for effect_line in _command_effect_switch_lines(command):
-            lines.append(f"         * {effect_line}")
+            lines.append(f"{indent}     * {effect_line}")
         if opts.include_evidence and evidence:
-            lines.append(f"         * evidence: {evidence}")
-        lines.append("         */")
-        lines.append(f"        candidate_{name}(logical_index, value);")
-        lines.append("        break;")
+            lines.append(f"{indent}     * evidence: {evidence}")
+        lines.append(f"{indent}     */")
+        if value == 0x01:
+            lines.append(f"{indent}    if ((RX_FRAME(1) & 0x80u) != 0u) {{")
+            lines.append(f"{indent}        candidate_unknown_command(command, logical_index, value);")
+            lines.append(f"{indent}        break;")
+            lines.append(f"{indent}    }}")
+        lines.append(f"{indent}    candidate_{name}(logical_index, value);")
+        lines.append(f"{indent}    break;")
     lines.extend(
         [
-            "    default:",
-            "        candidate_unknown_command(command, logical_index, value);",
-            "        break;",
-            "    }",
-            "}",
-            "",
+            f"{indent}default:",
+            f"{indent}    candidate_unknown_command(command, logical_index, value);",
+            f"{indent}    break;",
+            f"{indent}}}",
         ],
     )
     return lines
 
 
+def _command_has_availability(command: JsonObject, availability: str) -> bool:
+    value = command.get("availability")
+    if value == availability:
+        return True
+    if isinstance(value, list) and availability in value:
+        return True
+    conditions = " ".join(str(item) for item in command.get("availability_conditions", []))
+    if availability == "initial_idle_dispatch":
+        return "FAA2 == 0" in conditions
+    if availability == "continuation_dispatch":
+        return "FAA2 != 0" in conditions
+    return False
+
+
 def _command_effect_comment_lines(
     value: object,
     opts: SerialPseudocodeOptions,
@@ -528,6 +608,8 @@ def _response_schema_comment_lines(
         response_id = schema.get("response_id") or schema.get("call_address_hex") or "candidate_response"
         byte_text = _response_schema_summary(schema)
         lines.append(f"{prefix}- {response_id}: {byte_text}")
+        for note in schema.get("semantic_notes", []):
+            lines.append(f"{prefix}  note: {_comment_text(str(note))}")
         evidence = _hex_join(schema.get("evidence_addresses_hex"))
         if opts.include_evidence and evidence:
             lines.append(f"{prefix}  evidence: {evidence}")
@@ -612,6 +694,13 @@ def _retry_error_comment_lines(
         threshold = retry.get("threshold_candidate", "?")
         summary = _comment_text(str(retry.get("summary") or "candidate retry path"))
         lines.append(f"{prefix}- retry path: counter {counter}, threshold {threshold}; {summary}")
+        echo = retry.get("echo_response_candidate")
+        if isinstance(echo, dict):
+            staging = _comment_text(str(echo.get("staging_candidate") or "retry/error echo staging"))
+            caveat = _comment_text(str(echo.get("observed_frame_caveat") or ""))
+            lines.append(f"{prefix}  echo path: {echo.get('entry_label', 'loc_BE4D')}: {staging}")
+            if caveat:
+                lines.append(f"{prefix}  echo caveat: {caveat}")
     if isinstance(command_07, dict):
         summary = _comment_text(str(command_07.get("summary") or "candidate command 0x07 path"))
         lines.append(f"{prefix}- command 0x07 path: {summary}")
@@ -987,6 +1076,8 @@ def _effect_summary(effect: JsonObject) -> str:
     operation = effect.get("operation_candidate")
     table = effect.get("table_base_hex")
     state = effect.get("state_address_hex")
+    selector = effect.get("selector_without_response_hex")
+    observed = effect.get("observed_frame_caveat")
     if target:
         parts.append(f"target {target}")
     if source:
@@ -997,6 +1088,10 @@ def _effect_summary(effect: JsonObject) -> str:
         parts.append(f"table {table}")
     if state:
         parts.append(f"state {state}")
+    if selector:
+        parts.append(f"selector {selector} has no response")
+    if observed:
+        parts.append(str(observed))
     return _comment_text("; ".join(parts))