phase-loop-runtime 0.2.0__py3-none-any.whl

phase_loop_runtime/fleet_metrics.py

@@ -0,0 +1,298 @@
+"""CS-2.1 SA — fleet-metric ledger emission + pure derivation.
+
+This is the enforcement-side PUSH source for the three LEDGER-FAITHFUL named
+fleet-trend metrics the CS-2.1 spine reserved (velocity / burn_down /
+promise_broken_duration). It is additive observability on the harness's OWN
+ledger:
+
+  * Events are appended to a SEPARATE sibling ledger,
+    ``.phase-loop/fleet-metrics.jsonl`` — ``events.jsonl`` is never touched, so
+    its bytes, digests, and reconcile/fold semantics are provably unaffected.
+  * Every append is a single ``os.write`` on an ``O_APPEND`` fd (mirrors
+    ``events._append_jsonl`` and ``train_ledger.append_record``).
+  * Derivation is pure (no I/O) so the velocity/burn_down/promise-broken-duration
+    series are unit-testable without a runner or a database.
+
+The load-bearing boundary: this file lives on the ENFORCEMENT side of the
+``.phase-loop`` wall. Portal never reads it. Only the sanitized aggregate
+series (see ``fleet_metrics_export``) crosses to Portal, one-way.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+from .models import FleetMetricEvent
+from .runtime_paths import (
+    ensure_phase_loop_excluded,
+    phase_loop_fleet_metrics_file,
+    phase_loop_fleet_metrics_read_files,
+)
+
+
+# ── append + read (the sibling ledger) ─────────────────────────────────────
+
+def fleet_metrics_path(repo: Path) -> Path:
+    return phase_loop_fleet_metrics_file(repo)
+
+
+def append_fleet_metric(repo: Path, event: FleetMetricEvent) -> None:
+    """Atomically append one fleet-metric event to the sibling ledger."""
+    ensure_phase_loop_excluded(repo)
+    path = fleet_metrics_path(repo)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    encoded = (json.dumps(event.to_json(), sort_keys=True) + "\n").encode("utf-8")
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o666)
+    try:
+        os.write(fd, encoded)
+    finally:
+        os.close(fd)
+
+
+def read_fleet_metrics(repo: Path) -> list[dict[str, Any]]:
+    """Tolerant reader: skips blank/malformed lines, keeps only fleet_metric records."""
+    records: list[dict[str, Any]] = []
+    for path in phase_loop_fleet_metrics_read_files(repo):
+        if not path.exists():
+            continue
+        with path.open(encoding="utf-8") as handle:
+            for line in handle:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    record = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if isinstance(record, dict) and record.get("event_kind") == "fleet_metric":
+                    records.append(record)
+    return records
+
+
+# ── runner hook — emit at closeout ─────────────────────────────────────────
+
+def record_phase_fleet_metrics(
+    repo: Path,
+    *,
+    phase: str,
+    completed: bool,
+    total_scope: int,
+    completed_count: int,
+    missing_gates: Iterable[str] = (),
+    produced_gates: Iterable[str] = (),
+    timestamp: str | None = None,
+) -> list[FleetMetricEvent]:
+    """Emit the fleet-metric events implied by one phase closeout.
+
+    Truth sources (all already known at the closeout site, runner.py):
+      * ``completed`` / ``completed_count`` / ``total_scope`` — velocity + burn_down.
+      * ``missing_gates`` (declared-but-not-produced, from ``validate_produced_gates``)
+        — a BROKEN promise per gate.
+      * ``produced_gates`` that had an earlier unmatched ``promise_broken`` — a
+        REPAIRED promise (break-anchored, so duration is broken→repaired, never
+        mere fulfillment lead-time).
+
+    Best-effort: callers wrap this so observability can never break the loop.
+    """
+    ts = timestamp or _utc_now()
+    emitted: list[FleetMetricEvent] = []
+
+    if completed:
+        emitted.append(
+            FleetMetricEvent(
+                metric_kind="velocity",
+                timestamp=ts,
+                phase=phase,
+                payload={"completed_total": int(completed_count)},
+            )
+        )
+        remaining = max(0, int(total_scope) - int(completed_count))
+        emitted.append(
+            FleetMetricEvent(
+                metric_kind="burn_down",
+                timestamp=ts,
+                phase=phase,
+                payload={
+                    "total_scope": int(total_scope),
+                    "completed": int(completed_count),
+                    "remaining": remaining,
+                },
+            )
+        )
+
+    # Which gates are currently open breaks (declared-but-not-produced without a
+    # later repair) — computed from the ledger so repairs are break-anchored.
+    open_breaks = _open_promise_breaks(read_fleet_metrics(repo))
+    missing = [str(g) for g in missing_gates if str(g).strip()]
+    produced = {str(g) for g in produced_gates if str(g).strip()}
+
+    for gate in missing:
+        if gate in open_breaks:
+            continue  # already an open break — don't double-count
+        emitted.append(
+            FleetMetricEvent(
+                metric_kind="promise_broken",
+                timestamp=ts,
+                phase=phase,
+                payload={"gate": gate},
+            )
+        )
+        open_breaks[gate] = ts
+
+    for gate in sorted(produced):
+        if gate in open_breaks:
+            emitted.append(
+                FleetMetricEvent(
+                    metric_kind="promise_repaired",
+                    timestamp=ts,
+                    phase=phase,
+                    payload={"gate": gate},
+                )
+            )
+            open_breaks.pop(gate, None)
+
+    for event in emitted:
+        append_fleet_metric(repo, event)
+    return emitted
+
+
+def _open_promise_breaks(records: Iterable[dict[str, Any]]) -> dict[str, str]:
+    """Fold the ledger to gates with an open break (break with no later repair).
+
+    Returns ``{gate: broken_at_ts}``. Records are in append order.
+    """
+    open_at: dict[str, str] = {}
+    for record in records:
+        kind = record.get("metric_kind")
+        gate = str((record.get("payload") or {}).get("gate") or "").strip()
+        if not gate:
+            continue
+        if kind == "promise_broken":
+            open_at.setdefault(gate, str(record.get("timestamp") or ""))
+        elif kind == "promise_repaired":
+            open_at.pop(gate, None)
+    return open_at
+
+
+# ── pure derivation — the sanitizable aggregate series ─────────────────────
+
+def derive_fleet_metric_series(
+    records: Iterable[dict[str, Any]],
+    *,
+    now: str | None = None,
+) -> dict[str, Any]:
+    """Fold fleet-metric records into ledger-faithful aggregate time-series.
+
+    Pure: no I/O. Output contains ONLY numeric aggregates + ISO timestamps +
+    fixed enum labels — no gate identifiers, paths, secrets, or payloads. This
+    is exactly what the export bridge is allowed to push to Portal.
+    """
+    records = list(records)
+    now_ts = now or _utc_now()
+
+    velocity_points: list[dict[str, Any]] = []
+    burndown_points: list[dict[str, Any]] = []
+    # Break/repair pairing keyed by gate (gate id stays LOCAL — only durations leave).
+    break_open: dict[str, str] = {}
+    repaired_durations: list[float] = []
+    open_break_started: dict[str, str] = {}
+
+    for record in records:
+        kind = record.get("metric_kind")
+        ts = str(record.get("timestamp") or "")
+        payload = record.get("payload") or {}
+        if kind == "velocity":
+            velocity_points.append(
+                {"t": ts, "completed_total": int(payload.get("completed_total") or 0)}
+            )
+        elif kind == "burn_down":
+            burndown_points.append(
+                {
+                    "t": ts,
+                    "total": int(payload.get("total_scope") or 0),
+                    "completed": int(payload.get("completed") or 0),
+                    "remaining": int(payload.get("remaining") or 0),
+                }
+            )
+        elif kind == "promise_broken":
+            gate = str(payload.get("gate") or "")
+            if gate:
+                break_open.setdefault(gate, ts)
+                open_break_started.setdefault(gate, ts)
+        elif kind == "promise_repaired":
+            gate = str(payload.get("gate") or "")
+            started = break_open.pop(gate, None)
+            open_break_started.pop(gate, None)
+            if started:
+                repaired_durations.append(_seconds_between(started, ts))
+
+    # promise_broken_duration series: one point per broken promise carrying only
+    # its duration (seconds) + whether it was repaired — never the gate id.
+    broken_points: list[dict[str, Any]] = []
+    # Re-walk to preserve order + emit repaired ones with their measured duration.
+    replay_open: dict[str, str] = {}
+    for record in records:
+        kind = record.get("metric_kind")
+        ts = str(record.get("timestamp") or "")
+        gate = str((record.get("payload") or {}).get("gate") or "")
+        if kind == "promise_broken" and gate:
+            replay_open.setdefault(gate, ts)
+        elif kind == "promise_repaired" and gate and gate in replay_open:
+            started = replay_open.pop(gate)
+            broken_points.append(
+                {"t": ts, "broken_seconds": _seconds_between(started, ts), "repaired": True}
+            )
+    # Still-open breaks: duration measured to `now`.
+    for gate, started in sorted(open_break_started.items()):
+        broken_points.append(
+            {"t": now_ts, "broken_seconds": _seconds_between(started, now_ts), "repaired": False}
+        )
+
+    open_count = len(open_break_started)
+    open_seconds = [
+        _seconds_between(started, now_ts) for started in open_break_started.values()
+    ]
+    mean_repaired = (
+        round(sum(repaired_durations) / len(repaired_durations), 3)
+        if repaired_durations
+        else None
+    )
+
+    return {
+        "velocity": {"points": velocity_points},
+        "burn_down": {"points": burndown_points},
+        "promise_broken_duration": {
+            "points": broken_points,
+            "aggregate": {
+                "open_count": open_count,
+                "max_open_seconds": round(max(open_seconds), 3) if open_seconds else 0,
+                "mean_repaired_seconds": mean_repaired,
+                "repaired_count": len(repaired_durations),
+            },
+        },
+    }
+
+
+def _seconds_between(start_ts: str, end_ts: str) -> float:
+    try:
+        start = _parse_ts(start_ts)
+        end = _parse_ts(end_ts)
+    except ValueError:
+        return 0.0
+    return max(0.0, round((end - start).total_seconds(), 3))
+
+
+def _parse_ts(value: str) -> datetime:
+    text = value.strip().replace("Z", "+00:00")
+    parsed = datetime.fromisoformat(text)
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")

phase_loop_runtime/fleet_metrics_export.py

@@ -0,0 +1,196 @@
+"""CS-2.1 SA — the one-way SANITIZED export bridge (enforcement → Portal).
+
+This is the PUSH side of the ``.phase-loop`` wall. Enforcement computes the
+ledger-faithful aggregate series (``fleet_metrics.derive_fleet_metric_series``)
+and pushes ONLY sanitized aggregates + timestamps to Portal's control-plane
+ingest. Portal never reaches back into ``.phase-loop`` — the direction is
+strictly enforcement → Portal.
+
+Sanitization is PROVABLE, not incidental: :func:`build_sanitized_export` runs
+every payload through :func:`assert_sanitized`, which fails closed if any leaf
+value looks like a filesystem path, a ``.phase-loop`` / ``events.jsonl``
+reference, a secret, or a raw session payload. The named metrics only ever carry
+numbers, ISO-8601 timestamps, and a fixed set of enum labels.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from .fleet_metrics import derive_fleet_metric_series, read_fleet_metrics
+
+
+EXPORT_SCHEMA = "fleet_metrics_export.v1"
+
+# The complete set of NAMED ledger-faithful series this bridge is allowed to
+# push. Matches the series_kinds the CS-2.1 spine reserved for `ledger-faithful`.
+NAMED_SERIES = ("velocity", "burn_down", "promise_broken_duration")
+
+# A repo id is a control-plane LABEL, never a path — enforce a slug shape.
+_REPO_SLUG_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+
+# ISO-8601 UTC timestamps are the only strings allowed as leaf *values* (besides
+# the fixed enum labels), so a stray path can never masquerade as a timestamp.
+_ISO_TS_RE = re.compile(
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$"
+)
+
+# Substrings that must NEVER appear anywhere in the payload — the wall markers
+# plus common secret/path tells. A hit is a hard sanitization failure.
+_FORBIDDEN_SUBSTRINGS = (
+    "/",
+    "\\",
+    ".phase-loop",
+    "events.jsonl",
+    "state.json",
+    "secret",
+    "token",
+    "api_key",
+    "authorization",
+    "password",
+    "session",
+    "prompt",
+)
+
+# Keys allowed to appear in the payload tree. Anything else (e.g. a raw "path",
+# "gate", "payload", "command" field) is a sanitization failure — this is what
+# stops raw ledger internals from leaking.
+_ALLOWED_KEYS = frozenset(
+    {
+        "schema",
+        "repo",
+        "captured_at",
+        "series",
+        "series_kind",
+        "provenance",
+        "points",
+        "aggregate",
+        # numeric/label leaves inside points + aggregate:
+        "t",
+        "completed_total",
+        "total",
+        "completed",
+        "remaining",
+        "broken_seconds",
+        "repaired",
+        "open_count",
+        "max_open_seconds",
+        "mean_repaired_seconds",
+        "repaired_count",
+    }
+)
+
+
+class SanitizationError(ValueError):
+    """Raised when an export payload carries a forbidden path/secret/payload field."""
+
+
+def build_export_payload(repo_id: str, series: dict[str, Any], captured_at: str) -> dict[str, Any]:
+    """Shape the derived series into the ``fleet_metrics_export.v1`` wire payload.
+
+    Every pushed series is ``provenance: ledger-faithful`` — the DB CHECK on the
+    Portal side binds these three series_kinds to exactly that provenance.
+    """
+    if not _REPO_SLUG_RE.match(repo_id):
+        raise SanitizationError(f"repo id is not a control-plane slug: {repo_id!r}")
+    return {
+        "schema": EXPORT_SCHEMA,
+        "repo": repo_id,
+        "captured_at": captured_at,
+        "series": [
+            {
+                "series_kind": name,
+                "provenance": "ledger-faithful",
+                **series.get(name, {}),
+            }
+            for name in NAMED_SERIES
+        ],
+    }
+
+
+def build_sanitized_export(repo: Path, *, repo_id: str, captured_at: str) -> dict[str, Any]:
+    """Read the enforcement ledger, derive the series, and return a proven-sanitized payload."""
+    series = derive_fleet_metric_series(read_fleet_metrics(repo), now=captured_at)
+    payload = build_export_payload(repo_id, series, captured_at)
+    assert_sanitized(payload)
+    return payload
+
+
+def assert_sanitized(payload: Any, *, _path: str = "$") -> None:
+    """Fail closed unless every node is a numeric aggregate, ISO timestamp, or fixed label.
+
+    Walks the whole tree:
+      * dict keys must be in ``_ALLOWED_KEYS``;
+      * every string value must be an allowed enum label or a strict ISO-8601
+        timestamp — and must contain no forbidden substring;
+      * numbers/bools/None pass; nested lists/dicts recurse.
+    """
+    if isinstance(payload, dict):
+        for key, value in payload.items():
+            if key not in _ALLOWED_KEYS:
+                raise SanitizationError(f"forbidden key at {_path}.{key}")
+            assert_sanitized(value, _path=f"{_path}.{key}")
+        return
+    if isinstance(payload, (list, tuple)):
+        for i, item in enumerate(payload):
+            assert_sanitized(item, _path=f"{_path}[{i}]")
+        return
+    if isinstance(payload, bool) or payload is None:
+        return
+    if isinstance(payload, (int, float)):
+        return
+    if isinstance(payload, str):
+        lowered = payload.lower()
+        for bad in _FORBIDDEN_SUBSTRINGS:
+            if bad in lowered:
+                raise SanitizationError(f"forbidden substring {bad!r} at {_path}: {payload!r}")
+        if payload in _ALLOWED_LABELS or _ISO_TS_RE.match(payload):
+            return
+        # The one free-form string is the control-plane repo LABEL, allowed only
+        # under the `$.repo` key and only if it is a slug (no path/secret shape).
+        if _path == "$.repo" and _REPO_SLUG_RE.match(payload):
+            return
+        raise SanitizationError(f"non-timestamp, non-label string at {_path}: {payload!r}")
+    raise SanitizationError(f"unsupported leaf type {type(payload).__name__} at {_path}")
+
+
+# Fixed enum labels permitted as string leaf VALUES (schema/provenance/kind/repo).
+# Note: repo ids are validated separately by shape; the wall markers can never be
+# a repo id because a slug forbids "/".
+_ALLOWED_LABELS = frozenset({EXPORT_SCHEMA, "ledger-faithful", *NAMED_SERIES})
+
+
+def push_export(
+    url: str,
+    payload: dict[str, Any],
+    *,
+    ingest_key: str,
+    timeout: float = 15.0,
+) -> int:
+    """One-way HTTP POST of a proven-sanitized payload to Portal's ingest route.
+
+    Fails closed on missing url/key. Re-asserts sanitization immediately before
+    the wire write so nothing unsanitized can ever leave, even if a caller built
+    the payload by hand. Returns the HTTP status code.
+    """
+    if not url:
+        raise ValueError("fleet-metrics export url is not configured")
+    if not ingest_key:
+        raise ValueError("fleet-metrics export ingest key is not configured")
+    assert_sanitized(payload)
+    body = json.dumps(payload, sort_keys=True).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=body,
+        method="POST",
+        headers={
+            "content-type": "application/json",
+            "x-ledger-export-key": ingest_key,
+        },
+    )
+    with urllib.request.urlopen(request, timeout=timeout) as response:  # noqa: S310 (trusted control-plane url)
+        return int(response.status)