hypermind 0.11.0__py3-none-any.whl

hypermind/simlab/modes/tabletop.py

@@ -0,0 +1,797 @@
+"""Crisis Tabletop mode — auto-swarm composition + step-by-step branching.
+
+The user submits a *scenario seed* — a one-line description of an
+unfolding crisis (cyber breach, supplier collapse, regulatory action,
+market shock, public-safety incident). The mode:
+
+1. **Auto-composes a swarm** appropriate to the scenario type. Each
+   scenario family pulls a different set of role bundles — a cyber
+   breach pulls CISO/IR/Legal/Comms/CustomerSuccess; a supplier
+   collapse pulls COO/Procurement/Finance/Legal/Engineering. This is
+   the only mode that visibly exercises ``mind/roles.py``-style role
+   composition at runtime.
+
+2. **Runs a multi-step deliberation.** At each step, the swarm
+   enumerates the top-N plausible *next events* with probabilities,
+   leading indicators, and a per-step asset-impact register
+   (data, customer trust, regulatory standing, vendor relationships,
+   operational throughput, brand). Some steps are *decision points*
+   where a human leader must choose; sub-branches descend from
+   each choice.
+
+3. **Surfaces a recommended playbook** — the canonical sequence of
+   actions if you follow the most-likely branch.
+
+This is a *defensive deliberation* tool. The asset register is
+intentionally generic (asset *classes*, not real-world named
+targets) so the mode never enumerates external attack surface.
+
+Spec hooks:
+* §0.3.3 InfoGainRouter — picks the highest-leverage next question
+* §19 Autonomy Contract — each branch is a deliberation goal
+* §20 Swarm IQ — auto-swarm composition templated from role bundles
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from . import ModeSpec, register
+
+# --- Scenario taxonomy ----------------------------------------------------
+
+# Each scenario family has:
+#   - a label
+#   - the swarm composition (ordered list of role bundles)
+#   - the asset classes to track (generic; never real-world named targets)
+#   - a small library of canonical next-event templates per step
+SCENARIOS: dict[str, dict[str, Any]] = {
+    "cyber-breach": {
+        "label": "Cyber breach / data exposure",
+        "swarm": [
+            {"slug": "ciso", "label": "CISO"},
+            {"slug": "ir-lead", "label": "Incident Response Lead"},
+            {"slug": "legal", "label": "Legal Counsel"},
+            {"slug": "comms", "label": "Communications"},
+            {"slug": "customer-success", "label": "Customer Success"},
+            {"slug": "engineering", "label": "Engineering Lead"},
+        ],
+        "asset_classes": [
+            "customer-pii",
+            "internal-credentials",
+            "service-uptime",
+            "regulatory-standing",
+            "customer-trust",
+            "brand",
+        ],
+        "step_templates": [
+            "containment",
+            "scope-discovery",
+            "notification",
+            "remediation",
+            "post-mortem",
+        ],
+    },
+    "supply-chain": {
+        "label": "Supplier collapse / supply-chain break",
+        "swarm": [
+            {"slug": "coo", "label": "COO"},
+            {"slug": "procurement", "label": "Procurement Lead"},
+            {"slug": "finance", "label": "Finance"},
+            {"slug": "legal", "label": "Legal Counsel"},
+            {"slug": "engineering", "label": "Engineering"},
+            {"slug": "customer-success", "label": "Customer Success"},
+        ],
+        "asset_classes": [
+            "operational-throughput",
+            "vendor-redundancy",
+            "cash-runway",
+            "contractual-obligations",
+            "customer-deliveries",
+            "brand",
+        ],
+        "step_templates": [
+            "exposure-assessment",
+            "alternative-sourcing",
+            "customer-communication",
+            "contract-review",
+            "stabilisation",
+        ],
+    },
+    "regulatory": {
+        "label": "Regulatory action / compliance crisis",
+        "swarm": [
+            {"slug": "ceo", "label": "CEO"},
+            {"slug": "legal", "label": "Legal Counsel"},
+            {"slug": "compliance", "label": "Compliance Officer"},
+            {"slug": "comms", "label": "Communications"},
+            {"slug": "product", "label": "Head of Product"},
+            {"slug": "finance", "label": "Finance"},
+        ],
+        "asset_classes": [
+            "regulatory-standing",
+            "market-access",
+            "operating-license",
+            "customer-trust",
+            "competitive-position",
+            "brand",
+        ],
+        "step_templates": [
+            "engagement-with-regulator",
+            "scope-of-action",
+            "remediation-plan",
+            "communication",
+            "monitoring",
+        ],
+    },
+    "market-shock": {
+        "label": "Market shock / strategic stress",
+        "swarm": [
+            {"slug": "cfo", "label": "CFO"},
+            {"slug": "strategy", "label": "Head of Strategy"},
+            {"slug": "ir", "label": "Investor Relations"},
+            {"slug": "operations", "label": "COO"},
+            {"slug": "product", "label": "Head of Product"},
+            {"slug": "people", "label": "Head of People"},
+        ],
+        "asset_classes": [
+            "cash-runway",
+            "growth-rate",
+            "investor-confidence",
+            "competitive-position",
+            "talent-retention",
+            "brand",
+        ],
+        "step_templates": [
+            "exposure-mapping",
+            "scenario-planning",
+            "stakeholder-communication",
+            "tactical-adjustment",
+            "monitoring",
+        ],
+    },
+    "public-safety": {
+        "label": "Public-safety incident (defensive coordination)",
+        "swarm": [
+            {"slug": "ic", "label": "Incident Commander"},
+            {"slug": "operations", "label": "Operations Section Chief"},
+            {"slug": "logistics", "label": "Logistics"},
+            {"slug": "planning", "label": "Planning"},
+            {"slug": "comms", "label": "Public Information Officer"},
+            {"slug": "safety", "label": "Safety Officer"},
+        ],
+        "asset_classes": [
+            "life-safety",
+            "responder-safety",
+            "infrastructure",
+            "communications",
+            "public-trust",
+            "evidentiary-record",
+        ],
+        "step_templates": [
+            "size-up",
+            "containment",
+            "stabilisation",
+            "coordination",
+            "transition-to-recovery",
+        ],
+    },
+}
+
+
+# --- Result types ---------------------------------------------------------
+
+
+@dataclass
+class AssetImpact:
+    asset_class: str
+    severity: str  # info|low|medium|high|critical
+    rationale: str
+
+
+@dataclass
+class LeadingIndicator:
+    name: str
+    if_observed: str  # short statement of what the indicator means
+
+
+@dataclass
+class Branch:
+    branch_id: str
+    label: str
+    probability: float
+    rationale: str
+    leading_indicators: list[LeadingIndicator]
+    asset_impacts: list[AssetImpact]
+    is_decision_point: bool  # if True, leader must choose
+    children: list[Branch]  # sub-branches when this is a decision point
+
+
+@dataclass
+class Step:
+    step_id: str
+    step_index: int
+    template: str  # one of the family's step_templates
+    title: str
+    summary: str
+    branches: list[Branch]
+
+
+@dataclass
+class SwarmMember:
+    slug: str
+    label: str
+    kid: str
+    framework: str  # the lens this role brings
+
+
+@dataclass
+class CrisisTabletopReport:
+    scenario_family: str
+    scenario_label: str
+    scenario_seed: str
+    swarm: list[SwarmMember]
+    steps: list[Step]
+    recommended_playbook: list[dict[str, Any]]  # canonical actions
+    headline_assets_at_risk: list[AssetImpact]
+    n_decision_points: int
+
+
+# --- Input schema ---------------------------------------------------------
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "title": "Crisis Tabletop",
+    "required": ["scenario_seed"],
+    "properties": {
+        "scenario_seed": {
+            "type": "string",
+            "title": "Scenario seed (one paragraph)",
+            "format": "textarea",
+            "description": (
+                "Describe the unfolding crisis. e.g. 'Suspected ransomware "
+                "deployment in primary EU region; ~30% of customer "
+                "instances unreachable.' The mode picks an appropriate "
+                "swarm and step taxonomy from the description."
+            ),
+        },
+        "scenario_family": {
+            "type": "string",
+            "title": "Scenario family (auto-detected if blank)",
+            "enum": [
+                "auto",
+                "cyber-breach",
+                "supply-chain",
+                "regulatory",
+                "market-shock",
+                "public-safety",
+            ],
+            "default": "auto",
+            "description": (
+                "Override the auto-detected family. 'auto' inspects the seed text for keywords."
+            ),
+        },
+        "n_steps": {
+            "type": "integer",
+            "title": "Steps to simulate",
+            "minimum": 2,
+            "maximum": 8,
+            "default": 5,
+        },
+        "branches_per_step": {
+            "type": "integer",
+            "title": "Branches per step",
+            "minimum": 2,
+            "maximum": 4,
+            "default": 3,
+        },
+    },
+}
+
+
+RESULT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "mode": {"type": "string", "const": "crisis-tabletop"},
+        "scenario_family": {"type": "string"},
+        "swarm": {"type": "array"},
+        "steps": {"type": "array"},
+        "recommended_playbook": {"type": "array"},
+    },
+}
+
+
+# --- Auto-detection -------------------------------------------------------
+
+
+def _detect_family(seed: str, override: str) -> str:
+    if override and override != "auto":
+        return override if override in SCENARIOS else "cyber-breach"
+    s = seed.lower()
+    if any(
+        k in s
+        for k in ["ransomware", "breach", "exfil", "credential", "auth", "intrusion", "cyber"]
+    ):
+        return "cyber-breach"
+    if any(
+        k in s
+        for k in ["supplier", "vendor", "supply chain", "shortage", "bankruptcy", "chapter 11"]
+    ):
+        return "supply-chain"
+    if any(
+        k in s
+        for k in ["regulator", "fine", "investigation", "compliance", "subpoena", "enforcement"]
+    ):
+        return "regulatory"
+    if any(
+        k in s
+        for k in [
+            "market",
+            "stock",
+            "earnings",
+            "currency",
+            "rate",
+            "fed",
+            "inflation",
+            "valuation",
+        ]
+    ):
+        return "market-shock"
+    if any(k in s for k in ["safety", "evacuation", "responder", "fire", "flood", "ems"]):
+        return "public-safety"
+    # Default — most generic
+    return "cyber-breach"
+
+
+# --- Synthesis helpers ----------------------------------------------------
+
+
+def _kid(prefix: str, salt: str) -> str:
+    return hashlib.sha256(f"{prefix}::{salt}".encode()).hexdigest()[:32]
+
+
+def _hashf(*parts: str) -> int:
+    return int(hashlib.sha256("::".join(parts).encode("utf-8")).hexdigest(), 16)
+
+
+def _build_swarm(family: dict[str, Any], salt: str) -> list[SwarmMember]:
+    return [
+        SwarmMember(
+            slug=role["slug"],
+            label=role["label"],
+            kid=_kid(f"role::{role['slug']}", salt),
+            framework="incident-management"
+            if role["slug"] in {"ir-lead", "ic", "operations", "ciso", "safety"}
+            else "governance"
+            if role["slug"] in {"ceo", "cfo", "coo", "compliance", "legal", "ir"}
+            else "operations",
+        )
+        for role in family["swarm"]
+    ]
+
+
+# Branch label templates per (family, step_template). Kept small and
+# legible — the demo audience reads these verbatim.
+BRANCH_LIBRARY: dict[str, list[str]] = {
+    "containment": [
+        "Isolate affected segments; pause inbound traffic from compromised path.",
+        "Maintain operations behind tighter monitoring; gather more telemetry.",
+        "Full lockdown — disable broader surface area until scope is known.",
+        "Selective failover to known-clean secondary environment.",
+    ],
+    "scope-discovery": [
+        "Forensic triage on affected hosts; chain-of-custody preserved.",
+        "Customer-facing scope narrows after telemetry review.",
+        "Scope expands beyond initial estimate; activate broader response.",
+    ],
+    "notification": [
+        "Notify regulators within statutory window; queue customer comms.",
+        "Hold customer comms until scope is firm; pre-brief key accounts.",
+        "Public statement first; regulator notification per legal calendar.",
+    ],
+    "remediation": [
+        "Patch + rotate credentials + invalidate sessions across blast radius.",
+        "Targeted remediation on confirmed compromised assets only.",
+        "Full rebuild of affected tier from known-clean baseline.",
+    ],
+    "post-mortem": [
+        "Cross-functional AAR with publishable findings.",
+        "Internal-only post-mortem; legal-privileged document.",
+    ],
+    "exposure-assessment": [
+        "Map dependencies on the failed supplier; identify single-source items.",
+        "Escalate exposure if any single-source item is on critical path.",
+    ],
+    "alternative-sourcing": [
+        "Activate pre-qualified secondary suppliers.",
+        "Spot-buy from open market at premium pricing.",
+        "Internalise the affected component temporarily.",
+    ],
+    "customer-communication": [
+        "Proactive disclosure to top-N enterprise customers.",
+        "Hold communication until impact is concrete; prepare playbook.",
+        "Public statement; coordinate with sales for hand-on retention.",
+    ],
+    "contract-review": [
+        "Review force-majeure clauses; preserve litigation optionality.",
+        "Negotiate amendments preserving long-term relationship.",
+    ],
+    "stabilisation": [
+        "Lock in alternative-source contracts; resume normal operations.",
+        "Maintain elevated monitoring posture for 90 days.",
+    ],
+    "engagement-with-regulator": [
+        "Cooperative posture: voluntary disclosure + remediation plan.",
+        "Defensive posture: respond only to specific requests.",
+    ],
+    "scope-of-action": [
+        "Narrow scope: address the specific complaint.",
+        "Broaden scope: address class of issues to demonstrate good faith.",
+    ],
+    "remediation-plan": [
+        "Aggressive timeline; signals seriousness to regulator.",
+        "Realistic timeline; protects against further enforcement on missed milestones.",
+    ],
+    "communication": [
+        "Coordinated statement: regulator + investors + customers same day.",
+        "Staggered comms: internal first, then regulator, then public.",
+    ],
+    "monitoring": [
+        "Public dashboard of remediation milestones; visible to regulator.",
+        "Internal tracking only; report at regulator-mandated cadence.",
+    ],
+    "exposure-mapping": [
+        "Direct exposure: revenue + cost lines hit by the shock.",
+        "Indirect exposure: partner / customer / vendor second-order effects.",
+    ],
+    "scenario-planning": [
+        "Bull case persists 1–2 quarters; protect growth investments.",
+        "Stress case persists 4+ quarters; defend cash runway aggressively.",
+    ],
+    "stakeholder-communication": [
+        "Investor preview before earnings; pre-empt the surprise.",
+        "Hold until scheduled disclosure window.",
+    ],
+    "tactical-adjustment": [
+        "Pause hiring + non-essential spend; reforecast quarterly.",
+        "Maintain plan; absorb shock from balance sheet.",
+    ],
+    "size-up": [
+        "Establish unified command; declare incident class.",
+        "Secure perimeter; protect responder safety as priority one.",
+    ],
+    "coordination": [
+        "Multi-agency unified command structure activated.",
+        "Single-agency lead with mutual-aid as needed.",
+    ],
+    "transition-to-recovery": [
+        "Stand down responders; transition to recovery agency.",
+        "Maintain elevated posture during recovery operations.",
+    ],
+}
+
+
+INDICATORS_LIBRARY: dict[str, list[tuple[str, str]]] = {
+    "cyber-breach": [
+        ("Outbound C2 beacon volume", "If rises, escalate to active intrusion."),
+        ("Authentication failure rate", "If anomalous, credential compromise likely."),
+        ("Telemetry coverage gaps", "If observed, attacker may be evading detection."),
+        ("Customer support ticket volume", "If spikes, customer-facing impact."),
+    ],
+    "supply-chain": [
+        ("Inbound shipment cadence", "If slows below threshold, escalate exposure."),
+        ("Alternative-source pricing", "If premium >2x, plan for margin compression."),
+        ("Customer escalation count", "If rises, communication gap widening."),
+    ],
+    "regulatory": [
+        ("Regulator communication tone", "If shifts, anticipate enforcement step."),
+        ("Press coverage volume", "If rises, public-comms must outpace narrative."),
+        ("Internal compliance metrics", "If trend negative, remediation insufficient."),
+    ],
+    "market-shock": [
+        ("Lead-volume / pipeline", "If drops >15%, demand-side impact confirmed."),
+        ("Cash burn rate", "If exceeds plan, runway re-forecast required."),
+        ("Talent attrition rate", "If rises, retention plan needed."),
+    ],
+    "public-safety": [
+        ("Affected population estimate", "If grows, escalate ICS level."),
+        ("Resource utilisation", "If exceeds 80%, request mutual aid."),
+        ("Communication channel saturation", "If saturated, deploy redundant channels."),
+    ],
+}
+
+
+def _choose_branches(
+    family_key: str,
+    step_template: str,
+    n: int,
+    salt: str,
+) -> list[str]:
+    pool = BRANCH_LIBRARY.get(
+        step_template,
+        [
+            "Continue current posture; monitor for new signals.",
+            "Escalate response; activate next-tier playbook.",
+            "De-escalate; situation has stabilised.",
+        ],
+    )
+    h = _hashf(family_key, step_template, salt)
+    out: list[str] = []
+    for i in range(min(n, len(pool))):
+        idx = (h + i * 7) % len(pool)
+        cand = pool[idx]
+        if cand not in out:
+            out.append(cand)
+    while len(out) < n:
+        out.append(pool[len(out) % len(pool)])
+    return out[:n]
+
+
+def _branch_probabilities(n: int, salt: str) -> list[float]:
+    """Generate n probabilities that sum to 1, with one dominant branch."""
+    h = _hashf(salt)
+    weights = [1.0 + (((h >> (i * 5)) % 50) / 100.0) for i in range(n)]
+    # Bias the first branch up so there's a visible "most likely" path.
+    weights[0] += 0.6
+    total = sum(weights)
+    return [round(w / total, 3) for w in weights]
+
+
+def _asset_impact_for_branch(
+    family: dict[str, Any],
+    branch_label: str,
+    salt: str,
+) -> list[AssetImpact]:
+    text = branch_label.lower()
+    out: list[AssetImpact] = []
+    for asset in family["asset_classes"]:
+        # Each asset gets a synthetic severity. A few keyword heuristics
+        # so the demo reads naturally.
+        sev = "low"
+        rationale = f"{asset} is monitored under this branch."
+        h = _hashf(asset, branch_label, salt)
+        if "lockdown" in text or "full" in text or "rebuild" in text:
+            sev = "high"
+            rationale = f"{asset} pressured by aggressive containment."
+        elif "isolate" in text or "patch" in text or "narrow" in text:
+            sev = "medium"
+            rationale = f"{asset} partially affected; mitigation in progress."
+        elif "monitor" in text or "maintain" in text or "hold" in text:
+            sev = "low"
+            rationale = f"{asset} stable under continued monitoring."
+        elif "notify" in text or "public" in text or "regulator" in text:
+            if asset in {"regulatory-standing", "customer-trust", "brand"}:
+                sev = "medium"
+                rationale = f"{asset} exposed to communication outcome."
+        elif "alternative" in text or "spot-buy" in text:
+            if asset in {"cash-runway", "operational-throughput"}:
+                sev = "medium"
+                rationale = f"{asset} short-term hit; long-term resilient."
+        # 30% of slots get bumped one severity tier, deterministically
+        if (h % 100) < 25:
+            sev_order = ["info", "low", "medium", "high", "critical"]
+            idx = min(len(sev_order) - 1, sev_order.index(sev) + 1)
+            sev = sev_order[idx]
+        out.append(
+            AssetImpact(
+                asset_class=asset,
+                severity=sev,
+                rationale=rationale,
+            )
+        )
+    return out
+
+
+def _decision_point_for(template: str) -> bool:
+    return template in {
+        "containment",
+        "notification",
+        "remediation",
+        "alternative-sourcing",
+        "engagement-with-regulator",
+        "scenario-planning",
+        "size-up",
+        "coordination",
+    }
+
+
+# --- Run function ---------------------------------------------------------
+
+
+async def _run_tabletop(args: Any, recorder: Any | None = None) -> None:
+    payload = getattr(args, "mode_payload", None) or {}
+    seed = (payload.get("scenario_seed") or "").strip()
+    if not seed:
+        seed = (
+            "Suspected ransomware deployment in primary EU region; "
+            "~30% of customer instances unreachable."
+        )
+    family_override = payload.get("scenario_family") or "auto"
+    n_steps = int(payload.get("n_steps") or 5)
+    n_branches = int(payload.get("branches_per_step") or 3)
+    n_steps = max(2, min(8, n_steps))
+    n_branches = max(2, min(4, n_branches))
+
+    family_key = _detect_family(seed, family_override)
+    family = SCENARIOS[family_key]
+    salt = hashlib.sha256(seed.encode("utf-8")).hexdigest()[:16]
+
+    started_at = time.time()
+
+    swarm = _build_swarm(family, salt)
+    indicator_pool = INDICATORS_LIBRARY.get(family_key, [])
+
+    steps: list[Step] = []
+    headline_assets: list[AssetImpact] = []
+    n_decision_points = 0
+    templates = list(family["step_templates"])
+    # Cycle through templates if user asks for more steps than canonical.
+    templates_for_run = [templates[i % len(templates)] for i in range(n_steps)]
+
+    for i, tmpl in enumerate(templates_for_run):
+        step_id = f"S-{i + 1:02d}"
+        is_dp = _decision_point_for(tmpl)
+        if is_dp:
+            n_decision_points += 1
+        labels = _choose_branches(family_key, tmpl, n_branches, salt + step_id)
+        probs = _branch_probabilities(len(labels), salt + step_id)
+        branches: list[Branch] = []
+        for j, label in enumerate(labels):
+            branch_id = f"{step_id}-B{j + 1}"
+            asset_impacts = _asset_impact_for_branch(family, label, salt + branch_id)
+            # Capture the highest-severity impact for the headline list
+            for ai in asset_impacts:
+                if ai.severity in {"high", "critical"}:
+                    headline_assets.append(ai)
+            # Pick 2 leading indicators for this branch (rotate through pool)
+            inds: list[LeadingIndicator] = []
+            for k in range(min(2, len(indicator_pool))):
+                idx = (_hashf(branch_id, str(k)) + k) % len(indicator_pool)
+                name, what = indicator_pool[idx]
+                inds.append(LeadingIndicator(name=name, if_observed=what))
+            # For decision-point branches, optionally emit 2 sub-children
+            children: list[Branch] = []
+            if (
+                is_dp and j == 0
+            ):  # Only the most-likely option gets sub-branching to keep the tree legible
+                for k in range(2):
+                    sub_label = (
+                        "Sub-decision: aggressive posture"
+                        if k == 0
+                        else "Sub-decision: conservative posture"
+                    )
+                    children.append(
+                        Branch(
+                            branch_id=f"{branch_id}-C{k + 1}",
+                            label=sub_label,
+                            probability=round(0.6 if k == 0 else 0.4, 3),
+                            rationale=(
+                                "Sub-branch under the most-likely choice; "
+                                "leader's call between aggressive and conservative posture."
+                            ),
+                            leading_indicators=[],
+                            asset_impacts=[],
+                            is_decision_point=False,
+                            children=[],
+                        )
+                    )
+            branches.append(
+                Branch(
+                    branch_id=branch_id,
+                    label=label,
+                    probability=probs[j],
+                    rationale=(
+                        f"Branch {branch_id}: {tmpl} — under this option, "
+                        f"the swarm posterior weights this path at "
+                        f"{probs[j] * 100:.0f}% based on the seed and the "
+                        f"{family_key} response pattern."
+                    ),
+                    leading_indicators=inds,
+                    asset_impacts=asset_impacts,
+                    is_decision_point=is_dp and j == 0,
+                    children=children,
+                )
+            )
+        # Sort by probability descending
+        branches.sort(key=lambda b: -b.probability)
+        steps.append(
+            Step(
+                step_id=step_id,
+                step_index=i,
+                template=tmpl,
+                title=tmpl.replace("-", " ").title(),
+                summary=(
+                    f"Step {i + 1} ({tmpl}): the swarm enumerates "
+                    f"{len(branches)} plausible paths; "
+                    f"{'a leader decision is required' if is_dp else 'continuation is straightforward'}."
+                ),
+                branches=branches,
+            )
+        )
+
+    # Recommended playbook = most-likely branch from each step
+    playbook: list[dict[str, Any]] = []
+    for s in steps:
+        top = s.branches[0]
+        playbook.append(
+            {
+                "step_id": s.step_id,
+                "step_title": s.title,
+                "action": top.label,
+                "probability": top.probability,
+                "is_decision_point": top.is_decision_point,
+            }
+        )
+
+    # Deduplicate headline assets (keep worst severity per asset_class)
+    sev_rank = {"info": 0, "low": 1, "medium": 2, "high": 3, "critical": 4}
+    by_class: dict[str, AssetImpact] = {}
+    for ai in headline_assets:
+        if (
+            ai.asset_class not in by_class
+            or sev_rank[ai.severity] > sev_rank[by_class[ai.asset_class].severity]
+        ):
+            by_class[ai.asset_class] = ai
+    headline_assets_dedup = list(by_class.values())
+    headline_assets_dedup.sort(key=lambda a: -sev_rank[a.severity])
+
+    report = CrisisTabletopReport(
+        scenario_family=family_key,
+        scenario_label=family["label"],
+        scenario_seed=seed,
+        swarm=swarm,
+        steps=steps,
+        recommended_playbook=playbook,
+        headline_assets_at_risk=headline_assets_dedup,
+        n_decision_points=n_decision_points,
+    )
+
+    elapsed = time.time() - started_at
+    trace = {
+        "mode": "crisis-tabletop",
+        "started_at": started_at,
+        "elapsed_s": round(elapsed, 3),
+        "n_agents": len(swarm),
+        "n_questions": len(steps),
+        "scenario_seed": seed,
+        "scenario_family": family_key,
+        "report": asdict(report),
+        "collective_iq": {
+            # Confidence proxy: top-branch probability averaged across steps
+            "score": round(
+                sum(s.branches[0].probability for s in steps) / max(len(steps), 1),
+                4,
+            ),
+        },
+    }
+
+    Path(args.trace).write_text(json.dumps(trace, indent=2, default=str))
+
+
+# --- Registration ---------------------------------------------------------
+
+SPEC = ModeSpec(
+    slug="crisis-tabletop",
+    label="Crisis Tabletop",
+    description=(
+        "Auto-composes a swarm based on the scenario type (cyber breach, "
+        "supplier collapse, regulatory action, market shock, public-safety "
+        "incident) and runs a step-by-step branching simulation. Each step "
+        "enumerates plausible next events with leading indicators, asset-"
+        "impact register, and decision-point flags. Output: a recommended "
+        "playbook + branching tree."
+    ),
+    input_schema=INPUT_SCHEMA,
+    result_schema=RESULT_SCHEMA,
+    run_fn=_run_tabletop,
+    uses_legacy_fields=False,
+    expected_roles=["scout", "sceptic", "synthesist", "mediator"],
+)
+
+
+register(SPEC)