hypermind 0.11.0__py3-none-any.whl

hypermind/simlab/modes/aar.py

@@ -0,0 +1,611 @@
+"""Post-Incident After-Action Review mode — HLC time-travel.
+
+The user submits an *incident timeline* (a list of HLC-stamped events
+describing what happened). The mode replays the timeline through the
+swarm: each event is a sealed claim, witnesses cosign, sceptics file
+disputes when claims contradict, the swarm's belief state is checkpointed
+at each HLC tick.
+
+The result view is a **time slider**: drag it back to any HLC moment
+and see what the swarm believed at that instant — which claims were
+sealed, which were under dispute, which witnesses had cosigned, which
+sources had been revoked.
+
+This is the canonical answer to *"what did we know, when did we know
+it, and who said so?"* — the question every incident review eventually
+asks. HyperMind's HLC + transparency log + revocation list make the
+answer cryptographically verifiable.
+
+Spec hooks:
+* §02 HLC — every event carries a deterministic HLC tick
+* §11 Witness Transparency — witness cosign per claim
+* §12 Revocation — sources can be revoked mid-timeline; prior claims
+  downweighted in retrospective replay
+"""
+
+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
+
+# --- Result types ----------------------------------------------------------
+
+
+@dataclass
+class WitnessSig:
+    witness_kid: str
+    witness_label: str
+    sig_hex: str
+    ts_offset_ms: int  # when cosignature was attached (relative to incident start)
+
+
+@dataclass
+class TimelineEvent:
+    """A single sealed claim on the incident timeline."""
+
+    event_id: str
+    ts_offset_ms: int  # relative to incident_start
+    hlc_logical: int  # HLC logical clock value
+    hlc_counter: int  # HLC counter
+    actor_label: str
+    actor_kid: str
+    severity: str  # info|warn|alert|critical
+    title: str
+    detail: str
+    witness_sigs: list[WitnessSig]  # cosigners
+    disputes: list[dict[str, Any]]  # disputes opened against this claim
+    source_revoked_at_ms: int | None  # if non-None, the source was revoked at this offset
+
+
+@dataclass
+class BeliefSnapshot:
+    """Swarm belief state at a single HLC tick. Used to power the slider."""
+
+    ts_offset_ms: int
+    hlc_logical: int
+    hlc_counter: int
+    sealed_claim_ids: list[str]
+    disputed_claim_ids: list[str]
+    revoked_source_ids: list[str]
+    confidence: float  # aggregate confidence in the standing belief set
+    headline: str  # one-line summary of the swarm's standing belief
+
+
+@dataclass
+class AARReport:
+    incident_label: str
+    incident_summary: str
+    starting_hlc_logical: int
+    timeline: list[TimelineEvent]
+    belief_snapshots: list[BeliefSnapshot]
+    pivot_moments: list[dict[str, Any]]  # {ts_offset_ms, label, why} — moments where belief flipped
+    final_findings: list[str]  # the AAR's bottom-line findings
+
+
+# --- Input schema ----------------------------------------------------------
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "title": "Post-Incident After-Action Review",
+    "required": ["incident_label", "events"],
+    "properties": {
+        "incident_label": {
+            "type": "string",
+            "title": "Incident label",
+            "description": "e.g. '2026-04-12 cloud region outage'",
+        },
+        "incident_summary": {
+            "type": "string",
+            "title": "Incident summary (one paragraph)",
+            "format": "textarea",
+            "description": "What happened, in plain English.",
+            "default": "",
+        },
+        "events": {
+            "type": "array",
+            "title": "Timeline events (semicolon-separated)",
+            "description": (
+                "Each event: 'TS|actor|severity|title'. Times are minutes "
+                "since incident start (e.g. '0', '14', '47'). Severity ∈ "
+                "{info, warn, alert, critical}. Example: "
+                "'0|monitoring|info|first error spike;5|on-call|alert|"
+                "investigating;12|sre|critical|root cause confirmed'."
+            ),
+            "examples": [
+                "0|monitoring|info|first error spike",
+                "5|on-call|alert|paging engineering",
+                "14|sre|critical|database failover triggered",
+                "27|security|warn|suspicious auth attempt detected",
+                "47|sre|info|service restored",
+            ],
+            "default": [],
+        },
+    },
+}
+
+
+RESULT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "mode": {"type": "string", "const": "post-incident-aar"},
+        "incident_label": {"type": "string"},
+        "timeline": {"type": "array"},
+        "belief_snapshots": {"type": "array"},
+        "pivot_moments": {"type": "array"},
+        "final_findings": {"type": "array"},
+    },
+}
+
+
+# --- Event parsing ---------------------------------------------------------
+
+
+def _parse_events(raw: list[str]) -> list[dict[str, Any]]:
+    """Parse 'TS|actor|severity|title' strings. Permissive."""
+    out: list[dict[str, Any]] = []
+    for item in raw:
+        if not item or "|" not in item:
+            continue
+        parts = [p.strip() for p in item.split("|")]
+        if len(parts) < 4:
+            continue
+        try:
+            ts_min = float(parts[0])
+        except ValueError:
+            continue
+        out.append(
+            {
+                "ts_offset_ms": int(ts_min * 60_000),
+                "actor": parts[1] or "unknown",
+                "severity": parts[2].lower()
+                if parts[2].lower() in {"info", "warn", "alert", "critical"}
+                else "info",
+                "title": "|".join(parts[3:]),
+            }
+        )
+    out.sort(key=lambda e: e["ts_offset_ms"])
+    return out
+
+
+def _seed_events_from_label(label: str) -> list[dict[str, Any]]:
+    """Demo seed when the user gives no events."""
+    h = label.lower()
+    if "cloud" in h or "outage" in h:
+        return [
+            {
+                "ts_offset_ms": 0,
+                "actor": "monitoring",
+                "severity": "info",
+                "title": "elevated 5xx rate observed",
+            },
+            {
+                "ts_offset_ms": 4 * 60_000,
+                "actor": "on-call",
+                "severity": "alert",
+                "title": "paged engineering on-call",
+            },
+            {
+                "ts_offset_ms": 8 * 60_000,
+                "actor": "sre",
+                "severity": "warn",
+                "title": "suspecting database connection pool exhaustion",
+            },
+            {
+                "ts_offset_ms": 14 * 60_000,
+                "actor": "sre",
+                "severity": "critical",
+                "title": "primary database degraded; failover initiated",
+            },
+            {
+                "ts_offset_ms": 22 * 60_000,
+                "actor": "security",
+                "severity": "alert",
+                "title": "unusual authentication burst detected",
+            },
+            {
+                "ts_offset_ms": 26 * 60_000,
+                "actor": "sre",
+                "severity": "warn",
+                "title": "failover stalled; manual intervention required",
+            },
+            {
+                "ts_offset_ms": 33 * 60_000,
+                "actor": "sre",
+                "severity": "info",
+                "title": "secondary database promoted; throughput recovering",
+            },
+            {
+                "ts_offset_ms": 41 * 60_000,
+                "actor": "security",
+                "severity": "info",
+                "title": "auth burst attributed to retry storm, not attack",
+            },
+            {
+                "ts_offset_ms": 47 * 60_000,
+                "actor": "sre",
+                "severity": "info",
+                "title": "service fully restored",
+            },
+        ]
+    if "cyber" in h or "breach" in h or "attack" in h:
+        return [
+            {
+                "ts_offset_ms": 0,
+                "actor": "siem",
+                "severity": "warn",
+                "title": "anomalous outbound traffic from staging",
+            },
+            {
+                "ts_offset_ms": 6 * 60_000,
+                "actor": "soc",
+                "severity": "alert",
+                "title": "C2 beacon pattern matched; isolating host",
+            },
+            {
+                "ts_offset_ms": 11 * 60_000,
+                "actor": "soc",
+                "severity": "critical",
+                "title": "lateral movement confirmed in dev VPC",
+            },
+            {
+                "ts_offset_ms": 18 * 60_000,
+                "actor": "ir",
+                "severity": "alert",
+                "title": "credential rotation initiated",
+            },
+            {
+                "ts_offset_ms": 25 * 60_000,
+                "actor": "ir",
+                "severity": "warn",
+                "title": "scope of compromise narrowed to one cluster",
+            },
+            {
+                "ts_offset_ms": 38 * 60_000,
+                "actor": "ir",
+                "severity": "info",
+                "title": "containment achieved",
+            },
+            {
+                "ts_offset_ms": 52 * 60_000,
+                "actor": "ir",
+                "severity": "info",
+                "title": "forensic image captured for post-mortem",
+            },
+        ]
+    return [
+        {"ts_offset_ms": 0, "actor": "system", "severity": "info", "title": "incident declared"},
+        {
+            "ts_offset_ms": 12 * 60_000,
+            "actor": "ops",
+            "severity": "alert",
+            "title": "investigation underway",
+        },
+        {
+            "ts_offset_ms": 28 * 60_000,
+            "actor": "ops",
+            "severity": "warn",
+            "title": "mitigation applied",
+        },
+        {
+            "ts_offset_ms": 45 * 60_000,
+            "actor": "ops",
+            "severity": "info",
+            "title": "incident closed",
+        },
+    ]
+
+
+# --- Witness + dispute synth ----------------------------------------------
+
+WITNESSES = [
+    ("witness-sre", "SRE Witness"),
+    ("witness-security", "Security Witness"),
+    ("witness-product", "Product Witness"),
+    ("witness-customer", "Customer-Facing Witness"),
+]
+
+
+def _kid(prefix: str, salt: str) -> str:
+    return hashlib.sha256(f"{prefix}::{salt}".encode()).hexdigest()[:32]
+
+
+def _witness_sigs_for(
+    event: dict[str, Any],
+    incident_salt: str,
+) -> list[WitnessSig]:
+    """Each event picks up 2–4 witness cosignatures depending on severity."""
+    sev_to_n = {"info": 2, "warn": 3, "alert": 3, "critical": 4}
+    n = sev_to_n.get(event["severity"], 2)
+    sigs: list[WitnessSig] = []
+    for i, (slug, label) in enumerate(WITNESSES[:n]):
+        sigs.append(
+            WitnessSig(
+                witness_kid=_kid(slug, incident_salt),
+                witness_label=label,
+                sig_hex=hashlib.sha256(
+                    f"sig::{slug}::{event['title']}::{event['ts_offset_ms']}".encode(),
+                ).hexdigest()[:32],
+                ts_offset_ms=event["ts_offset_ms"] + 30_000 * (i + 1),  # cosignatures lag a bit
+            )
+        )
+    return sigs
+
+
+def _disputes_for(
+    idx: int,
+    event: dict[str, Any],
+    all_events: list[dict[str, Any]],
+    incident_salt: str,
+) -> list[dict[str, Any]]:
+    """A few events earn disputes — typically when subsequent events
+    flatly contradict an earlier alert. Demo heuristic: the security
+    alert "auth burst" gets contradicted by the "retry storm" finding
+    later in the cloud-outage seed."""
+    out: list[dict[str, Any]] = []
+    text = event["title"].lower()
+    follows = [e["title"].lower() for e in all_events[idx + 1 :]]
+
+    if event["severity"] in {"alert", "critical"}:
+        # A claim is disputed if a later event with similar token
+        # ("auth", "attack", "breach") gets walked back ("retry",
+        # "false positive", "attributed to").
+        contradicted = any(
+            (
+                ("auth" in text or "attack" in text or "breach" in text)
+                and ("retry" in f or "false" in f or "attributed" in f or "narrowed" in f)
+            )
+            for f in follows
+        )
+        if contradicted:
+            out.append(
+                {
+                    "dispute_id": f"D-{idx:03d}",
+                    "opened_by_kid": _kid("sceptic", incident_salt + str(idx)),
+                    "opened_at_ms": event["ts_offset_ms"] + 8 * 60_000,
+                    "rationale": (
+                        "Subsequent evidence contradicts the alert's framing. "
+                        "Recommend reclassifying as informational and updating "
+                        "the post-incident timeline."
+                    ),
+                    "final_state": "CLOSED",
+                    "outcome": "claim downweighted",
+                }
+            )
+    return out
+
+
+def _revoke_at(
+    idx: int,
+    event: dict[str, Any],
+    all_events: list[dict[str, Any]],
+    incident_salt: str,
+) -> int | None:
+    """Some sources get retroactively revoked. Demo heuristic: if the
+    event is alert/critical and its actor's later events walk it back,
+    flag the source as revoked at the walking-back moment."""
+    text = event["title"].lower()
+    for later in all_events[idx + 1 :]:
+        ltext = later["title"].lower()
+        if (
+            ("auth" in text or "attack" in text or "breach" in text)
+            and later["actor"] == event["actor"]
+            and ("attributed" in ltext or "retry" in ltext or "false" in ltext)
+        ):
+            return later["ts_offset_ms"]
+    return None
+
+
+# --- Belief snapshot construction -----------------------------------------
+
+
+def _build_snapshots(
+    timeline: list[TimelineEvent],
+) -> tuple[list[BeliefSnapshot], list[dict[str, Any]]]:
+    """For each event, capture the swarm's standing belief state.
+    Also detect *pivot moments* — instants where the belief headline
+    changed materially."""
+    snapshots: list[BeliefSnapshot] = []
+    pivots: list[dict[str, Any]] = []
+    sealed: list[str] = []
+    disputed: list[str] = []
+    revoked: list[str] = []
+    last_headline = ""
+
+    for ev in timeline:
+        sealed.append(ev.event_id)
+        # Disputes opened against this event flag it as disputed.
+        for _d in ev.disputes:
+            if ev.event_id not in disputed:
+                disputed.append(ev.event_id)
+        # If this event walks back an earlier one, retroactively revoke
+        # the source on the prior event (its source_revoked_at_ms field
+        # carries the offset). For the snapshot, anything whose source
+        # was revoked at-or-before this ts_offset is in the revoked list.
+        revoked_now = [
+            t.event_id
+            for t in timeline
+            if t.source_revoked_at_ms is not None and t.source_revoked_at_ms <= ev.ts_offset_ms
+        ]
+        revoked = revoked_now
+
+        # Standing belief headline = severity + title of the latest
+        # non-revoked alert/critical event.
+        headline_event = next(
+            (
+                e
+                for e in reversed(timeline[: timeline.index(ev) + 1])
+                if e.severity in {"alert", "critical"} and e.event_id not in revoked
+            ),
+            None,
+        )
+        headline = (
+            f"{headline_event.severity.upper()}: {headline_event.title}"
+            if headline_event
+            else f"Standing: {ev.title}"
+        )
+        confidence = 1.0 - 0.15 * len(disputed) / max(len(sealed), 1)
+
+        snap = BeliefSnapshot(
+            ts_offset_ms=ev.ts_offset_ms,
+            hlc_logical=ev.hlc_logical,
+            hlc_counter=ev.hlc_counter,
+            sealed_claim_ids=list(sealed),
+            disputed_claim_ids=list(disputed),
+            revoked_source_ids=list(revoked),
+            confidence=round(max(0.0, min(1.0, confidence)), 3),
+            headline=headline,
+        )
+        snapshots.append(snap)
+        if headline != last_headline and last_headline != "":
+            pivots.append(
+                {
+                    "ts_offset_ms": ev.ts_offset_ms,
+                    "from_headline": last_headline,
+                    "to_headline": headline,
+                    "trigger_event_id": ev.event_id,
+                }
+            )
+        last_headline = headline
+
+    return snapshots, pivots
+
+
+# --- Final findings synthesis ---------------------------------------------
+
+
+def _final_findings(
+    timeline: list[TimelineEvent],
+    pivots: list[dict[str, Any]],
+) -> list[str]:
+    findings: list[str] = []
+    n_critical = sum(1 for e in timeline if e.severity == "critical")
+    n_disputed = sum(1 for e in timeline if e.disputes)
+    n_revoked = sum(1 for e in timeline if e.source_revoked_at_ms is not None)
+    n_pivots = len(pivots)
+    if n_critical:
+        findings.append(
+            f"{n_critical} critical event{'s' if n_critical != 1 else ''} during the incident; "
+            f"all reached witness cosign quorum.",
+        )
+    if n_disputed:
+        findings.append(
+            f"{n_disputed} claim{'s' if n_disputed != 1 else ''} were retrospectively disputed; "
+            f"these were downweighted in the standing belief.",
+        )
+    if n_revoked:
+        findings.append(
+            f"{n_revoked} source{'s' if n_revoked != 1 else ''} retroactively revoked once "
+            f"corrective evidence arrived. Prior claims from those sources are flagged in the slider.",
+        )
+    if n_pivots:
+        findings.append(
+            f"{n_pivots} belief-pivot moment{'s' if n_pivots != 1 else ''} detected — drag the "
+            f"slider to any pivot to see what the swarm thought before vs. after.",
+        )
+    if not findings:
+        findings.append("Incident timeline replayed without dispute or revocation activity.")
+    return findings
+
+
+# --- Run function ----------------------------------------------------------
+
+
+async def _run_aar(args: Any, recorder: Any | None = None) -> None:
+    payload = getattr(args, "mode_payload", None) or {}
+    label = (payload.get("incident_label") or "").strip() or "Incident replay"
+    summary = payload.get("incident_summary") or ""
+    raw_events = payload.get("events") or []
+    if isinstance(raw_events, str):
+        raw_events = [raw_events]
+
+    parsed = _parse_events(list(raw_events))
+    if not parsed:
+        parsed = _seed_events_from_label(label)
+
+    started_at = time.time()
+    incident_salt = hashlib.sha256(label.encode("utf-8")).hexdigest()[:16]
+
+    # Build timeline events with HLC stamps + witness sigs + disputes.
+    timeline: list[TimelineEvent] = []
+    starting_hlc_logical = int(started_at * 1000)
+    for i, ev in enumerate(parsed):
+        revoked_at = _revoke_at(i, ev, parsed, incident_salt)
+        timeline.append(
+            TimelineEvent(
+                event_id=f"E-{i + 1:03d}",
+                ts_offset_ms=ev["ts_offset_ms"],
+                hlc_logical=starting_hlc_logical + ev["ts_offset_ms"],
+                hlc_counter=i,
+                actor_label=ev["actor"],
+                actor_kid=_kid(f"actor::{ev['actor']}", incident_salt),
+                severity=ev["severity"],
+                title=ev["title"],
+                detail=(
+                    f"At T+{ev['ts_offset_ms'] // 60_000}m the {ev['actor']} "
+                    f"recorded: {ev['title']}."
+                ),
+                witness_sigs=_witness_sigs_for(ev, incident_salt),
+                disputes=_disputes_for(i, ev, parsed, incident_salt),
+                source_revoked_at_ms=revoked_at,
+            )
+        )
+
+    snapshots, pivots = _build_snapshots(timeline)
+    findings = _final_findings(timeline, pivots)
+
+    report = AARReport(
+        incident_label=label,
+        incident_summary=summary,
+        starting_hlc_logical=starting_hlc_logical,
+        timeline=timeline,
+        belief_snapshots=snapshots,
+        pivot_moments=pivots,
+        final_findings=findings,
+    )
+
+    elapsed = time.time() - started_at
+    trace = {
+        "mode": "post-incident-aar",
+        "started_at": started_at,
+        "elapsed_s": round(elapsed, 3),
+        "n_agents": len(WITNESSES) + 1,
+        "n_questions": 1,
+        "incident_label": label,
+        "report": asdict(report),
+        "collective_iq": {
+            "score": round(
+                snapshots[-1].confidence if snapshots else 0.5,
+                4,
+            ),
+        },
+    }
+
+    Path(args.trace).write_text(json.dumps(trace, indent=2, default=str))
+
+
+# --- Registration ----------------------------------------------------------
+
+SPEC = ModeSpec(
+    slug="post-incident-aar",
+    label="Post-Incident After-Action Review",
+    description=(
+        "Replay an incident timeline through the swarm: HLC-stamped "
+        "claims, witness cosignatures, retrospective disputes and "
+        "source revocations. Result is a time-slider — drag back to "
+        "any moment to see what the swarm believed at that instant."
+    ),
+    input_schema=INPUT_SCHEMA,
+    result_schema=RESULT_SCHEMA,
+    run_fn=_run_aar,
+    uses_legacy_fields=False,
+    expected_roles=["scout", "sceptic", "witness", "mediator"],
+)
+
+
+register(SPEC)