capsule-engine 0.1.0__py3-none-any.whl

capsule_engine/telemetry/fixtures/synthetic_events.jsonl

@@ -0,0 +1,45 @@
+{"metric": "install_seen", "arm": "guards-only", "install_id": "synthetic-g1", "value": true, "emitted_at": "2026-08-05T00:00:00Z"}
+{"metric": "install_seen", "arm": "guards-only", "install_id": "synthetic-g2", "value": true, "emitted_at": "2026-08-05T00:00:01Z"}
+{"metric": "install_seen", "arm": "guards-only", "install_id": "synthetic-g3", "value": true, "emitted_at": "2026-08-05T00:00:02Z"}
+{"metric": "install_seen", "arm": "guards-only", "install_id": "synthetic-g4", "value": true, "emitted_at": "2026-08-05T00:00:03Z"}
+{"metric": "install_seen", "arm": "guards-only", "install_id": "synthetic-g5", "value": true, "emitted_at": "2026-08-05T00:00:04Z"}
+{"metric": "install_seen", "arm": "guards-only", "install_id": "synthetic-g6", "value": true, "emitted_at": "2026-08-05T00:00:05Z"}
+{"metric": "install_seen", "arm": "guards-only", "install_id": "synthetic-g7", "value": true, "emitted_at": "2026-08-05T00:00:06Z"}
+{"metric": "install_seen", "arm": "guards-only", "install_id": "synthetic-g8", "value": true, "emitted_at": "2026-08-05T00:00:07Z"}
+{"metric": "install_seen", "arm": "guards-only", "install_id": "synthetic-g9", "value": true, "emitted_at": "2026-08-05T00:00:08Z"}
+{"metric": "install_seen", "arm": "guards-only", "install_id": "synthetic-g10", "value": true, "emitted_at": "2026-08-05T00:00:09Z"}
+{"metric": "m1_activation", "arm": "guards-only", "install_id": "synthetic-g1", "value": true, "emitted_at": "2026-08-05T04:00:00Z"}
+{"metric": "m1_activation", "arm": "guards-only", "install_id": "synthetic-g2", "value": true, "emitted_at": "2026-08-05T04:00:01Z"}
+{"metric": "m1_activation", "arm": "guards-only", "install_id": "synthetic-g3", "value": true, "emitted_at": "2026-08-05T04:00:02Z"}
+{"metric": "m1_activation", "arm": "guards-only", "install_id": "synthetic-g4", "value": true, "emitted_at": "2026-08-05T04:00:03Z"}
+{"metric": "m2_enforcement_on", "arm": "guards-only", "install_id": "synthetic-g1", "value": true, "emitted_at": "2026-08-12T00:00:00Z"}
+{"metric": "m2_enforcement_on", "arm": "guards-only", "install_id": "synthetic-g2", "value": true, "emitted_at": "2026-08-12T00:00:01Z"}
+{"metric": "m3_day14_alive", "arm": "guards-only", "install_id": "synthetic-g1", "value": true, "emitted_at": "2026-08-18T00:00:00Z"}
+{"metric": "m3_day14_alive", "arm": "guards-only", "install_id": "synthetic-g2", "value": true, "emitted_at": "2026-08-18T00:00:01Z"}
+{"metric": "m3_day14_alive", "arm": "guards-only", "install_id": "synthetic-g3", "value": true, "emitted_at": "2026-08-18T00:00:02Z"}
+{"metric": "install_seen", "arm": "full", "install_id": "synthetic-f1", "value": true, "emitted_at": "2026-08-05T00:00:00Z"}
+{"metric": "install_seen", "arm": "full", "install_id": "synthetic-f2", "value": true, "emitted_at": "2026-08-05T00:00:01Z"}
+{"metric": "install_seen", "arm": "full", "install_id": "synthetic-f3", "value": true, "emitted_at": "2026-08-05T00:00:02Z"}
+{"metric": "install_seen", "arm": "full", "install_id": "synthetic-f4", "value": true, "emitted_at": "2026-08-05T00:00:03Z"}
+{"metric": "install_seen", "arm": "full", "install_id": "synthetic-f5", "value": true, "emitted_at": "2026-08-05T00:00:04Z"}
+{"metric": "install_seen", "arm": "full", "install_id": "synthetic-f6", "value": true, "emitted_at": "2026-08-05T00:00:05Z"}
+{"metric": "install_seen", "arm": "full", "install_id": "synthetic-f7", "value": true, "emitted_at": "2026-08-05T00:00:06Z"}
+{"metric": "install_seen", "arm": "full", "install_id": "synthetic-f8", "value": true, "emitted_at": "2026-08-05T00:00:07Z"}
+{"metric": "install_seen", "arm": "full", "install_id": "synthetic-f9", "value": true, "emitted_at": "2026-08-05T00:00:08Z"}
+{"metric": "install_seen", "arm": "full", "install_id": "synthetic-f10", "value": true, "emitted_at": "2026-08-05T00:00:09Z"}
+{"metric": "m1_activation", "arm": "full", "install_id": "synthetic-f1", "value": true, "emitted_at": "2026-08-05T04:00:00Z"}
+{"metric": "m1_activation", "arm": "full", "install_id": "synthetic-f2", "value": true, "emitted_at": "2026-08-05T04:00:01Z"}
+{"metric": "m1_activation", "arm": "full", "install_id": "synthetic-f3", "value": true, "emitted_at": "2026-08-05T04:00:02Z"}
+{"metric": "m1_activation", "arm": "full", "install_id": "synthetic-f4", "value": true, "emitted_at": "2026-08-05T04:00:03Z"}
+{"metric": "m1_activation", "arm": "full", "install_id": "synthetic-f5", "value": true, "emitted_at": "2026-08-05T04:00:04Z"}
+{"metric": "m2_enforcement_on", "arm": "full", "install_id": "synthetic-f1", "value": true, "emitted_at": "2026-08-12T00:00:00Z"}
+{"metric": "m3_day14_alive", "arm": "full", "install_id": "synthetic-f1", "value": true, "emitted_at": "2026-08-18T00:00:00Z"}
+{"metric": "m3_day14_alive", "arm": "full", "install_id": "synthetic-f2", "value": true, "emitted_at": "2026-08-18T00:00:01Z"}
+{"metric": "m5_evidence_pull", "arm": "full", "install_id": "synthetic-f1", "value": true, "emitted_at": "2026-08-06T00:00:00Z"}
+{"metric": "m5_evidence_pull", "arm": "full", "install_id": "synthetic-f3", "value": true, "emitted_at": "2026-08-06T00:00:01Z"}
+{"metric": "m6_report_opened", "report_token": "synthetic-tok-A", "emitted_at": "2026-08-06T00:00:00Z"}
+{"metric": "m6_report_opened", "report_token": "synthetic-tok-A", "emitted_at": "2026-08-06T01:00:00Z"}
+{"metric": "m6_report_opened", "report_token": "synthetic-tok-A", "emitted_at": "2026-08-06T02:00:00Z"}
+{"metric": "m6_report_opened", "report_token": "synthetic-tok-B", "emitted_at": "2026-08-07T00:00:00Z"}
+{"metric": "m6_report_opened", "report_token": "synthetic-tok-B", "emitted_at": "2026-08-07T05:00:00Z"}
+{"metric": "m6_report_opened", "report_token": "synthetic-tok-C", "emitted_at": "2026-08-08T00:00:00Z"}

