atif-sql 0.2.0__py3-none-any.whl

atif_converter/domain/schema_version.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""The converter-owned version of what a conversion produces.
+
+The package version (``converter_version`` in ``meta.json``) moves with every
+release, including ones that change nothing a corpus holds. This number moves
+only when the artifacts a conversion writes change shape or meaning, so a
+materialize pass can re-convert exactly the sessions an older converter wrote:
+materialize stamps it into every ``meta.json`` as ``converter_schema`` and
+treats a session recording a different value as stale, whether or not its
+source moved. A source-removed session re-converts from its raw source archive.
+
+THE RULE: bump this in the same commit as any change that can alter a byte of
+any artifact for any input. A refactor that provably changes no output does not
+bump it. ``packages/atif-converter/tests/test_converter_schema_version.py`` pins
+a digest of the converter's code (docstrings and comments excluded) beside this
+value, so any converter code change fails that test until someone decides:
+bump if output can change, then re-pin the digest either way.
+
+History:
+
+* 1 — every converter before this constant existed (implicit).
+* 2 — ``session_events.jsonl`` (hooks, injected context, API errors,
+  compaction boundaries, cost-state, mode changes); ``records_captured`` in
+  ``loss_report.json`` and the structural gaps reported only when enrichment
+  didn't repair them; an unpriced model yields ``total_cost_usd`` NULL instead
+  of $0; ``final_metrics.extra.reported_cost_usd`` from Claude Code's
+  ``cost-state``; local price overrides for claude-opus-5-5 / claude-fable-5-1.
+  In the same version: inline base64 attachments replaced by blob placeholders
+  (and the bytes handed out for the corpus blob store); typed ``is_error`` /
+  ``exit_code`` / ``interrupted`` / ``images`` on observation results;
+  ``agent_id`` read from ``agentId`` and filled on every sidechain step;
+  ``trajectory.extra.subagents`` from the ``agent-*.meta.json`` sidecars.
+  Both change sets ship together and no corpus was ever stamped with only one
+  of them, so one bump separates every version-1 session from every version-2
+  one.
+* 3 — harbor 0.23.0: every priced Claude Code step carries
+  ``metrics.cost_usd`` and ``metrics.extra.cost_source`` (an unpriced step
+  carries neither), and ``meta.json`` records ``harbor_version`` 0.23.0. Prices
+  from litellm v1.102.0, which also prices claude-fable-5-1, so its local
+  override retired and its sessions are labeled ``litellm_estimate``.
+* 4 — Codex ``is_error`` / ``exit_code`` for code-mode ``exec`` scripts, from
+  the script's own header and the items its nested commands, MCP calls and
+  patches complete; ``is_error`` from the ``status`` of ``FileChange`` and
+  ``CollabAgentToolCall`` items.
+* 5 — Claude Code ``agent.extra`` lists (``cwds``, ``git_branches``,
+  ``agent_ids``) in first-seen order instead of set order, so a session
+  converts to the same bytes in every process.
+* 6 — prices from litellm v1.103.2, whose arithmetic bills cache writes and
+  cache reads at the input rate for a model that publishes no cache-creation
+  or cache-read rate (every OpenAI text model's cache writes, and cached
+  tokens of the 46 entries with no cache-read rate), where v1.102.0 billed
+  them $0. The table also adds flex rates for gpt-5.1 and gpt-5.2 and moves
+  o4-mini's flex cache-read rate. ``total_cost_usd`` and ``metrics.cost_usd``
+  change for every such session.
+* 7 — harbor 0.24.0: ``meta.json`` records ``harbor_version`` 0.24.0. The
+  Claude Code port itself puts each event's ``agentId`` on every step the
+  event becomes (prompts, tool results and turns, which enrichment filled
+  before) and writes ``is_sidechain`` and ``agent_id`` right after ``id`` in
+  ``extra``, harbor's key order; a snake_case ``agent_id`` key names no
+  subagent (harbor #3434). A Codex tool output that is a list of content blocks or
+  items is its text parts joined by newlines, with an inline image as its blob
+  placeholder, where it was Python's ``str()`` of the list; a non-string
+  ``output`` inside an output object is its JSON text; a JSON scalar output
+  keeps its raw text (harbor #3467). A Codex ``web_search_call`` carries its
+  item id, or ``<api call>_web_search_<n>``, where its id was empty (harbor
+  #2972).
+* 8 — every Codex tool output image the port writes a blob placeholder for is
+  lifted by the pre-pass too: an MCP ``image`` block with inline base64 (by
+  ``mimeType`` or ``mime_type``), and an ``input_image`` whose data URL
+  carries parameters or whose base64 is wrapped. Its bytes reach the blob
+  store, its result carries ``extra.images``, and a tool output list the port
+  dumps as JSON (one element of an unknown type) holds the placeholder item
+  where it held the base64. Placeholder text is unchanged.
+* 9 — a Codex code-mode ``exec`` script's nested MCP calls and commands (the
+  ``McpToolCall`` / ``CommandExecution`` items attributed to it) are tool
+  calls of their own on its step, after the ``exec`` call, with
+  ``extra.nested_in``, ``via`` and ``duration_ms``, and one result each
+  carrying its content and its own ``is_error`` / ``exit_code`` (and
+  ``images``: the pre-pass lifts images out of those items' MCP results too).
+  The ``exec`` result's own fields are unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+CONVERTER_SCHEMA_VERSION: Final = 9
+
+__all__ = ["CONVERTER_SCHEMA_VERSION"]

atif_converter/domain/session_events.py

@@ -0,0 +1,408 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""session_events.jsonl: the non-message records worth keeping, one typed row each.
+
+Pure functions over already-parsed ``(record, source_file)`` pairs; no harbor,
+no I/O. The step converter keeps user and assistant records only
+(:attr:`~atif_converter.domain.fidelity.FidelityGap.NON_MESSAGE_RECORDS_DROPPED`),
+which loses records that say what happened AROUND the turns: hooks that ran,
+blocked or were cancelled, context a hook or a queued command injected into
+the model's view, API errors, compaction boundaries, refusal fallbacks,
+Claude Code's own running cost, and mode changes. This module picks those out
+and writes each one as a row. They're deliberately NOT ATIF steps: the steps
+view and everything built on it stay exactly as they were.
+
+ROW SHAPE (:data:`SESSION_EVENT_FIELDS`, key order stable)::
+
+    {
+        seq,
+        ts,
+        event_type,
+        subtype,
+        uuid,
+        parent_uuid,
+        tool_use_id,
+        is_sidechain,
+        source_file,
+        payload,
+        payload_bytes,
+        payload_truncated,
+    }
+
+``event_type`` is the raw record ``type`` (``system``, ``attachment``,
+``cost-state``, ``mode``, ``permission-mode``; for Codex ``compacted`` or
+``event_msg``) and ``subtype`` names the kind inside it (``system.subtype``,
+``attachment.type``, a Codex ``payload.type``; ``None`` where the record type
+is the whole story). ``seq`` is the row's position in the session's record
+order (main file first, then side files, as read), because ``cost-state`` and
+``mode`` records carry no timestamp. ``parent_uuid`` is the record's
+``parentUuid``: for an attachment it's the record the attachment follows,
+which is how a row joins back to ``steps.source_uuids``.
+
+BOUNDED PAYLOAD. ``payload`` is the record minus its envelope (the columns
+above plus per-record noise such as ``cwd`` and ``version``). Strings longer
+than :data:`PAYLOAD_STRING_MAX_CHARS` and lists longer than
+:data:`PAYLOAD_LIST_MAX_ITEMS` are cut, and a payload still over
+:data:`PAYLOAD_MAX_BYTES` becomes ``{"truncated_preview": <first bytes>}``.
+``payload_bytes`` is always the ORIGINAL payload's UTF-8 JSON length and
+``payload_truncated`` says whether anything was cut, so a reader can tell a
+short payload from a shortened one.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from typing import Any, Final
+
+from atif_converter.domain.codex_edges import record_id
+
+#: Stable key order for one session_events.jsonl line.
+SESSION_EVENT_FIELDS: Final = (
+    "seq",
+    "ts",
+    "event_type",
+    "subtype",
+    "uuid",
+    "parent_uuid",
+    "tool_use_id",
+    "is_sidechain",
+    "source_file",
+    "payload",
+    "payload_bytes",
+    "payload_truncated",
+)
+
+#: Hard ceiling for one serialized payload, in UTF-8 bytes.
+PAYLOAD_MAX_BYTES: Final = 8192
+#: Any string leaf longer than this is cut to it.
+PAYLOAD_STRING_MAX_CHARS: Final = 2048
+#: Any list longer than this keeps its first items only.
+PAYLOAD_LIST_MAX_ITEMS: Final = 32
+#: Nesting below this depth is replaced by its JSON text, then cut as a string.
+_PAYLOAD_MAX_DEPTH: Final = 8
+_ELLIPSIS: Final = "…"
+
+# --------------------------------------------------------------------------- Claude Code
+
+#: ``system`` records kept, by ``subtype``.
+CLAUDE_SYSTEM_SUBTYPES: Final = frozenset(
+    {"stop_hook_summary", "api_error", "compact_boundary", "model_refusal_fallback"}
+)
+#: ``attachment`` records kept, by ``attachment.type``, besides every ``hook_*`` type.
+CLAUDE_ATTACHMENT_TYPES: Final = frozenset({"queued_command"})
+_CLAUDE_HOOK_ATTACHMENT_PREFIX: Final = "hook_"
+#: Record types kept whole (no subtype).
+CLAUDE_WHOLE_RECORD_TYPES: Final = frozenset({"cost-state", "mode", "permission-mode"})
+
+#: Record keys that are columns or per-record noise, never payload.
+_CLAUDE_ENVELOPE: Final = frozenset(
+    {
+        "type",
+        "subtype",
+        "uuid",
+        "parentUuid",
+        "timestamp",
+        "isSidechain",
+        "toolUseID",
+        "sessionId",
+        "userType",
+        "entrypoint",
+        "cwd",
+        "version",
+        "gitBranch",
+        "slug",
+        "isMeta",
+        "attachment",
+        "rendered",
+    }
+)
+
+# --------------------------------------------------------------------------- Codex
+
+#: Top-level Codex record types kept whole.
+CODEX_WHOLE_RECORD_TYPES: Final = frozenset({"compacted"})
+#: ``event_msg`` records kept, by ``payload.type``.
+CODEX_EVENT_MSG_TYPES: Final = frozenset(
+    {"turn_aborted", "error", "stream_error", "context_compacted", "warning"}
+)
+
+
+def _bounded_container(value: dict[str, Any] | list[Any], depth: int) -> tuple[Any, bool]:
+    if depth >= _PAYLOAD_MAX_DEPTH:
+        text = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+        return _bounded(text, depth)[0], True
+    if isinstance(value, dict):
+        cut = False
+        out: dict[str, Any] = {}
+        for key, item in value.items():
+            out[str(key)], item_cut = _bounded(item, depth + 1)
+            cut = cut or item_cut
+        return out, cut
+    cut = len(value) > PAYLOAD_LIST_MAX_ITEMS
+    items: list[Any] = []
+    for item in value[:PAYLOAD_LIST_MAX_ITEMS]:
+        bounded_item, item_cut = _bounded(item, depth + 1)
+        items.append(bounded_item)
+        cut = cut or item_cut
+    return items, cut
+
+
+def _bounded(value: Any, depth: int = 0) -> tuple[Any, bool]:
+    """``value`` with long strings and lists cut; the flag says whether anything was."""
+    if isinstance(value, str):
+        if len(value) > PAYLOAD_STRING_MAX_CHARS:
+            return value[:PAYLOAD_STRING_MAX_CHARS] + _ELLIPSIS, True
+        return value, False
+    if isinstance(value, dict | list):
+        return _bounded_container(value, depth)
+    return value, False
+
+
+def bound_payload(payload: dict[str, Any]) -> tuple[dict[str, Any], int, bool]:
+    """``(bounded payload, original UTF-8 JSON length, truncated?)`` for one event."""
+    original = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+    original_bytes = len(original.encode("utf-8"))
+    if original_bytes <= PAYLOAD_MAX_BYTES:
+        return payload, original_bytes, False
+    bounded, _cut = _bounded(payload)
+    text = json.dumps(bounded, ensure_ascii=False, separators=(",", ":"))
+    if len(text.encode("utf-8")) <= PAYLOAD_MAX_BYTES:
+        return bounded, original_bytes, True
+    preview = original.encode("utf-8")[:PAYLOAD_MAX_BYTES].decode("utf-8", errors="ignore")
+    return {"truncated_preview": preview}, original_bytes, True
+
+
+def _str_or_none(value: Any) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _claude_subtype(record: dict[str, Any], record_type: str) -> str | None:
+    """The kept subtype of a ``system`` / ``attachment`` record, else ``None``."""
+    if record_type == "system":
+        subtype = record.get("subtype")
+        return subtype if isinstance(subtype, str) and subtype in CLAUDE_SYSTEM_SUBTYPES else None
+    if record_type == "attachment":
+        attachment = record.get("attachment")
+        kind = attachment.get("type") if isinstance(attachment, dict) else None
+        if isinstance(kind, str) and (
+            kind.startswith(_CLAUDE_HOOK_ATTACHMENT_PREFIX) or kind in CLAUDE_ATTACHMENT_TYPES
+        ):
+            return kind
+    return None
+
+
+def _claude_kind(record: dict[str, Any]) -> tuple[str, str | None] | None:
+    """``(event_type, subtype)`` when a Claude Code record is kept, else ``None``."""
+    record_type = record.get("type")
+    if not isinstance(record_type, str):
+        return None
+    if record_type in CLAUDE_WHOLE_RECORD_TYPES:
+        return record_type, None
+    subtype = _claude_subtype(record, record_type)
+    return None if subtype is None else (record_type, subtype)
+
+
+def is_claude_session_event(record: dict[str, Any]) -> bool:
+    """Whether a Claude Code record becomes a session_events row."""
+    return _claude_kind(record) is not None
+
+
+def _claude_payload(record: dict[str, Any]) -> dict[str, Any]:
+    payload = {key: value for key, value in record.items() if key not in _CLAUDE_ENVELOPE}
+    attachment = record.get("attachment")
+    if isinstance(attachment, dict):
+        payload.update(
+            {key: value for key, value in attachment.items() if key not in {"type", "toolUseID"}}
+        )
+    return payload
+
+
+def _claude_tool_use_id(record: dict[str, Any]) -> str | None:
+    own = _str_or_none(record.get("toolUseID"))
+    if own is not None:
+        return own
+    attachment = record.get("attachment")
+    return _str_or_none(attachment.get("toolUseID")) if isinstance(attachment, dict) else None
+
+
+def _row(
+    seq: int,
+    *,
+    ts: Any,
+    kind: tuple[str, str | None],
+    uuid: str | None,
+    parent_uuid: str | None,
+    tool_use_id: str | None,
+    is_sidechain: bool,
+    source_file: str,
+    payload: dict[str, Any],
+) -> dict[str, Any]:
+    bounded, original_bytes, truncated = bound_payload(payload)
+    return {
+        "seq": seq,
+        "ts": _str_or_none(ts),
+        "event_type": kind[0],
+        "subtype": kind[1],
+        "uuid": uuid,
+        "parent_uuid": parent_uuid,
+        "tool_use_id": tool_use_id,
+        "is_sidechain": is_sidechain,
+        "source_file": source_file,
+        "payload": bounded,
+        "payload_bytes": original_bytes,
+        "payload_truncated": truncated,
+    }
+
+
+def claude_session_events(records: Iterable[tuple[dict[str, Any], str]]) -> list[dict[str, Any]]:
+    """The kept Claude Code records as rows, in the order the pairs arrive."""
+    rows: list[dict[str, Any]] = []
+    for record, source_file in records:
+        kind = _claude_kind(record)
+        if kind is None:
+            continue
+        rows.append(
+            _row(
+                len(rows),
+                ts=record.get("timestamp"),
+                kind=kind,
+                uuid=_str_or_none(record.get("uuid")),
+                parent_uuid=_str_or_none(record.get("parentUuid")),
+                tool_use_id=_claude_tool_use_id(record),
+                is_sidechain=bool(record.get("isSidechain", False)),
+                source_file=source_file,
+                payload=_claude_payload(record),
+            )
+        )
+    return rows
+
+
+def _codex_kind(record: dict[str, Any]) -> tuple[str, str | None] | None:
+    record_type = record.get("type")
+    if not isinstance(record_type, str):
+        return None
+    if record_type in CODEX_WHOLE_RECORD_TYPES:
+        return record_type, None
+    payload = record.get("payload")
+    if record_type == "event_msg" and isinstance(payload, dict):
+        kind = payload.get("type")
+        if isinstance(kind, str) and kind in CODEX_EVENT_MSG_TYPES:
+            return record_type, kind
+    return None
+
+
+def is_codex_session_event(record: dict[str, Any]) -> bool:
+    """Whether a Codex rollout record becomes a session_events row."""
+    return _codex_kind(record) is not None
+
+
+def codex_session_events(records: Iterable[tuple[dict[str, Any], str]]) -> list[dict[str, Any]]:
+    """The kept Codex records as rows, in file order.
+
+    ``uuid`` is the same id ``edges.jsonl`` gives the record
+    (:func:`~atif_converter.domain.codex_edges.record_id`, line-numbered per
+    source file), so a row joins ``messages`` on it. A rollout has no parent
+    pointer and no sidechain, so those columns are ``None`` / ``False``.
+    """
+    rows: list[dict[str, Any]] = []
+    line_numbers: dict[str, int] = {}
+    for record, source_file in records:
+        line_numbers[source_file] = line_numbers.get(source_file, 0) + 1
+        kind = _codex_kind(record)
+        if kind is None:
+            continue
+        payload = record.get("payload")
+        body = (
+            {key: value for key, value in payload.items() if key != "type"}
+            if isinstance(payload, dict)
+            else {}
+        )
+        rows.append(
+            _row(
+                len(rows),
+                ts=record.get("timestamp"),
+                kind=kind,
+                uuid=record_id(record, line_numbers[source_file]),
+                parent_uuid=None,
+                tool_use_id=None,
+                is_sidechain=False,
+                source_file=source_file,
+                payload=body,
+            )
+        )
+    return rows
+
+
+#: ``final_metrics.extra`` keys the reported cost lands under.
+REPORTED_COST_KEY: Final = "reported_cost_usd"
+REPORTED_COST_SOURCE_KEY: Final = "reported_cost_source"
+REPORTED_UNKNOWN_MODEL_COST_KEY: Final = "reported_cost_has_unknown_model_cost"
+#: ``reported_cost_source`` for a figure read off a Claude Code ``cost-state`` record.
+REPORTED_COST_SOURCE_COST_STATE: Final = "claude_code_cost_state"
+
+
+def claude_reported_cost(records: Iterable[tuple[dict[str, Any], str]]) -> dict[str, Any]:
+    """What Claude Code itself says the session cost, for ``final_metrics.extra``.
+
+    Claude Code appends a ``cost-state`` record as the session runs; its
+    ``totalCostUSD`` is cumulative across resumes (measured 2026-09-27: the
+    value only grows and ``startTime`` stays fixed across a resume), so the
+    LAST one in record order is the session's figure. Returns ``{}`` when no
+    record carries a numeric ``totalCostUSD``. ``hasUnknownModelCost`` is kept
+    beside it because Claude Code sets it when it met a model it couldn't
+    price, which makes its own total a lower bound.
+    """
+    last: dict[str, Any] | None = None
+    for record, _source_file in records:
+        if record.get("type") != "cost-state" or record.get("isSidechain"):
+            continue
+        total = record.get("totalCostUSD")
+        if isinstance(total, int | float) and not isinstance(total, bool):
+            last = record
+    if last is None:
+        return {}
+    reported: dict[str, Any] = {
+        REPORTED_COST_KEY: float(last["totalCostUSD"]),
+        REPORTED_COST_SOURCE_KEY: REPORTED_COST_SOURCE_COST_STATE,
+    }
+    unknown = last.get("hasUnknownModelCost")
+    if isinstance(unknown, bool):
+        reported[REPORTED_UNKNOWN_MODEL_COST_KEY] = unknown
+    return reported
+
+
+def session_event_to_jsonl_line(row: dict[str, Any]) -> str:
+    """Serialize one row as a compact, key-order-stable JSONL line."""
+    ordered = {key: row.get(key) for key in SESSION_EVENT_FIELDS}
+    return json.dumps(ordered, ensure_ascii=False, separators=(",", ":"))
+
+
+def session_events_jsonl_lines(rows: Iterable[dict[str, Any]]) -> list[str]:
+    """The ready-to-write session_events.jsonl body."""
+    return [session_event_to_jsonl_line(row) for row in rows]
+
+
+__all__ = [
+    "CLAUDE_ATTACHMENT_TYPES",
+    "CLAUDE_SYSTEM_SUBTYPES",
+    "CLAUDE_WHOLE_RECORD_TYPES",
+    "CODEX_EVENT_MSG_TYPES",
+    "CODEX_WHOLE_RECORD_TYPES",
+    "PAYLOAD_LIST_MAX_ITEMS",
+    "PAYLOAD_MAX_BYTES",
+    "PAYLOAD_STRING_MAX_CHARS",
+    "REPORTED_COST_KEY",
+    "REPORTED_COST_SOURCE_COST_STATE",
+    "REPORTED_COST_SOURCE_KEY",
+    "REPORTED_UNKNOWN_MODEL_COST_KEY",
+    "SESSION_EVENT_FIELDS",
+    "bound_payload",
+    "claude_reported_cost",
+    "claude_session_events",
+    "codex_session_events",
+    "is_claude_session_event",
+    "is_codex_session_event",
+    "session_event_to_jsonl_line",
+    "session_events_jsonl_lines",
+]

atif_converter/infrastructure/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Infrastructure layer: harbor adapter and raw-JSONL readers."""

atif_converter/infrastructure/census.py

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Raw-side census of a Claude Code session: the input half of a LossReport.
+
+Counts come from records already parsed out of a
+:class:`~atif_converter.infrastructure.raw_records.SessionSnapshot`, and the
+side-file classification is derived from that same snapshot's file list — no
+second parse, no disk access, no harbor, no env, no network. Both halves read
+from the one snapshot, so the census, the trajectory, and edges.jsonl
+describe the same bytes of a session that may still be growing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from atif_converter.domain.fidelity import RecordType
+from atif_converter.infrastructure.raw_records import SessionSnapshot
+
+_KNOWN_TYPES: dict[str, RecordType] = {
+    rt.value: rt for rt in RecordType if rt is not RecordType.OTHER
+}
+
+#: harbor's ``rglob("subagents/*.jsonl")`` discovers a side-file only when this
+#: is the name of its immediate parent directory.
+_HARBOR_SUBAGENT_DIR = "subagents"
+
+
+@dataclass(frozen=True, slots=True)
+class SessionCensus:
+    """Raw record counts for one session (main file + every side-file).
+
+    ``record_counts`` covers EVERY record of EVERY discovered ``*.jsonl``, so
+    it agrees line-for-line with edges.jsonl. ``subagent_files`` are the
+    side-files harbor 0.22.0's ``rglob("subagents/*.jsonl")`` can discover;
+    ``workflow_subagent_files`` are the ones it cannot — those nested deeper
+    (``subagents/workflows/wf_*/agent-*.jsonl``) plus any other ``*.jsonl``
+    elsewhere in the side directory — fidelity gap 1.
+    """
+
+    session_jsonl: Path
+    record_counts: dict[RecordType, int] = field(default_factory=dict)
+    subagent_files: tuple[Path, ...] = ()
+    workflow_subagent_files: tuple[Path, ...] = ()
+
+
+def _record_type(record: dict[str, Any]) -> RecordType:
+    raw_type = record.get("type")
+    if isinstance(raw_type, str):
+        return _KNOWN_TYPES.get(raw_type, RecordType.OTHER)
+    return RecordType.OTHER
+
+
+def census_from_snapshot(
+    snapshot: SessionSnapshot,
+    records: Iterable[tuple[dict[str, Any], str]],
+) -> SessionCensus:
+    """Census one snapshot: record-type counts plus side-file classification.
+
+    ``records`` are that snapshot's parsed pairs from
+    :func:`~atif_converter.infrastructure.raw_records.read_snapshot_records`.
+    Only each record's ``type`` is read, so a generator whose records are
+    discarded as they are consumed counts the same as a list.
+    """
+    counts: dict[RecordType, int] = {}
+    for record, _source_file in records:
+        record_type = _record_type(record)
+        counts[record_type] = counts.get(record_type, 0) + 1
+
+    session_jsonl = snapshot.session_jsonl
+    subagent_files: list[Path] = []
+    workflow_files: list[Path] = []
+    for candidate in snapshot.files:
+        if candidate == session_jsonl:
+            continue
+        if candidate.parent.name == _HARBOR_SUBAGENT_DIR:
+            subagent_files.append(candidate)
+        else:
+            workflow_files.append(candidate)
+
+    return SessionCensus(
+        session_jsonl=session_jsonl,
+        record_counts=counts,
+        subagent_files=tuple(subagent_files),
+        workflow_subagent_files=tuple(workflow_files),
+    )