v0.36.0: vstack.redaction + health + priority_queue + snippet + aggregate

Five more feature modules (thirty-four total):

  - vstack.redaction: PII/secret scrubbing for traces. Built-in
    patterns for email, phone, SSN, credit card, AWS keys,
    sk-prefixed API keys, Bearer tokens, JWT, IPv4, URL credentials.
    Redactor tracks match counts; scrub_trace() returns redacted
    copy with original unmutated.

  - vstack.health: composite health checks. Check protocol +
    CallableCheck adapter. HealthReport with HEALTHY/DEGRADED/
    UNHEALTHY status. HealthMonitor with interval-aware tick().

  - vstack.priority_queue: finding priority queue with aging.
    Score = severity_weight × confidence_multiplier + age_boost
    + manual_boost. Aging prevents low-severity starvation.
    boost/remove_pattern/snapshot helpers.

  - vstack.snippet: minimal trace excerpts. find_relevant_steps()
    via token-overlap heuristic. extract_snippet() pulls context
    around relevant steps with omission counts. render_snippet()
    produces markdown.

  - vstack.aggregate: cross-report aggregation. AggregateSummary
    with per-pattern stats + severity/agent counts. top_n_patterns,
    top_n_agents, severity_distribution, cooccurrence_matrix.

113 new tests; all 3,127 tests pass (was 3,014).

Author: valani9

CHANGELOG.md