capsule_engine/telemetry/funnel.py

@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The 6-metric funnel report: a reporting tool over already-collected
+telemetry events, not the collection itself. Renders exactly the six
+metrics this package's instrumentation emits, as raw counts/rates -- and
+nothing else. No pass/worry/fail banding, no thresholds, no verdict:
+turning a rate into a judgment is a decision made elsewhere, later,
+against a table this repository does not carry. See ``events.py``'s module
+docstring for the same point made about the events themselves.
+
+Two arms are always both present in the output (even a synthetic run with
+data for only one arm shows the other at 0/0) because the report's own
+shape -- what gets rendered -- must not depend on which arm happens to have
+data; only the numbers may vary.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from ..packaging import FULL, GUARDS_ONLY
+from .events import ALLOWED_FIELDS
+
+ARMS = (GUARDS_ONLY, FULL)
+
+__all__ = ["ArmMetric", "FunnelReport", "compute_funnel", "render_funnel_report"]
+
+
+@dataclass(frozen=True)
+class ArmMetric:
+    """A raw count out of a raw count. ``rate`` is arithmetic only --
+    ``None`` (not 0) when the denominator is 0, so a report never implies
+    "0%" for a metric that simply has no data yet."""
+
+    numerator: int
+    denominator: int
+
+    @property
+    def rate(self) -> float | None:
+        return (self.numerator / self.denominator) if self.denominator else None
+
+
+@dataclass(frozen=True)
+class FunnelReport:
+    m1_activation: dict[str, ArmMetric]
+    m2_enforcement_on: dict[str, ArmMetric]
+    m3_day14_alive: dict[str, ArmMetric]
+    m4_evidence_tax: float | None
+    m5_evidence_pull: ArmMetric
+    m6_viral_unit: int
+
+
+def _validate(raw: dict) -> None:
+    """Same schema check ``sink.emit`` applies on the way out -- re-applied
+    on the way in, so a funnel run over an untrusted/hand-edited events file
+    still cannot smuggle ledger-shaped content into the report."""
+    if set(raw) - {"report_token"} - ALLOWED_FIELDS:
+        raise ValueError(f"telemetry event carries unexpected fields: {set(raw) - ALLOWED_FIELDS - {'report_token'}}")
+
+
+def compute_funnel(raw_events: Iterable[dict]) -> FunnelReport:
+    installs_seen: dict[str, set[str]] = defaultdict(set)  # arm -> install_ids
+    activated: dict[str, set[str]] = defaultdict(set)
+    enforced: dict[str, set[str]] = defaultdict(set)
+    alive: dict[str, set[str]] = defaultdict(set)
+    evidence_pulled: set[str] = set()
+    report_opens: dict[str, int] = defaultdict(int)
+
+    for raw in raw_events:
+        _validate(raw)
+        metric = raw.get("metric")
+        arm = raw.get("arm")
+        install_id = raw.get("install_id")
+        value = raw.get("value")
+
+        if metric == "m6_report_opened":
+            token = raw.get("report_token")
+            if token:
+                report_opens[token] += 1
+            continue
+
+        if arm not in ARMS or not install_id:
+            continue
+        if metric == "install_seen":
+            installs_seen[arm].add(install_id)
+        elif metric == "m1_activation" and value:
+            activated[arm].add(install_id)
+        elif metric == "m2_enforcement_on" and value:
+            enforced[arm].add(install_id)
+        elif metric == "m3_day14_alive" and value:
+            alive[arm].add(install_id)
+        elif metric == "m5_evidence_pull" and value:
+            evidence_pulled.add(install_id)
+
+    m1 = {arm: ArmMetric(len(activated[arm]), len(installs_seen[arm])) for arm in ARMS}
+    m2 = {arm: ArmMetric(len(enforced[arm]), len(activated[arm])) for arm in ARMS}
+    m3 = {arm: ArmMetric(len(alive[arm]), len(activated[arm])) for arm in ARMS}
+
+    guards_only_rate = m1["guards-only"].rate
+    full_rate = m1["full"].rate
+    m4 = (full_rate / guards_only_rate) if guards_only_rate else None
+
+    m5 = ArmMetric(len(evidence_pulled & activated["full"]), len(activated["full"]))
+
+    m6 = sum(1 for count in report_opens.values() if count >= 2)
+
+    return FunnelReport(
+        m1_activation=m1,
+        m2_enforcement_on=m2,
+        m3_day14_alive=m3,
+        m4_evidence_tax=m4,
+        m5_evidence_pull=m5,
+        m6_viral_unit=m6,
+    )
+
+
+def _fmt_rate(metric: ArmMetric) -> str:
+    if metric.rate is None:
+        return f"n/a ({metric.numerator}/{metric.denominator})"
+    return f"{metric.rate:.1%} ({metric.numerator}/{metric.denominator})"
+
+
+def render_funnel_report(report: FunnelReport) -> str:
+    """Plain text: the six metrics, and nothing else."""
+    lines = ["capsule-ledger two-arm funnel report", "=" * 33, ""]
+
+    def arm_line(label: str, metrics: dict[str, ArmMetric]) -> None:
+        lines.append(label)
+        for arm in ARMS:
+            lines.append(f"  {arm:<11} {_fmt_rate(metrics[arm])}")
+
+    arm_line("M1 activation (>=1 guard configured near install)", report.m1_activation)
+    lines.append("")
+    arm_line("M2 enforcement-on (dry_run -> enforce, of activated)", report.m2_enforcement_on)
+    lines.append("")
+    arm_line("M3 day-14-alive (guard evaluated recently, of activated)", report.m3_day14_alive)
+    lines.append("")
+    lines.append("M4 evidence tax (full M1 rate / guards-only M1 rate)")
+    lines.append(f"  {report.m4_evidence_tax:.2f}" if report.m4_evidence_tax is not None else "  n/a")
+    lines.append("")
+    lines.append("M5 evidence-pull (full arm only, of activated)")
+    lines.append(f"  {_fmt_rate(report.m5_evidence_pull)}")
+    lines.append("")
+    lines.append("M6 viral unit (share link opened by a distinct second party)")
+    lines.append(f"  {report.m6_viral_unit} distinct instance(s)")
+    lines.append("")
+    return "\n".join(lines)

