session-preserve 0.2.0__py3-none-any.whl

codex_preserve/__init__.py

@@ -0,0 +1,12 @@
+"""Session Preserve: durable local coding-agent session preservation.
+
+The public distribution and console command are named session-preserve.
+The internal Python package keeps its historical codex_preserve module name for
+the v0.2.0 transition while schema-2 compatibility remains frozen.
+
+This project is independent and unofficial.
+"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

codex_preserve/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m codex_preserve`` runs the same command as ``session-preserve``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

codex_preserve/_claude_payload.py

@@ -0,0 +1,146 @@
+"""Internal Claude payload candidate over persisted, G4a/G4b-safe facts.
+
+This is not a package schema or a claim about the current Claude UI. G4a's
+``COMPLETE`` classifies the selected persisted source under its parser contract;
+it does not attest that all visible replies were flushed or that a session ended.
+No source path or raw JSONL is accepted or read here.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Optional, Tuple
+
+from ._claude_readable import (
+    ReadableBranchPoint, ReadableDiagnosticSummary, ReadableEvent,
+    ReadableGraph, ReadableLeafHint, ReadableNode, build_readable_graph,
+)
+from ._claude_source import ParseResult
+
+
+@dataclass(frozen=True)
+class ClaudeProvenance:
+    """Content identity of a stable selected top-level JSONL snapshot, not authenticity."""
+
+    source_sha256: Optional[str]
+    source_size_bytes: Optional[int]
+
+
+@dataclass(frozen=True)
+class ClaudeCoverage:
+    """Separate source stability, parser classification, persisted text, and UI claims."""
+
+    source_stable: bool
+    parser_source_classification: str
+    source_entrypoint: str
+    readable_node_count: int
+    rendered_text_block_count: int
+    branch_count: int
+    graph_gap_count: int
+    unknown_count: int
+    duplicate_uuid_count: int
+    diagnostic_counts_by_code: Tuple[Tuple[str, int], ...]
+    source_scope: str = field(init=False, default="selected_top_level_jsonl")
+    sidecar_bodies_included: bool = field(init=False, default=False)
+    ui_completeness_attested: bool = field(init=False, default=False)
+    session_terminal_attested: bool = field(init=False, default=False)
+
+
+@dataclass(frozen=True)
+class ClaudeGraphGap:
+    record_id: str
+    source_line: int
+    node_id: Optional[str]
+
+
+@dataclass(frozen=True)
+class ClaudeDuplicateOccurrence:
+    node_id: str
+    record_ids: Tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ClaudeProviderPayload:
+    """Loss-averse internal candidate; occurrence order is persisted source order."""
+
+    readable_nodes: Tuple[ReadableNode, ...]
+    events: Tuple[ReadableEvent, ...]
+    branch_points: Tuple[ReadableBranchPoint, ...]
+    leaf_hints: Tuple[ReadableLeafHint, ...]
+    graph_gaps: Tuple[ClaudeGraphGap, ...]
+    duplicate_occurrences: Tuple[ClaudeDuplicateOccurrence, ...]
+    diagnostics: ReadableDiagnosticSummary
+    coverage: ClaudeCoverage
+    provenance: ClaudeProvenance
+    presentation_order: str
+    format_status: str = field(init=False, default="INTERNAL_CANDIDATE")
+
+    def as_dict(self) -> dict:
+        """Deterministic safe candidate shape; G5 may replace it without migration."""
+        def json_shape(value):
+            if isinstance(value, dict):
+                return {key: json_shape(item) for key, item in value.items()}
+            if isinstance(value, tuple):
+                return [json_shape(item) for item in value]
+            return value
+
+        return json_shape(asdict(self))
+
+    def candidate_json_bytes(self) -> bytes:
+        """Deterministic internal bytes, with no promised package member name."""
+        return (json.dumps(self.as_dict(), ensure_ascii=False, sort_keys=True,
+                           separators=(",", ":")) + "\n").encode("utf-8")
+
+
+def build_claude_payload(graph: ReadableGraph,
+                         source: ParseResult) -> ClaudeProviderPayload:
+    """Project G4b graph plus only G4a's attested snapshot facts.
+
+    The caller supplies the G4a result used to build ``graph``. This function
+    validates the graph against that already-safe ParseResult so snapshot
+    provenance cannot be paired with content from another source. It never
+    reopens a source path or reads raw JSONL bytes.
+    """
+    if not isinstance(graph, ReadableGraph) or not isinstance(source, ParseResult):
+        raise TypeError("expected Claude ReadableGraph and ParseResult")
+    expected_graph = build_readable_graph(source)
+    if graph != expected_graph:
+        raise ValueError("graph does not match the supplied source ParseResult")
+    if source.source_stable:
+        if source.source_sha256 is None or source.source_size_bytes is None:
+            raise ValueError("stable source lacks snapshot identity")
+    elif source.source_sha256 is not None or source.source_size_bytes is not None:
+        raise ValueError("unstable source cannot attest snapshot identity")
+
+    occurrences = {}
+    for node in graph.nodes:
+        if node.node_id is not None:
+            occurrences.setdefault(node.node_id, []).append(node.record_id)
+    duplicate_occurrences = tuple(
+        ClaudeDuplicateOccurrence(node_id, tuple(record_ids))
+        for node_id, record_ids in occurrences.items() if len(record_ids) > 1
+    )
+    graph_gaps = tuple(
+        ClaudeGraphGap(node.record_id, node.source_line, node.node_id)
+        for node in graph.nodes if node.parent_link == "missing"
+    )
+    diagnostic_counts = dict(graph.diagnostics.counts_by_code)
+    coverage = ClaudeCoverage(
+        source_stable=source.source_stable,
+        parser_source_classification=graph.source_completeness,
+        source_entrypoint=graph.source_entrypoint,
+        readable_node_count=graph.readable_node_count,
+        rendered_text_block_count=graph.rendered_text_block_count,
+        branch_count=graph.branch_count,
+        graph_gap_count=graph.graph_gap_count,
+        unknown_count=graph.unknown_count,
+        duplicate_uuid_count=diagnostic_counts.get("DUPLICATE_UUID", 0),
+        diagnostic_counts_by_code=graph.diagnostics.counts_by_code,
+    )
+    return ClaudeProviderPayload(
+        graph.nodes, graph.events, graph.branch_points, graph.leaf_hints,
+        graph_gaps, duplicate_occurrences, graph.diagnostics, coverage,
+        ClaudeProvenance(source.source_sha256, source.source_size_bytes),
+        graph.presentation_order,
+    )