@@ -6,6 +6,55 @@ project adheres to [Semantic Versioning](https://semver.org/) from
 `1.0.0` onward. During the `0.x` series, minor bumps may include
 breaking changes (see API stability promise in `vstack/__init__.py`).
 
+## [0.36.0] — 2026-06-09
+
+Five more feature modules: redaction + health + priority_queue +
+snippet + aggregate. Thirty-four feature modules total since v0.23.0.
+
+### Added
+
+- **`vstack.redaction`** — PII / secret scrubbing for traces.
+  `RedactionPattern` (regex + replacement); built-in
+  `DEFAULT_PATTERNS` covering email, US/CA phone, SSN, credit card,
+  AWS access/secret keys, sk-prefixed API keys, Bearer tokens, JWT,
+  IPv4, URLs with user:pass@ credentials. `Redactor` tracks per-
+  pattern match counts; `scrub_trace()` returns a redacted copy of
+  the trace with goal/outcome/step content scrubbed (original
+  unmutated).
+- **`vstack.health`** — composite health checks. `Check` protocol +
+  `CallableCheck` adapter. `HealthReport` aggregates with
+  HEALTHY / DEGRADED / UNHEALTHY status (critical UNHEALTHY →
+  UNHEALTHY; non-critical UNHEALTHY → DEGRADED). `HealthMonitor`
+  with `tick()` (interval-aware) + `force_tick()` for scheduler-
+  driven probes.
+- **`vstack.priority_queue`** — finding priority queue with aging
+  boost. `FindingPriorityQueue` heap-backed; score = severity_weight
+  (high=100/med=10/low=1) × confidence_multiplier (0.5-1.0) +
+  age_boost (aging_multiplier × hours_elapsed) + manual_boost.
+  `boost()` / `remove_pattern()` / `snapshot()` helpers. Aging
+  prevents low-severity starvation.
+- **`vstack.snippet`** — minimal trace excerpts. `find_relevant_steps()`
+  uses token-overlap (lowercase, stopword-filtered, ≥3 chars)
+  between finding text and step content. `extract_snippet()` pulls
+  N context steps around relevant steps with omission counts.
+  `render_snippet()` produces markdown with `→` markers on relevant
+  steps + elision for long content.
+- **`vstack.aggregate`** — cross-report aggregation. `aggregate_reports()`
+  returns `AggregateSummary` with per-pattern stats (high/med/low
+  + severity_score), severity_counts, agent_counts.
+  `top_n_patterns()` / `top_n_agents()` (optionally severity-
+  filtered), `severity_distribution()`, `cooccurrence_matrix()`
+  (pairs that appear in the same report).
+
+### Changed
+
+- Test count: 3,014 → 3,127 (+113 from the five new modules).
+
+### Compatibility
+
+- All 3,127 tests pass (1 skipped: crewai not installed).
+- Public API surface strictly expanded.
+
 ## [0.35.0] — 2026-06-09
 
 Three more feature modules: alerting + eval_gates + intervention_tracker.

_aggregate/lib/__init__.py

@@ -0,0 +1,48 @@
+"""vstack.aggregate — cross-report aggregation utilities.
+
+Aggregate findings across many reports for fleet-level analysis:
+
+  - Top-N patterns by frequency.
+  - Severity distribution.
+  - Per-agent finding counts.
+  - Co-occurrence: which pattern pairs appear together?
+  - Trend: severity rate over time.
+
+Quick start
+-----------
+
+    from vstack.aggregate import (
+        aggregate_reports,
+        top_n_patterns,
+        cooccurrence_matrix,
+    )
+
+    summary = aggregate_reports(reports)
+    print(summary.total_findings, summary.unique_patterns)
+
+    top = top_n_patterns(reports, n=5)
+    for pattern, count in top:
+        print(pattern, count)
+"""
+
+from __future__ import annotations
+
+from ._aggregate import (
+    AggregateSummary,
+    PatternStats,
+    aggregate_reports,
+    cooccurrence_matrix,
+    severity_distribution,
+    top_n_agents,
+    top_n_patterns,
+)
+
+__all__ = [
+    "AggregateSummary",
+    "PatternStats",
+    "aggregate_reports",
+    "cooccurrence_matrix",
+    "severity_distribution",
+    "top_n_agents",
+    "top_n_patterns",
+]

_aggregate/lib/_aggregate.py

@@ -0,0 +1,190 @@
+"""Cross-report aggregation."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _get_findings(report: Any) -> list[Any]:
+    if isinstance(report, dict):
+        return list(report.get("findings", []))
+    if hasattr(report, "findings"):
+        return list(report.findings)
+    if isinstance(report, list):
+        return list(report)
+    return []
+
+
+def _f(finding: Any, field: str, default: Any = "") -> Any:
+    if isinstance(finding, dict):
+        return finding.get(field, default)
+    return getattr(finding, field, default)
+
+
+@dataclass
+class PatternStats:
+    """Per-pattern aggregate stats."""
+
+    pattern: str
+    total: int = 0
+    high: int = 0
+    medium: int = 0
+    low: int = 0
+
+    @property
+    def severity_score(self) -> float:
+        """Weighted severity (high=3, med=2, low=1)."""
+        return self.high * 3 + self.medium * 2 + self.low
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "pattern": self.pattern,
+            "total": self.total,
+            "high": self.high,
+            "medium": self.medium,
+            "low": self.low,
+            "severity_score": self.severity_score,
+        }
+
+
+@dataclass
+class AggregateSummary:
+    """Cross-report summary."""
+
+    total_reports: int = 0
+    total_findings: int = 0
+    unique_patterns: int = 0
+    pattern_stats: dict[str, PatternStats] = field(default_factory=dict)
+    severity_counts: dict[str, int] = field(default_factory=dict)
+    agent_counts: dict[str, int] = field(default_factory=dict)
+
+    def top_patterns(self, n: int = 10) -> list[PatternStats]:
+        items = sorted(
+            self.pattern_stats.values(),
+            key=lambda p: (-p.total, -p.severity_score, p.pattern),
+        )
+        return items[:n]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "total_reports": self.total_reports,
+            "total_findings": self.total_findings,
+            "unique_patterns": self.unique_patterns,
+            "pattern_stats": {k: v.to_dict() for k, v in self.pattern_stats.items()},
+            "severity_counts": dict(self.severity_counts),
+            "agent_counts": dict(self.agent_counts),
+        }
+
+
+def aggregate_reports(
+    reports: list[Any],
+    *,
+    agent_id_extractor: Any = None,
+) -> AggregateSummary:
+    """Cross-report aggregation.
+
+    Args:
+        reports: list of report objects (dict or attr-style).
+        agent_id_extractor: callable(report) → str. Default: pulls
+            'agent_id' from the report dict.
+    """
+    summary = AggregateSummary(total_reports=len(reports))
+
+    if agent_id_extractor is None:
+
+        def agent_id_extractor(r: Any) -> str:
+            if isinstance(r, dict):
+                return str(r.get("agent_id", "unknown"))
+            return str(getattr(r, "agent_id", "unknown"))
+
+    for report in reports:
+        findings = _get_findings(report)
+        agent = agent_id_extractor(report)
+
+        for finding in findings:
+            pattern = str(_f(finding, "pattern", "unknown"))
+            severity = str(_f(finding, "severity", "low"))
+
+            stats = summary.pattern_stats.setdefault(pattern, PatternStats(pattern=pattern))
+            stats.total += 1
+            if severity == "high":
+                stats.high += 1
+            elif severity == "medium":
+                stats.medium += 1
+            else:
+                stats.low += 1
+
+            summary.severity_counts[severity] = summary.severity_counts.get(severity, 0) + 1
+            summary.agent_counts[agent] = summary.agent_counts.get(agent, 0) + 1
+            summary.total_findings += 1
+
+    summary.unique_patterns = len(summary.pattern_stats)
+    return summary
+
+
+def top_n_patterns(reports: list[Any], n: int = 10) -> list[tuple[str, int]]:
+    """Return [(pattern, count)] for the top-N patterns by frequency."""
+    counter: Counter[str] = Counter()
+    for report in reports:
+        for finding in _get_findings(report):
+            pattern = str(_f(finding, "pattern", "unknown"))
+            counter[pattern] += 1
+    return counter.most_common(n)
+
+
+def top_n_agents(
+    reports: list[Any],
+    *,
+    n: int = 10,
+    severity: str | None = None,
+) -> list[tuple[str, int]]:
+    """Return [(agent_id, finding_count)] for the noisiest agents.
+
+    If ``severity`` is given, only count findings of that severity.
+    """
+    counter: Counter[str] = Counter()
+    for report in reports:
+        agent = "unknown"
+        if isinstance(report, dict):
+            agent = str(report.get("agent_id", "unknown"))
+        elif hasattr(report, "agent_id"):
+            agent = str(report.agent_id)
+
+        for finding in _get_findings(report):
+            if severity is not None and _f(finding, "severity") != severity:
+                continue
+            counter[agent] += 1
+    return counter.most_common(n)
+
+
+def severity_distribution(reports: list[Any]) -> dict[str, int]:
+    """Count of findings per severity bucket."""
+    dist: dict[str, int] = {"high": 0, "medium": 0, "low": 0}
+    for report in reports:
+        for finding in _get_findings(report):
+            severity = str(_f(finding, "severity", "low"))
+            dist[severity] = dist.get(severity, 0) + 1
+    return dist
+
+
+def cooccurrence_matrix(reports: list[Any]) -> dict[tuple[str, str], int]:
+    """Count co-occurrence of pattern pairs within the same report.
+
+    Returns a dict keyed by (pattern_a, pattern_b) where a < b
+    (tuples ordered canonically). Value = number of reports in
+    which both patterns appeared.
+    """
+    matrix: dict[tuple[str, str], int] = {}
+    for report in reports:
+        patterns = set()
+        for finding in _get_findings(report):
+            patterns.add(str(_f(finding, "pattern", "unknown")))
+        # All pairs.
+        plist = sorted(patterns)
+        for i, a in enumerate(plist):
+            for b in plist[i + 1 :]:
+                key = (a, b)
+                matrix[key] = matrix.get(key, 0) + 1
+    return matrix