capsule_engine/telemetry/record.py

@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CLI-facing hooks: update local state idempotently, emit the corresponding
+metric event -- all of it, including the local state file itself, gated on
+``consent.is_opted_in()``. An install that never opts in leaves no
+telemetry footprint at all: no state file, no local bookkeeping, nothing.
+
+Each function only ever fires its event the first time the underlying fact
+becomes true for this install (a guard is "configured" once; re-running
+``guard dry-run --cap ...`` a second time updates nothing and emits
+nothing new) -- these are one-shot facts, matching what ``events.py``'s
+docstring says M1/M2/M5 are. ``record_guard_evaluated`` re-affirms
+"alive" on every real evaluation (the state timestamp always advances) but
+is still summarized centrally as a single per-install yes/no fact (M3), not
+a per-evaluation count. ``record_install_seen`` is not one of the six
+metrics -- it is the denominator bookkeeping (this install exists, in this
+arm) the central funnel report needs to turn the six one-shot facts into
+rates; see ``funnel.py``.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from . import events
+from .consent import is_opted_in
+from .sink import EventSink, emit
+from .state import TelemetryState, load_state, save_state
+
+__all__ = [
+    "record_install_seen",
+    "record_guard_configured",
+    "record_enforcement_flip",
+    "record_guard_evaluated",
+    "record_evidence_touch",
+]
+
+_INSTALL_SEEN_METRIC = "install_seen"
+
+
+def _now_utc() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _emit_bookkeeping(install_id: str, arm: str, *, sink: EventSink | None) -> None:
+    """Not one of the six metrics -- the denominator fact an install exists
+    in a given arm, so the funnel report can turn one-shot facts into rates
+    without needing an external cohort list."""
+    emit(
+        events.MetricEvent(metric=_INSTALL_SEEN_METRIC, arm=arm, install_id=install_id, value=True, emitted_at=_now_utc()),
+        opted_in=True,
+        sink=sink,
+    )
+
+
+def record_install_seen(arm: str, *, sink: EventSink | None = None) -> None:
+    if not is_opted_in():
+        return
+    s = load_state()
+    _emit_bookkeeping(s.install_id, arm, sink=sink)
+
+
+def record_guard_configured(arm: str, *, sink: EventSink | None = None, state: TelemetryState | None = None) -> None:
+    if not is_opted_in():
+        return
+    s = state or load_state()
+    if s.first_guard_configured_at is not None:
+        return
+    s.first_guard_configured_at = _now_utc()
+    save_state(s)
+    emit(events.m1_activation_event(install_id=s.install_id, arm=arm), opted_in=True, sink=sink)
+
+
+def record_enforcement_flip(arm: str, *, sink: EventSink | None = None, state: TelemetryState | None = None) -> None:
+    if not is_opted_in():
+        return
+    s = state or load_state()
+    if s.enforce_flipped_at is not None:
+        return
+    s.enforce_flipped_at = _now_utc()
+    save_state(s)
+    emit(events.m2_enforcement_on_event(install_id=s.install_id, arm=arm), opted_in=True, sink=sink)
+
+
+def record_guard_evaluated(arm: str, *, sink: EventSink | None = None, state: TelemetryState | None = None) -> None:
+    if not is_opted_in():
+        return
+    s = state or load_state()
+    already_alive = s.last_guard_evaluated_at is not None
+    s.last_guard_evaluated_at = _now_utc()
+    save_state(s)
+    if not already_alive:
+        emit(events.m3_day14_alive_event(install_id=s.install_id, arm=arm), opted_in=True, sink=sink)
+
+
+def record_evidence_touch(arm: str, *, sink: EventSink | None = None, state: TelemetryState | None = None) -> None:
+    """M5, full arm only -- callers already gate this on the arm (the
+    evidence-surfacing commands are only registered in the full arm), but
+    this function re-asserts it so a future caller can't emit a
+    meaningless guards-only M5 fact by mistake."""
+    if arm != "full" or not is_opted_in():
+        return
+    s = state or load_state()
+    if s.evidence_touched_at is not None:
+        return
+    s.evidence_touched_at = _now_utc()
+    save_state(s)
+    emit(events.m5_evidence_pull_event(install_id=s.install_id, arm=arm), opted_in=True, sink=sink)

