cli-consumption 0.0.7__tar.gz → 0.0.9__tar.gz

{cli_consumption-0.0.7 → cli_consumption-0.0.9}/.agents/skills/yolo/SKILL.md

@@ -10,9 +10,11 @@ Run each phase in order from the repository root. The implicit pull request is t
 ## 1. Publish
 
 1. Read all repository instructions and the product specification referenced by `AGENTS.md`.
-2. Load and follow `$yeet-github` in full to inspect, validate, commit, push, and open a draft pull request, except do not request its approval before pushing or publishing: the explicit `$yolo` invocation already provides that approval.
-3. Retain the exact source and target branches, pushed SHA, pull-request number, and URL.
-4. Stop after any failure or ambiguous external result. Never merge or clean up after a partial failure.
+2. Read `.agents/local-environment.md` when present and follow its GitHub authentication instructions.
+3. Load and follow `$yeet-github` in full to inspect, validate, commit, push, and open a draft pull request, except do not request its approval before pushing or publishing: the explicit `$yolo` invocation already provides that approval.
+4. Use `gh` directly for GitHub API and pull-request operations. When Git transport is unavoidable and the remote is HTTPS, authenticate it explicitly through the current `gh` session, for example `git -c credential.helper='!gh auth git-credential' push -u origin <source-branch>`; never rely on ambient HTTPS Git credentials.
+5. Retain the exact source and target branches, pushed SHA, pull-request number, and URL.
+6. Stop after any failure or ambiguous external result. Never merge or clean up after a partial failure.
 
 ## 2. Merge
 
@@ -29,10 +31,10 @@ Run each phase in order from the repository root. The implicit pull request is t
 
 1. Reconfirm the merged state and capture the merge commit SHA.
 2. Refuse cleanup if new tracked, staged, or untracked work appeared after the source commit.
-3. Run `git fetch --prune origin`.
+3. Fetch with the authentication method required by `.agents/local-environment.md`; for an HTTPS GitHub remote, use `git -c credential.helper='!gh auth git-credential' fetch --prune origin`.
 4. Switch to the target branch and update it only by fast-forward with `git switch <target-branch>` and `git pull --ff-only origin <target-branch>`.
 5. Delete the exact local source branch if it remains. `git branch -D <source-branch>` is allowed only after verified squash merge.
-6. If the exact unprotected remote source branch remains, delete it with `git push origin --delete <source-branch>` without requesting additional approval.
+6. If the exact unprotected remote source branch remains, delete it without requesting additional approval. For an HTTPS GitHub remote, use `git -c credential.helper='!gh auth git-credential' push origin --delete <source-branch>`.
 7. Run `git status --short --branch` and report the final state.
 
 ## Guardrails