codex_preserve/_claude_readable.py

@@ -0,0 +1,203 @@
+"""Internal, loss-averse readable projection of a Claude ParseResult.
+
+This module accepts only G4a's already classified data. Source line order is
+the deterministic presentation order, not an active conversation path. No
+leaf hint, branch, or graph gap removes persisted safe text.
+"""
+
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from ._claude_source import (
+    KNOWN_IGNORED_OR_SUMMARIZED, RENDER, UNKNOWN, ParseResult,
+)
+
+
+@dataclass(frozen=True)
+class ReadableBlock:
+    index: int
+    semantic_kind: Optional[str]
+    text: str
+
+
+@dataclass(frozen=True)
+class ReadableNode:
+    # A record occurrence has its own identity even if a graph UUID repeats.
+    record_id: str
+    source_line: int
+    node_id: Optional[str]
+    parent_id: Optional[str]
+    parent_record_id: Optional[str]
+    parent_link: Optional[str]
+    sidechain: Optional[bool]
+    role: Optional[str]
+    semantic_kind: Optional[str]
+    source_policy: str
+    text_blocks: Tuple[ReadableBlock, ...]
+
+
+@dataclass(frozen=True)
+class ReadableEvent:
+    record_id: str
+    source_line: int
+    kind: str
+    block_index: Optional[int] = None
+    tool_name: Optional[str] = None
+    tool_ref: Optional[str] = None
+    result_present: Optional[bool] = None
+
+
+@dataclass(frozen=True)
+class ReadableLeafHint:
+    record_id: str
+    source_line: int
+    leaf_hint_id: Optional[str]
+    leaf_hint_explicit: Optional[bool]
+    leaf_hint_rewound: Optional[bool]
+
+
+@dataclass(frozen=True)
+class ReadableBranchPoint:
+    parent_node_id: str
+    # None means the normalized node ID has multiple persisted occurrences.
+    parent_record_id: Optional[str]
+    child_record_ids: Tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ReadableDiagnosticSummary:
+    # Codes and coordinates come from G4a, never from raw source values.
+    counts_by_code: Tuple[Tuple[str, int], ...]
+    graph_gap_count: int
+    unknown_count: int  # unknown blocks plus unknown records without such blocks
+
+
+@dataclass(frozen=True)
+class ReadableGraph:
+    source_completeness: str
+    source_entrypoint: str
+    nodes: Tuple[ReadableNode, ...]
+    events: Tuple[ReadableEvent, ...]
+    leaf_hints: Tuple[ReadableLeafHint, ...]
+    branch_points: Tuple[ReadableBranchPoint, ...]
+    diagnostics: ReadableDiagnosticSummary
+    readable_node_count: int
+    rendered_text_block_count: int
+    branch_count: int
+    graph_gap_count: int
+    unknown_count: int
+    active_head_id: None = None
+    presentation_order: str = "persisted_source_line"
+
+
+def build_readable_graph(source: ParseResult) -> ReadableGraph:
+    """Preserve every G4a-approved text block, without choosing a path."""
+    if not isinstance(source, ParseResult):
+        raise TypeError("source must be a Claude ParseResult")
+
+    # G4a records are in physical source order. The ordinal identifies an
+    # occurrence independently of its (possibly duplicated) normalized UUID.
+    ordered = sorted(enumerate(source.records, 1),
+                     key=lambda pair: (pair[1].line, pair[0]))
+    record_ids = {ordinal: "record-%06d" % ordinal for ordinal, _ in ordered}
+    occurrences = defaultdict(list)
+    for ordinal, record in ordered:
+        if record.node_id is not None:
+            occurrences[record.node_id].append(record_ids[ordinal])
+
+    nodes = []
+    events = []
+    hints = []
+    children = defaultdict(lambda: defaultdict(list))
+    for ordinal, record in ordered:
+        record_id = record_ids[ordinal]
+        text_blocks = tuple(
+            ReadableBlock(block.index, block.semantic_kind, block.text)
+            for block in sorted(record.blocks, key=lambda item: item.index)
+            if block.policy == RENDER and block.text is not None
+        )
+        if record.kind in ("user", "assistant", "attachment", "system") or \
+                record.node_id is not None or text_blocks:
+            parent_occurrences = occurrences.get(record.parent_id, ())
+            parent_record_id = (parent_occurrences[0]
+                                if record.parent_link == "linked" and
+                                len(parent_occurrences) == 1 else None)
+            nodes.append(ReadableNode(
+                record_id, record.line, record.node_id, record.parent_id,
+                parent_record_id, record.parent_link, record.sidechain,
+                record.kind if record.kind in ("user", "assistant") else None,
+                record.semantic_kind, record.policy, text_blocks,
+            ))
+            if (record.parent_link == "linked" and
+                    record.parent_id is not None and record.node_id is not None):
+                children[record.parent_id][record.node_id].append(record_id)
+
+        if record.kind == "last-prompt":
+            hints.append(ReadableLeafHint(
+                record_id, record.line, record.leaf_hint_id,
+                record.leaf_hint_explicit, record.leaf_hint_rewound,
+            ))
+        if record.semantic_kind == "compact_boundary" and \
+                record.policy == KNOWN_IGNORED_OR_SUMMARIZED:
+            events.append(ReadableEvent(record_id, record.line, "compact_boundary"))
+        for block in sorted(record.blocks, key=lambda item: item.index):
+            if block.policy != KNOWN_IGNORED_OR_SUMMARIZED:
+                continue
+            if block.kind == "tool_use":
+                events.append(ReadableEvent(
+                    record_id, record.line, "tool_use", block.index,
+                    tool_name=block.tool_name, tool_ref=block.tool_ref,
+                ))
+            elif block.kind == "tool_result":
+                events.append(ReadableEvent(
+                    record_id, record.line, "tool_result_present", block.index,
+                    tool_ref=block.tool_ref,
+                    result_present=block.result_present,
+                ))
+
+    source_line_by_record_id = {node.record_id: node.source_line for node in nodes}
+    branch_rows = []
+    for parent_id, child_groups in children.items():
+        if len(child_groups) <= 1:
+            continue
+        distinct_children = sorted(
+            child_groups.items(),
+            key=lambda pair: (
+                source_line_by_record_id[pair[1][0]], pair[0]
+            ),
+        )
+        branch_rows.append((
+            min(source_line_by_record_id[group[0]]
+                for _, group in distinct_children),
+            parent_id,
+            tuple(group[0] for _, group in distinct_children),
+        ))
+    branches = tuple(
+        ReadableBranchPoint(
+            parent_id,
+            occurrences[parent_id][0]
+            if len(occurrences[parent_id]) == 1 else None,
+            child_record_ids,
+        )
+        for _, parent_id, child_record_ids in sorted(branch_rows)
+    )
+    counts = Counter(item.code for item in source.diagnostics)
+    gap_count = counts["GRAPH_LINK_GAP"]
+    unknown_count = sum(
+        sum(block.policy == UNKNOWN for block in record.blocks) or
+        (record.policy == UNKNOWN)
+        for record in source.records
+    )
+    summary = ReadableDiagnosticSummary(
+        tuple(sorted(counts.items())), gap_count, unknown_count,
+    )
+    return ReadableGraph(
+        source.completeness, source.entrypoint, tuple(nodes), tuple(events),
+        tuple(hints), branches, summary,
+        sum(bool(node.text_blocks) for node in nodes),
+        sum(len(node.text_blocks) for node in nodes),
+        source.branch_count, gap_count, unknown_count,
+    )