capsule_engine/telemetry/sink.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Where an opted-in event goes. No sink here ever makes a network call --
+this package ships no telemetry backend and points at none by default; a
+real transport is a deployment-time concern for whoever operates one,
+wired in by passing a different ``EventSink``, never by editing this file.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Protocol
+
+from ..envcompat import env_get
+from .events import ALLOWED_FIELDS, MetricEvent
+
+__all__ = ["EventSink", "NullSink", "LocalJSONLSink", "default_sink", "emit"]
+
+
+class EventSink(Protocol):
+    def write(self, event: MetricEvent) -> None: ...
+
+
+class NullSink:
+    """The default: opted-in or not, nothing leaves this process."""
+
+    def write(self, event: MetricEvent) -> None:
+        return None
+
+
+class LocalJSONLSink:
+    """Append-only local file, one JSON object per line. Intended for
+    operators who want to inspect or forward their own install's telemetry
+    themselves -- this package never reads this file back or transmits it."""
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+
+    def write(self, event: MetricEvent) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        with self._path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(event.to_dict(), sort_keys=True) + "\n")
+
+
+def default_sink() -> EventSink:
+    path = env_get("CAPSULE_LEDGER_TELEMETRY_SINK_PATH")
+    return LocalJSONLSink(path) if path else NullSink()
+
+
+def emit(event: MetricEvent, *, opted_in: bool, sink: EventSink | None = None) -> bool:
+    """Write ``event`` to ``sink`` iff ``opted_in``. Returns whether it was
+    written. Re-validates the payload's keys against the fixed schema before
+    writing -- belt and suspenders alongside ``MetricEvent`` itself being a
+    closed dataclass, so a future edit to this module can't silently widen
+    what a payload may carry."""
+    if not opted_in:
+        return False
+    payload = event.to_dict()
+    if set(payload) != ALLOWED_FIELDS:
+        raise ValueError(f"telemetry payload carries unexpected fields: {set(payload) - ALLOWED_FIELDS}")
+    (sink or default_sink()).write(event)
+    return True