{cli_consumption-0.0.7 → cli_consumption-0.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-consumption
-Version: 0.0.7
+Version: 0.0.9
 Summary: Analyze and consolidate AI coding CLI consumption across machines.
 Project-URL: Homepage, https://github.com/Guillaume-Lombardo/cli-consumption
 Project-URL: Documentation, https://github.com/Guillaume-Lombardo/cli-consumption#readme
@@ -33,8 +33,8 @@ models, tokens, tools, conversations, and turns. It can analyze one workstation,
 consolidate copied data from several machines, or send metadata-only snapshots to a
 central collector.
 
-Codex, Gemini CLI, Kilo Code, Pi, OpenCode, and the core Claude Code local transcript
-format are supported.
+Codex, Aider, Gemini CLI, Goose, Kilo Code, Pi, OpenCode, and the core Claude Code
+local transcript format are supported.
 
 The collector deliberately excludes prompts, responses, tool arguments, and
 credentials. See [Privacy](docs/privacy.md) before sharing a database or export.
@@ -114,6 +114,12 @@ Select Kilo Code to read `~/.local/share/kilo/kilo.db` instead:
 uv run cli-consumption collect --provider kilo --database usage.sqlite
 ```
 
+Select Goose to read `~/.local/share/goose/sessions/sessions.db` instead:
+
+```bash
+uv run cli-consumption collect --provider goose --database usage.sqlite
+```
+
 Select Pi to read `~/.pi/agent/sessions/` instead:
 
 ```bash
@@ -126,6 +132,14 @@ Select Gemini CLI to read `~/.gemini/tmp/*/chats/` instead:
 uv run cli-consumption collect --provider gemini --database usage.sqlite
 ```
 
+Select Aider to read a local analytics log configured at
+`~/.aider/analytics.jsonl` instead:
+
+```bash
+export AIDER_ANALYTICS_LOG="$HOME/.aider/analytics.jsonl"
+uv run cli-consumption collect --provider aider --database usage.sqlite
+```
+
 Use `all` to detect and collect every supported provider present on the machine:
 
 ```bash
@@ -182,6 +196,14 @@ uv run cli-consumption collect --provider kilo \
   --source laptop=/data/kilo/laptop
 ```
 
+Copied Goose sources point to the sessions directory containing `sessions.db`:
+
+```bash
+uv run cli-consumption collect --provider goose \
+  --source desktop=/data/goose/desktop \
+  --source laptop=/data/goose/laptop
+```
+
 Copied Pi sources point to the agent directory containing `sessions/`:
 
 ```bash
@@ -198,6 +220,14 @@ uv run cli-consumption collect --provider gemini \
   --source laptop=/data/gemini/laptop
 ```
 
+Copied Aider sources point to a directory containing `analytics.jsonl`:
+
+```bash
+uv run cli-consumption collect --provider aider \
+  --source desktop=/data/aider/desktop \
+  --source laptop=/data/aider/laptop
+```
+
 ## SQLite and PostgreSQL
 
 A file path selects SQLite. A SQLAlchemy URL selects PostgreSQL:

{cli_consumption-0.0.7 → cli_consumption-0.0.9}/README.md

@@ -5,8 +5,8 @@ models, tokens, tools, conversations, and turns. It can analyze one workstation,
 consolidate copied data from several machines, or send metadata-only snapshots to a
 central collector.
 
-Codex, Gemini CLI, Kilo Code, Pi, OpenCode, and the core Claude Code local transcript
-format are supported.
+Codex, Aider, Gemini CLI, Goose, Kilo Code, Pi, OpenCode, and the core Claude Code
+local transcript format are supported.
 
 The collector deliberately excludes prompts, responses, tool arguments, and
 credentials. See [Privacy](docs/privacy.md) before sharing a database or export.
@@ -86,6 +86,12 @@ Select Kilo Code to read `~/.local/share/kilo/kilo.db` instead:
 uv run cli-consumption collect --provider kilo --database usage.sqlite
 ```
 
+Select Goose to read `~/.local/share/goose/sessions/sessions.db` instead:
+
+```bash
+uv run cli-consumption collect --provider goose --database usage.sqlite
+```
+
 Select Pi to read `~/.pi/agent/sessions/` instead:
 
 ```bash
@@ -98,6 +104,14 @@ Select Gemini CLI to read `~/.gemini/tmp/*/chats/` instead:
 uv run cli-consumption collect --provider gemini --database usage.sqlite
 ```
 
+Select Aider to read a local analytics log configured at
+`~/.aider/analytics.jsonl` instead:
+
+```bash
+export AIDER_ANALYTICS_LOG="$HOME/.aider/analytics.jsonl"
+uv run cli-consumption collect --provider aider --database usage.sqlite
+```
+
 Use `all` to detect and collect every supported provider present on the machine:
 
 ```bash
@@ -154,6 +168,14 @@ uv run cli-consumption collect --provider kilo \
   --source laptop=/data/kilo/laptop
 ```
 
+Copied Goose sources point to the sessions directory containing `sessions.db`:
+
+```bash
+uv run cli-consumption collect --provider goose \
+  --source desktop=/data/goose/desktop \
+  --source laptop=/data/goose/laptop
+```
+
 Copied Pi sources point to the agent directory containing `sessions/`:
 
 ```bash
@@ -170,6 +192,14 @@ uv run cli-consumption collect --provider gemini \
   --source laptop=/data/gemini/laptop
 ```
 
+Copied Aider sources point to a directory containing `analytics.jsonl`:
+
+```bash
+uv run cli-consumption collect --provider aider \
+  --source desktop=/data/aider/desktop \
+  --source laptop=/data/aider/laptop
+```
+
 ## SQLite and PostgreSQL
 
 A file path selects SQLite. A SQLAlchemy URL selects PostgreSQL:

{cli_consumption-0.0.7 → cli_consumption-0.0.9}/docs/architecture.md

@@ -16,9 +16,9 @@ provider files -> adapter -> metadata-only snapshot -> SQL storage -> dashboard/
 
 - `adapters`: parse a CLI's local data into conversations, turns, model calls, tool
   calls, context-pressure samples, bounded turn settings, compactions, and content-free
-  work-item intervals. Codex exposes the complete analytics contract; Claude Code,
-  Gemini CLI, Kilo Code, OpenCode, and Pi expose the core dimensions available in
-  their local stores.
+  work-item intervals. Codex exposes the complete analytics contract; Aider, Claude
+  Code, Gemini CLI, Goose, Kilo Code, OpenCode, and Pi expose the core dimensions
+  available in their local stores.
 - `models`: define the transport boundary shared by offline and API ingestion.
 - `storage`: owns the normalized schema, idempotent replacement rules, SQLite, and
   PostgreSQL engine creation.

{cli_consumption-0.0.7 → cli_consumption-0.0.9}/docs/provider-support.md

@@ -2,9 +2,11 @@
 
 | Provider | Status | Initial source |
 | --- | --- | --- |
+| Aider | Supported (core) | Opt-in local analytics JSONL |
 | Codex | Supported | Local rollout JSONL and optional metadata-only subagent state |
 | Claude Code | Supported (core) | Local project transcript JSONL |
 | Gemini CLI | Supported (core) | Local automatic chat history JSON and JSONL |
+| Goose | Supported (core) | Local SQLite session store v16 |
 | Kilo Code | Supported (core) | Local SQLite session store |
 | OpenCode | Supported (core) | Local SQLite v2 session store |
 | Pi | Supported (core) | Local session JSONL v1-v3 |
@@ -54,6 +56,23 @@ context-window sizes, configuration labels, tool outcomes, or provider-reported
 durations. Gemini CLI's internal history schema can change without notice, and local
 token events are not billing data.
 
+Goose reads `sessions.db` from its sessions directory (normally
+`~/.local/share/goose/sessions/`). The adapter was qualified against Goose v1.47.0
+and schema v16. It extracts visible user turns, per-request model and token usage,
+tool names, and compaction markers while discarding session names, prompts, responses,
+thinking, tool arguments/results, paths, recipes, arbitrary metadata, errors, costs,
+and cost-source labels. Working directories are inspected only for explicit project
+mappings.
+
+Goose reports input tokens with cache reads and writes as subsets. Normalized uncached
+input subtracts both cache subsets, and model labels combine the session provider with
+the usage-ledger model. Usage-ledger timestamps have one-second resolution, so model
+calls are attributed to the latest visible user turn at or before the ledger event.
+This adapter does not read legacy pre-1.10 JSONL sessions or pre-v16 SQLite schemas,
+collect parent/subagent relationships, context-window sizes, reasoning tokens,
+provider-reported latency, or cost. Goose's internal schema can change without notice,
+and local token events are not billing data.
+
 OpenCode reads `opencode.db` from its XDG data directory (normally
 `~/.local/share/opencode/`). It extracts v2 session messages, model references, token
 usage, tool names, and compaction timestamps while discarding message text, reasoning,
@@ -98,6 +117,22 @@ session directories automatically, context-window sizes, costs, branch relations
 or provider-reported durations. Pi's JSONL schema can change without notice, and its
 local token events are not billing data.
 
+Aider reads an explicitly configured local analytics log named `analytics.jsonl` (for
+example, `AIDER_ANALYTICS_LOG=~/.aider/analytics.jsonl`). It groups events from
+`launched` through `exit`, extracts message-send attempts, model identifiers, and
+prompt/completion/total token counters, and discards the analytics user UUID, costs,
+exception text, command events, edit formats, system properties, and arbitrary event
+properties. Conversation identifiers are stable hashes of the transient UUID and
+launch time; the UUID itself is never emitted.
+
+Aider analytics do not expose prompts or responses, but logging is not enabled at a
+fixed location by default. The adapter cannot attribute projects, tool calls, cached
+or reasoning tokens, compactions, context windows, or provider-reported durations.
+Turns represent Aider message-send attempts because the log has no durable user-turn
+identifier. Unknown custom model names may already be represented as
+`provider/REDACTED` by Aider. Its analytics event schema can change without notice,
+and local token events are not billing data.
+
 Provider formats can change without notice. Unknown fields are ignored; malformed
 provider records are counted and skipped. Compatibility fixes should add a fixture for
 both the old and new format whenever possible.

{cli_consumption-0.0.7 → cli_consumption-0.0.9}/docs/roadmap.md

@@ -7,6 +7,7 @@
 - Core Pi local session collector
 - Core Kilo Code local SQLite collector
 - Core Gemini CLI local chat-history collector
+- Core Goose local SQLite collector
 - Offline multi-machine deduplication
 - SQLite and PostgreSQL storage
 - Metadata-only central collection API

{cli_consumption-0.0.7 → cli_consumption-0.0.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cli-consumption"
-version = "0.0.7"
+version = "0.0.9"
 description = "Analyze and consolidate AI coding CLI consumption across machines."
 readme = "README.md"
 requires-python = ">=3.14"

{cli_consumption-0.0.7 → cli_consumption-0.0.9}/src/cli_consumption/adapters/__init__.py

@@ -1,14 +1,18 @@
+from cli_consumption.adapters.aider import AiderAdapter
 from cli_consumption.adapters.claude import ClaudeAdapter
 from cli_consumption.adapters.codex import CodexAdapter
 from cli_consumption.adapters.gemini import GeminiAdapter
+from cli_consumption.adapters.goose import GooseAdapter
 from cli_consumption.adapters.kilo import KiloAdapter
 from cli_consumption.adapters.opencode import OpenCodeAdapter
 from cli_consumption.adapters.pi import PiAdapter
 
 __all__ = [
+    "AiderAdapter",
     "ClaudeAdapter",
     "CodexAdapter",
     "GeminiAdapter",
+    "GooseAdapter",
     "KiloAdapter",
     "OpenCodeAdapter",
     "PiAdapter",

cli_consumption-0.0.9/src/cli_consumption/adapters/aider.py

@@ -0,0 +1,347 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from cli_consumption.models import Snapshot, empty_tokens
+
+MAX_BIGINT = 9_223_372_036_854_775_807
+SAFE_LABEL = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.:/+-]*")
+
+
+@dataclass(slots=True)
+class _Candidate:
+    machine: str
+    external_id: str
+    events: list[dict[str, Any]]
+    digest: str
+
+
+class AiderAdapter:
+    """Read Aider analytics logs while discarding arbitrary event properties."""
+
+    name = "aider"
+
+    def collect(
+        self,
+        sources: list[tuple[str, Path]],
+        project_mappings: list[tuple[str, str]] | None = None,
+    ) -> Snapshot:
+        del project_mappings  # Aider analytics do not record a project path.
+        selected: dict[str, _Candidate] = {}
+        duplicates = malformed = 0
+        for machine, home in sources:
+            path = home / "analytics.jsonl"
+            if not path.is_file():
+                raise ValueError(f"Missing Aider analytics log: {path}")
+            sessions, invalid = _read_sessions(path)
+            malformed += invalid
+            for external_id, events, digest in sessions:
+                candidate = _Candidate(machine, external_id, events, digest)
+                previous = selected.get(external_id)
+                if previous is None:
+                    selected[external_id] = candidate
+                    continue
+                duplicates += 1
+                if _rank(candidate) > _rank(previous):
+                    selected[external_id] = candidate
+
+        snapshot = Snapshot(
+            provider=self.name,
+            duplicate_conversations=duplicates,
+            malformed_records=malformed,
+        )
+        for candidate in sorted(selected.values(), key=lambda item: item.external_id):
+            self._normalize(snapshot, candidate)
+        return snapshot
+
+    def _normalize(self, snapshot: Snapshot, source: _Candidate) -> None:
+        conversation_id = f"aider:{source.external_id}"
+        timestamps = [
+            timestamp
+            for event in source.events
+            if (timestamp := _timestamp(event.get("time"))) is not None
+        ]
+        turns: list[dict[str, Any]] = []
+        turn_models: list[set[str]] = []
+        active: int | None = None
+        calls: list[tuple[int | None, datetime | None, str, dict[str, int]]] = []
+
+        for event in source.events:
+            name = event.get("event")
+            timestamp = _timestamp(event.get("time"))
+            if name == "message_send_starting":
+                if active is not None:
+                    _finish_turn(turns[active], timestamp, "aborted")
+                active = len(turns)
+                turns.append(_new_turn(conversation_id, active + 1, timestamp))
+                turn_models.append(set())
+                continue
+            if name == "message_send_exception":
+                if active is not None:
+                    _finish_turn(turns[active], timestamp, "aborted")
+                    active = None
+                continue
+            if name == "exit":
+                if active is not None:
+                    _finish_turn(turns[active], timestamp, "aborted")
+                    active = None
+                continue
+            if name != "message_send":
+                continue
+
+            properties = event.get("properties")
+            properties = properties if isinstance(properties, dict) else {}
+            model = _label(properties.get("main_model"), 255) or "unknown"
+            tokens = _usage(properties)
+            calls.append((active, timestamp, model, tokens))
+            if active is not None:
+                _finish_turn(turns[active], timestamp, "completed")
+                turn_models[active].add(model)
+                active = None
+
+        ended_at = max(timestamps, default=None)
+        if active is not None:
+            _finish_turn(turns[active], ended_at, "in-progress")
+
+        totals = empty_tokens()
+        models: set[str] = set()
+        for sequence, (turn_index, timestamp, model, tokens) in enumerate(calls, 1):
+            models.add(model)
+            _add_tokens(totals, tokens)
+            turn = turns[turn_index] if turn_index is not None else None
+            if turn is not None:
+                turn["model_calls"] += 1
+                _add_tokens(turn, tokens)
+            snapshot.model_calls.append(
+                {
+                    "id": f"{conversation_id}:model:{sequence}",
+                    "conversation_id": conversation_id,
+                    "turn_id": turn["id"] if turn else None,
+                    "sequence": sequence,
+                    "timestamp": _iso(timestamp),
+                    "model": model,
+                    **tokens,
+                }
+            )
+
+        for index, turn in enumerate(turns):
+            snapshot.turns.append(turn)
+            observed_models = turn_models[index]
+            snapshot.turn_settings.append(
+                {
+                    "id": f"{conversation_id}:settings:{index + 1}",
+                    "conversation_id": conversation_id,
+                    "turn_id": turn["id"],
+                    "model": next(iter(observed_models))
+                    if len(observed_models) == 1
+                    else None,
+                    "effort": None,
+                    "collaboration_mode": None,
+                    "service_tier": None,
+                    "context_window_tokens": None,
+                }
+            )
+
+        started_at = min(timestamps, default=None)
+        snapshot.conversations.append(
+            {
+                "id": conversation_id,
+                "provider": self.name,
+                "external_id": source.external_id,
+                "source_machine": source.machine,
+                "project": "outside-project",
+                "project_source": "none",
+                "started_at": _iso(started_at),
+                "ended_at": _iso(ended_at),
+                "duration_seconds": (
+                    (ended_at - started_at).total_seconds()
+                    if started_at and ended_at
+                    else None
+                ),
+                "source": "local-analytics-jsonl",
+                "models": sorted(models),
+                "iterations": len(turns),
+                "model_calls": len(calls),
+                "tool_calls": 0,
+                "compactions": 0,
+                "event_count": len(source.events),
+                "content_hash": source.digest,
+                **totals,
+            }
+        )
+
+
+def _read_sessions(
+    path: Path,
+) -> tuple[list[tuple[str, list[dict[str, Any]], str]], int]:
+    sessions: list[tuple[str, list[dict[str, Any]], str]] = []
+    active: list[dict[str, Any]] | None = None
+    malformed = 0
+    ordinals: dict[tuple[str, int], int] = {}
+    with path.open("rb") as handle:
+        for line in handle:
+            if not line.strip():
+                continue
+            try:
+                event = json.loads(line)
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                malformed += 1
+                continue
+            if not isinstance(event, dict) or not isinstance(event.get("event"), str):
+                malformed += 1
+                continue
+            if _epoch(event.get("time")) is None:
+                malformed += 1
+                continue
+            if event["event"] == "launched":
+                if active:
+                    sessions.append(_session(active, ordinals))
+                active = [event]
+                continue
+            if active is None:
+                continue
+            active.append(event)
+            if event["event"] == "exit":
+                sessions.append(_session(active, ordinals))
+                active = None
+    if active:
+        sessions.append(_session(active, ordinals))
+    return sessions, malformed
+
+
+def _session(
+    events: list[dict[str, Any]], ordinals: dict[tuple[str, int], int]
+) -> tuple[str, list[dict[str, Any]], str]:
+    launched = events[0]
+    user_id = launched.get("user_id")
+    user_id = user_id if isinstance(user_id, str) else "anonymous"
+    started = _epoch(launched.get("time")) or 0
+    key = (user_id, started)
+    ordinal = ordinals.get(key, 0) + 1
+    ordinals[key] = ordinal
+    stable = hashlib.sha256(f"{user_id}\0{started}\0{ordinal}".encode()).hexdigest()[
+        :32
+    ]
+    approved = [
+        {
+            "event": event.get("event"),
+            "time": _epoch(event.get("time")),
+            "properties": _approved_properties(event),
+        }
+        for event in events
+    ]
+    digest = hashlib.sha256(
+        json.dumps(approved, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+    return stable, events, digest
+
+
+def _approved_properties(event: dict[str, Any]) -> dict[str, Any]:
+    if event.get("event") != "message_send":
+        return {}
+    properties = event.get("properties")
+    if not isinstance(properties, dict):
+        return {}
+    return {
+        key: properties.get(key)
+        for key in ("main_model", "prompt_tokens", "completion_tokens", "total_tokens")
+    }
+
+
+def _new_turn(
+    conversation_id: str, sequence: int, timestamp: datetime | None
+) -> dict[str, Any]:
+    return {
+        "id": f"{conversation_id}:turn:{sequence}",
+        "conversation_id": conversation_id,
+        "external_id": f"turn-{sequence}",
+        "started_at": _iso(timestamp),
+        "ended_at": None,
+        "status": "in-progress",
+        "duration_ms": None,
+        "time_to_first_token_ms": None,
+        "model_calls": 0,
+        "tool_calls": 0,
+        **empty_tokens(),
+    }
+
+
+def _finish_turn(turn: dict[str, Any], timestamp: datetime | None, status: str) -> None:
+    turn["ended_at"] = _iso(timestamp)
+    turn["status"] = status
+
+
+def _usage(properties: dict[str, Any]) -> dict[str, int]:
+    input_tokens = _counter(properties.get("prompt_tokens"))
+    output_tokens = _counter(properties.get("completion_tokens"))
+    attributed = _sum(input_tokens, output_tokens)
+    total = max(attributed, _counter(properties.get("total_tokens")))
+    return {
+        "input_tokens": input_tokens,
+        "uncached_input_tokens": input_tokens,
+        "cached_input_tokens": 0,
+        "cache_write_input_tokens": 0,
+        "output_tokens": output_tokens,
+        "reasoning_output_tokens": 0,
+        "visible_output_tokens": output_tokens,
+        "total_tokens": total,
+        "unattributed_tokens": total - attributed,
+    }
+
+
+def _counter(value: object) -> int:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return 0
+    if not math.isfinite(value) or value < 0 or value > MAX_BIGINT:
+        return 0
+    return int(value)
+
+
+def _sum(*values: int) -> int:
+    return min(MAX_BIGINT, sum(values))
+
+
+def _add_tokens(target: dict[str, Any], values: dict[str, int]) -> None:
+    for key, value in values.items():
+        target[key] = _sum(int(target[key]), value)
+
+
+def _epoch(value: object) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    if not math.isfinite(value) or value < 0 or value > 253_402_300_799:
+        return None
+    return int(value)
+
+
+def _timestamp(value: object) -> datetime | None:
+    epoch = _epoch(value)
+    return datetime.fromtimestamp(epoch, tz=UTC) if epoch is not None else None
+
+
+def _iso(value: datetime | None) -> str | None:
+    return value.isoformat().replace("+00:00", "Z") if value else None
+
+
+def _label(value: object, limit: int) -> str | None:
+    if (
+        not isinstance(value, str)
+        or len(value) > limit
+        or not SAFE_LABEL.fullmatch(value)
+    ):
+        return None
+    return value
+
+
+def _rank(candidate: _Candidate) -> tuple[int, int, str, str]:
+    ended = max(
+        (_epoch(event.get("time")) or 0 for event in candidate.events), default=0
+    )
+    return len(candidate.events), ended, candidate.digest, candidate.machine