madcop 0.1.0__tar.gz

madcop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lin Ruihan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

madcop-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: madcop
+Version: 0.1.0
+Summary: madcop — the supply chain cop that goes mad for anomalies. Pluggable LangGraph framework: detect, diagnose, decide.
+Author-email: Lin Ruihan <chuiniu@me.com>
+License: MIT
+Project-URL: Homepage, https://github.com/linmy666/madcop
+Project-URL: Repository, https://github.com/linmy666/madcop
+Project-URL: Issues, https://github.com/linmy666/madcop/issues
+Keywords: supply-chain,langgraph,agent,anomaly-detection,rca,root-cause-analysis,ai-pm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Dynamic: license-file
+
+# madcop
+
+> **mad** + **cop** — the supply chain cop that goes *mad* for anomalies.
+> Pluggable LangGraph framework: from "detect" to "diagnose" to "decide", with self-evolution.
+
+[![Tests](https://img.shields.io/badge/tests-45%20passing-brightgreen)](#tests)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](#requirements)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](#license)
+[![TestPyPI](https://img.shields.io/badge/TestPyPI-v0.1.0-blue)](https://test.pypi.org/project/madcop/)
+
+## What is madcop?
+
+**madcop** is a pluggable framework that turns raw supply chain telemetry
+(orders, shipments, warehouse readings, contracts) into **decision prompts**
+with full causal chains. Where most tools stop at "alert fired", madcop walks
+the chain back to the **human decision** that made the anomaly possible.
+
+The name is short for **mad cop** — a cop that goes mad for anomalies. Not
+in a punitive sense, but in the sense of "won't let a single anomaly go
+untraced to its source."
+
+## Why?
+
+A typical supply chain alert reads:
+
+> ⚠️ Cold-chain temperature exceeded threshold at 14:30.
+
+That tells you **what** happened, not **why** it could happen. madcop answers
+the second question:
+
+> The temperature breach on SHIP-2026-0615-CG-SH traces back to a BD
+> decision (DEC-2026-03-12-N3) made three months earlier to accept the
+> supplier's "fine equals exemption" concession. That decision shaped
+> CLAUSE-04 — a **passive** clause that punishes the breach but does not
+> prevent it. The contract was signed with 冷链速运 at Q1 cost-cutting
+> pressure, and the shipment is now exposed to the same failure mode.
+
+The PM framing: an alert without a cause is a notification. An alert with a
+cause is a **decision prompt**. madcop's job is to bridge the two.
+
+## Architecture (4 layers, 1 graph)
+
+```
+┌──────────────────────────────────────────────────────┐
+│  L4  Strategy Router    — zero-code YAML policies     │
+├──────────────────────────────────────────────────────┤
+│  L3  LangGraph          — detect → diagnose → decide  │
+│                         → learn (state machine)        │
+├──────────────────────────────────────────────────────┤
+│  L2  Anomaly Engine     — rules · RCA · counterfactual│
+├──────────────────────────────────────────────────────┤
+│  L1  Unified Data Layer — OMS/TMS/WMS/BMS adapters    │
+└──────────────────────────────────────────────────────┘
+```
+
+**L1 — Unified Data Layer** (`madcop/event.py`, `madcop/adapters/`)
+A `UnifiedEvent` is the lingua franca. Every adapter implements `BaseAdapter`
+and yields events with frozen, UTC-validated, severity-rated fields.
+
+**L2 — Anomaly Engine** (`madcop/anomaly/`, `madcop/rca/`)
+5 shipped rules + a `Detector` that orchestrates them. RCA walks a typed
+property graph from any finding back to a decision.
+
+**L3 — LangGraph Orchestrator** (`madcop/graph/`) — *planned, W5*
+A typed state machine that sequences detect → diagnose → decide → learn.
+
+**L4 — Strategy Router** (`madcop/strategy/`) — *planned, W7*
+YAML policies + feedback-weighted registry. Self-evolution is real here:
+weekly reports roll up the week's findings, and policies are ranked by
+their rolling effectiveness.
+
+## What's shipped today (W1 + W2 + W3)
+
+| Layer | Component | Status |
+|-------|-----------|--------|
+| L1 | `UnifiedEvent` with UTC + severity + source/event_type validation | ✅ |
+| L1 | `BaseAdapter` contract + WMS mock (cold-chain) | ✅ |
+| L2 | `Detector` + 5 rules (cold-chain temp / sustained / OMS cancel / TMS lead / BMS score) | ✅ |
+| L2 | `KnowledgeGraph` + `trace()` + `explain()` RCA | ✅ |
+| L2 | Cold-chain seed graph (5 nodes, 4 edges) | ✅ |
+| L4 | Strategy registry, weekly report, LLM backend | 🔜 W7 |
+
+## Installation
+
+```bash
+pip install madcop
+```
+
+Or from TestPyPI (the current published version):
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ madcop
+```
+
+## Quick start
+
+```bash
+# W1: see the raw event stream
+python -m madcop run coldchain
+
+# W2: detect anomalies
+python -m madcop run anomalies
+
+# W3: detect + trace each finding to a root cause (the headline feature)
+python -m madcop run rca
+```
+
+### What `run rca` looks like
+
+```
+madcop RCA demo — 3 finding(s) on SHIP-2026-0615-CG-SH
+
+━━━ finding 1/3 ━━━
+  rule:    wms.coldchain.temperature_breach
+  summary: Cold-chain temperature -14.2°C exceeds threshold -15.0°C by 0.8°C
+  chain:   5 step(s), root cause:
+╭──────────────────────────────── root cause ────────────────────────────────╮
+│ decision DEC-2026-03-12-N3 (BD 接受乙方'罚款即免责'让步) (by BD-Lin) —       │
+│ rationale: Q1 降本压力 → shaped clause CLAUSE-04 (温控异常通知条款) PASSIVE  │
+│ ("温控异常时, 承运商应在 30 分钟内书面通知甲方, 逾期每日扣 0.5% 服务费") →   │
+│ under contract CONT-2026-0312 (冷链速运 / 2026 年度框架) → carried by        │
+│ 冷链速运 → on shipment SHIP-2026-0615-CG-SH (广州→上海, 冷链, 2026-06-15)    │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+**45 tests, all passing.** They cover the L1 contract (UTC validation, event
+type / source system consistency, adapter behavior), the L2 detector (every
+rule, plus state-machine semantics for windowed rules), and the RCA graph
+(forward/reverse traversal, empty chain, unknown subject).
+
+## Roadmap
+
+See [`ROADMAP.md`](ROADMAP.md). 8 weeks, 1 commit per week. Current: **W3
+done, ready to push**.
+
+## Requirements
+
+- Python 3.10+
+- `rich >= 13.0`
+
+## Project status
+
+Alpha. The architecture is real, the data layer is real, the anomaly rules
+are real, and the RCA traces are real. The adapters are mock data today;
+real wire integrations to OMS / TMS / WMS / BMS systems are scoped for
+later (see Roadmap).
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).
+
+## Why "madcop"?
+
+When the user asked for a name for "the agent that goes mad for anomalies",
+the obvious answer was **mad + cop**. The product is a cop that goes mad for
+anomalies — not in a punitive sense, but in the sense of "won't let a
+single anomaly go untraced to its source."
+
+## Contact
+
+Lin Ruihan · chuiniu@me.com

madcop-0.1.0/README.md

@@ -0,0 +1,168 @@
+# madcop
+
+> **mad** + **cop** — the supply chain cop that goes *mad* for anomalies.
+> Pluggable LangGraph framework: from "detect" to "diagnose" to "decide", with self-evolution.
+
+[![Tests](https://img.shields.io/badge/tests-45%20passing-brightgreen)](#tests)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](#requirements)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey)](#license)
+[![TestPyPI](https://img.shields.io/badge/TestPyPI-v0.1.0-blue)](https://test.pypi.org/project/madcop/)
+
+## What is madcop?
+
+**madcop** is a pluggable framework that turns raw supply chain telemetry
+(orders, shipments, warehouse readings, contracts) into **decision prompts**
+with full causal chains. Where most tools stop at "alert fired", madcop walks
+the chain back to the **human decision** that made the anomaly possible.
+
+The name is short for **mad cop** — a cop that goes mad for anomalies. Not
+in a punitive sense, but in the sense of "won't let a single anomaly go
+untraced to its source."
+
+## Why?
+
+A typical supply chain alert reads:
+
+> ⚠️ Cold-chain temperature exceeded threshold at 14:30.
+
+That tells you **what** happened, not **why** it could happen. madcop answers
+the second question:
+
+> The temperature breach on SHIP-2026-0615-CG-SH traces back to a BD
+> decision (DEC-2026-03-12-N3) made three months earlier to accept the
+> supplier's "fine equals exemption" concession. That decision shaped
+> CLAUSE-04 — a **passive** clause that punishes the breach but does not
+> prevent it. The contract was signed with 冷链速运 at Q1 cost-cutting
+> pressure, and the shipment is now exposed to the same failure mode.
+
+The PM framing: an alert without a cause is a notification. An alert with a
+cause is a **decision prompt**. madcop's job is to bridge the two.
+
+## Architecture (4 layers, 1 graph)
+
+```
+┌──────────────────────────────────────────────────────┐
+│  L4  Strategy Router    — zero-code YAML policies     │
+├──────────────────────────────────────────────────────┤
+│  L3  LangGraph          — detect → diagnose → decide  │
+│                         → learn (state machine)        │
+├──────────────────────────────────────────────────────┤
+│  L2  Anomaly Engine     — rules · RCA · counterfactual│
+├──────────────────────────────────────────────────────┤
+│  L1  Unified Data Layer — OMS/TMS/WMS/BMS adapters    │
+└──────────────────────────────────────────────────────┘
+```
+
+**L1 — Unified Data Layer** (`madcop/event.py`, `madcop/adapters/`)
+A `UnifiedEvent` is the lingua franca. Every adapter implements `BaseAdapter`
+and yields events with frozen, UTC-validated, severity-rated fields.
+
+**L2 — Anomaly Engine** (`madcop/anomaly/`, `madcop/rca/`)
+5 shipped rules + a `Detector` that orchestrates them. RCA walks a typed
+property graph from any finding back to a decision.
+
+**L3 — LangGraph Orchestrator** (`madcop/graph/`) — *planned, W5*
+A typed state machine that sequences detect → diagnose → decide → learn.
+
+**L4 — Strategy Router** (`madcop/strategy/`) — *planned, W7*
+YAML policies + feedback-weighted registry. Self-evolution is real here:
+weekly reports roll up the week's findings, and policies are ranked by
+their rolling effectiveness.
+
+## What's shipped today (W1 + W2 + W3)
+
+| Layer | Component | Status |
+|-------|-----------|--------|
+| L1 | `UnifiedEvent` with UTC + severity + source/event_type validation | ✅ |
+| L1 | `BaseAdapter` contract + WMS mock (cold-chain) | ✅ |
+| L2 | `Detector` + 5 rules (cold-chain temp / sustained / OMS cancel / TMS lead / BMS score) | ✅ |
+| L2 | `KnowledgeGraph` + `trace()` + `explain()` RCA | ✅ |
+| L2 | Cold-chain seed graph (5 nodes, 4 edges) | ✅ |
+| L4 | Strategy registry, weekly report, LLM backend | 🔜 W7 |
+
+## Installation
+
+```bash
+pip install madcop
+```
+
+Or from TestPyPI (the current published version):
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ madcop
+```
+
+## Quick start
+
+```bash
+# W1: see the raw event stream
+python -m madcop run coldchain
+
+# W2: detect anomalies
+python -m madcop run anomalies
+
+# W3: detect + trace each finding to a root cause (the headline feature)
+python -m madcop run rca
+```
+
+### What `run rca` looks like
+
+```
+madcop RCA demo — 3 finding(s) on SHIP-2026-0615-CG-SH
+
+━━━ finding 1/3 ━━━
+  rule:    wms.coldchain.temperature_breach
+  summary: Cold-chain temperature -14.2°C exceeds threshold -15.0°C by 0.8°C
+  chain:   5 step(s), root cause:
+╭──────────────────────────────── root cause ────────────────────────────────╮
+│ decision DEC-2026-03-12-N3 (BD 接受乙方'罚款即免责'让步) (by BD-Lin) —       │
+│ rationale: Q1 降本压力 → shaped clause CLAUSE-04 (温控异常通知条款) PASSIVE  │
+│ ("温控异常时, 承运商应在 30 分钟内书面通知甲方, 逾期每日扣 0.5% 服务费") →   │
+│ under contract CONT-2026-0312 (冷链速运 / 2026 年度框架) → carried by        │
+│ 冷链速运 → on shipment SHIP-2026-0615-CG-SH (广州→上海, 冷链, 2026-06-15)    │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+**45 tests, all passing.** They cover the L1 contract (UTC validation, event
+type / source system consistency, adapter behavior), the L2 detector (every
+rule, plus state-machine semantics for windowed rules), and the RCA graph
+(forward/reverse traversal, empty chain, unknown subject).
+
+## Roadmap
+
+See [`ROADMAP.md`](ROADMAP.md). 8 weeks, 1 commit per week. Current: **W3
+done, ready to push**.
+
+## Requirements
+
+- Python 3.10+
+- `rich >= 13.0`
+
+## Project status
+
+Alpha. The architecture is real, the data layer is real, the anomaly rules
+are real, and the RCA traces are real. The adapters are mock data today;
+real wire integrations to OMS / TMS / WMS / BMS systems are scoped for
+later (see Roadmap).
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).
+
+## Why "madcop"?
+
+When the user asked for a name for "the agent that goes mad for anomalies",
+the obvious answer was **mad + cop**. The product is a cop that goes mad for
+anomalies — not in a punitive sense, but in the sense of "won't let a
+single anomaly go untraced to its source."
+
+## Contact
+
+Lin Ruihan · chuiniu@me.com

madcop-0.1.0/madcop/__init__.py

@@ -0,0 +1,3 @@
+"""madcop: a pluggable LangGraph framework for supply chain anomaly orchestration."""
+
+__version__ = "0.1.0"

madcop-0.1.0/madcop/__main__.py

@@ -0,0 +1,123 @@
+"""madcop CLI entry point.
+
+Two demo scenarios today:
+  python -m madcop run coldchain              # W1 — print the event stream
+  python -m madcop run anomalies coldchain    # W2 — run anomaly detection
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .adapters.wms import WMSAdapter
+from .anomaly.rules import default_detector
+from .rca.graph import explain, trace
+from .rca.seed import build_coldchain_seed
+
+
+def _format_event(idx: int, total: int, ev) -> str:
+    ts = ev.parsed_timestamp.strftime("%H:%M:%S")
+    val = f"{ev.value:>6.1f}°C" if ev.value is not None else "    —  "
+    sev = "·" * ev.severity
+    return f"  [{idx:>2}/{total}] {ts}  {val}  sev{ev.severity} {sev}  {ev.attributes.get('note', '')}"
+
+
+def run_coldchain() -> int:
+    """W1 demo: print the WMS cold-chain event stream."""
+    adapter = WMSAdapter()
+    events = sorted(adapter.fetch(), key=lambda e: e.parsed_timestamp)
+    if not events:
+        print("(no events)", file=sys.stderr)
+        return 1
+    print(f"cold-chain timeline for {events[0].subject_id}")
+    print(f"  threshold: {adapter.COLD_CHAIN_THRESHOLD_C}°C")
+    print()
+    for i, ev in enumerate(events, 1):
+        print(_format_event(i, len(events), ev))
+    breaches = [e for e in events if e.value is not None and e.value > adapter.COLD_CHAIN_THRESHOLD_C]
+    print()
+    print(f"  → {len(breaches)} threshold breach(es) detected")
+    return 0
+
+
+def run_anomalies_coldchain() -> int:
+    """W2 demo: run all 5 anomaly rules on the cold-chain stream."""
+    adapter = WMSAdapter()
+    events = sorted(adapter.fetch(), key=lambda e: e.parsed_timestamp)
+    detector = default_detector()
+    findings = list(detector.run(events))
+    print(f"madcop anomaly report — subject={events[0].subject_id if events else 'N/A'}")
+    print(f"  events: {len(events)}   rules: {len(detector.rules)}   findings: {len(findings)}")
+    print()
+    if not findings:
+        print("  (no anomalies)")
+        return 0
+    for i, f in enumerate(findings, 1):
+        print(f"  [{i}/{len(findings)}] sev{f.severity}  {f.rule_id}")
+        print(f"            {f.summary}")
+    return 0
+
+
+def run_rca_coldchain() -> int:
+    """W3 demo: detect anomalies and trace each to a root-cause decision."""
+    from rich.console import Console
+    from rich.panel import Panel
+
+    console = Console()
+    events = sorted(WMSAdapter().fetch(), key=lambda e: e.parsed_timestamp)
+    findings = list(default_detector().run(events))
+    g = build_coldchain_seed()
+
+    console.print(f"[bold]madcop RCA demo[/] — {len(findings)} finding(s) on {events[0].subject_id}\n")
+    if not findings:
+        console.print("  [dim](no findings to trace)[/]")
+        return 0
+    for i, f in enumerate(findings, 1):
+        console.print(f"[cyan]━━━ finding {i}/{len(findings)} ━━━[/]")
+        console.print(f"  rule:    [yellow]{f.rule_id}[/]")
+        console.print(f"  summary: {f.summary}")
+        chain = trace(f, g)
+        if not chain.steps:
+            console.print("  [dim](no causal chain — subject not in knowledge graph)[/]")
+            continue
+        console.print(f"  chain:   [bold]{len(chain.steps)}[/] step(s), root cause:")
+        console.print(Panel(explain(chain), title="root cause", border_style="red"))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="madcop",
+        description="madcop — the supply chain cop that goes mad for anomalies.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    # run <scenario>
+    run_p = sub.add_parser("run", help="Run a scenario")
+    run_sub = run_p.add_subparsers(dest="scenario", required=True)
+    run_sub.add_parser("coldchain", help="W1: print the cold-chain event stream")
+    run_sub.add_parser("anomalies", help="W2: run anomaly detection on the cold-chain stream")
+    run_sub.add_parser("rca",       help="W3: detect anomalies and trace each to a root cause")
+
+    # demo <scenario> — alias for `run`
+    demo_p = sub.add_parser("demo", help="Alias for `run`")
+    demo_sub = demo_p.add_subparsers(dest="scenario", required=True)
+    demo_sub.add_parser("coldchain", help="W1: print the cold-chain event stream")
+    demo_sub.add_parser("anomalies", help="W2: run anomaly detection on the cold-chain stream")
+    demo_sub.add_parser("rca",       help="W3: detect anomalies and trace each to a root cause")
+
+    args = parser.parse_args(argv)
+    if args.cmd in ("run", "demo"):
+        if args.scenario == "coldchain":
+            return run_coldchain()
+        if args.scenario == "anomalies":
+            return run_anomalies_coldchain()
+        if args.scenario == "rca":
+            return run_rca_coldchain()
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

madcop-0.1.0/madcop/adapters/base.py

@@ -0,0 +1,82 @@
+"""Adapter contract — the seam between the outside world and `UnifiedEvent`.
+
+Every system (OMS / TMS / WMS / BMS / future) ships an adapter that implements
+`BaseAdapter`. Two responsibilities, and only two:
+
+1. **Pull** raw data from a system (HTTP, DB, file, etc.) and yield `UnifiedEvent`s.
+2. **Push** actions back to the system (e.g. re-route shipment, mark exception).
+
+We deliberately keep the adapter small. Logic that *reads* the event stream
+lives in the anomaly engine. Logic that *acts* on decisions lives in the
+strategy router. The adapter is just a translator.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Iterator
+
+from ..event import SourceSystem, UnifiedEvent
+
+
+class BaseAdapter(ABC):
+    """The contract every system adapter must satisfy.
+
+    Adapters are stateful objects (they hold a connection, an API key, a
+    file handle). They are constructed once per session and called repeatedly.
+    """
+
+    source_system: SourceSystem  # set by subclass
+
+    @abstractmethod
+    def fetch(self, *, since: str | None = None, subject_id: str | None = None) -> Iterator[UnifiedEvent]:
+        """Yield events from the upstream system, optionally filtered.
+
+        `since` is a UTC ISO 8601 string. If given, only events with
+        `timestamp >= since` should be returned.
+
+        `subject_id`, if given, restricts to events about a single business
+        object (an order, a SKU, a shipment, a contract). Adapters that
+        cannot filter server-side should filter in-memory after fetching.
+
+        Yields events in **any order** — the LangGraph orchestrator sorts
+        by timestamp.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def execute(self, action: "Action") -> dict:
+        """Push an action back to the system. Returns the system's response.
+
+        See `Action` for the schema. Adapters that cannot perform an action
+        (e.g. WMS can't change a contract) should raise
+        `UnsupportedActionError`.
+        """
+        raise NotImplementedError
+
+    def health_check(self) -> bool:
+        """Optional. Default: assume healthy. Override for real wire checks."""
+        return True
+
+
+class UnsupportedActionError(NotImplementedError):
+    """Raised when an adapter is asked to perform an action outside its scope."""
+
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class Action:
+    """A command the strategy router wants executed against an adapter.
+
+    The action is **adapter-agnostic**: the router does not know which system
+    will run it. The router picks an adapter based on `target_system` and the
+    adapter translates the rest.
+    """
+
+    target_system: SourceSystem
+    action_type: str                          # free-form, adapter-defined vocabulary
+    subject_id: str                           # what the action is about
+    parameters: Mapping[str, Any]             # adapter-specific args