capsule_engine/telemetry/state.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Local, per-install state the six metrics are computed from.
+
+Stored as a small JSON file outside the ledger and outside any repo --
+never ledger data, never PII: a random install id and a handful of "first
+time this happened" timestamps. Written regardless of telemetry opt-in (the
+facts are needed locally either way, e.g. for ``capsule telemetry status``);
+whether they are ever *emitted* anywhere is gated separately by
+``consent.is_opted_in()``.
+"""
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import asdict, dataclass, fields
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ..envcompat import env_get
+
+__all__ = ["TelemetryState", "state_path", "load_state", "save_state"]
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def state_path() -> Path:
+    override = env_get("CAPSULE_LEDGER_STATE_DIR")
+    base = Path(override) if override else Path.home() / ".local" / "state" / "capsule-ledger"
+    return base / "telemetry_state.json"
+
+
+@dataclass
+class TelemetryState:
+    install_id: str
+    install_at: str
+    first_guard_configured_at: str | None = None
+    enforce_flipped_at: str | None = None
+    last_guard_evaluated_at: str | None = None
+    evidence_touched_at: str | None = None
+
+
+def load_state(path: Path | None = None) -> TelemetryState:
+    """Load the local state, creating it (a fresh random install id, "now"
+    as the install timestamp) on first ever call."""
+    p = path or state_path()
+    if p.exists():
+        raw = json.loads(p.read_text(encoding="utf-8"))
+        known = {f.name for f in fields(TelemetryState)}
+        return TelemetryState(**{k: v for k, v in raw.items() if k in known})
+    state = TelemetryState(install_id=str(uuid.uuid4()), install_at=_utc_now())
+    save_state(state, p)
+    return state
+
+
+def save_state(state: TelemetryState, path: Path | None = None) -> None:
+    p = path or state_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(asdict(state), indent=2, sort_keys=True), encoding="utf-8")