iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/trajectory/lease.py

@@ -0,0 +1,173 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Session writer lease: one trajectory writer per session, across processes.
+
+The lease is an OS-level file lock on ``<session>/trajectory/writer.lock``. It
+is bound to the *writer worker*, not to the "currently active session": the UI
+may switch sessions while a stuck worker still holds the descriptor, and the
+lease keeps following that worker until it exits (or the OS reclaims it when
+the process dies — at which point the stuck thread is gone too).
+
+Acquisition never blocks: a held lease means "this session already has a
+writer somewhere", and the caller opens the session trajectory-disabled.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import threading
+from pathlib import Path
+from typing import Any, cast
+
+from chrys.foundation.platform.files import SecureFileError, secure_open_owner_only_append
+
+WRITER_LEASE_FILE_NAME = "writer.lock"
+
+_HELD_LEASES: dict[str, WriterLease] = {}
+_HELD_GUARD = threading.Lock()
+
+
+def _lease_key(path: Path) -> str:
+    return os.path.normcase(str(path.absolute()))
+
+
+def _try_lock_fd(fd: int) -> bool:
+    from chrys.foundation.platform import get_platform
+
+    if get_platform().is_windows:
+        import msvcrt
+
+        locking = cast(Any, msvcrt)
+        try:
+            os.lseek(fd, 0, os.SEEK_SET)
+            locking.locking(fd, locking.LK_NBLCK, 1)
+        except OSError:
+            return False
+        return True
+    import fcntl
+
+    # Same shape as the Windows branch above: the members exist only on the
+    # platform the branch runs on, so the type checker is told the module is
+    # opaque rather than asked to resolve them for the other one.
+    flock = cast(Any, fcntl)
+    try:
+        flock.flock(fd, flock.LOCK_EX | flock.LOCK_NB)
+    except BlockingIOError:
+        return False
+    except OSError:
+        return False
+    return True
+
+
+def _unlock_fd(fd: int) -> None:
+    from chrys.foundation.platform import get_platform
+
+    with contextlib.suppress(OSError):
+        if get_platform().is_windows:
+            import msvcrt
+
+            locking = cast(Any, msvcrt)
+            os.lseek(fd, 0, os.SEEK_SET)
+            locking.locking(fd, locking.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            flock = cast(Any, fcntl)
+            flock.flock(fd, flock.LOCK_UN)
+
+
+class WriterLease:
+    """A held writer lease; release it only when the worker has exited."""
+
+    def __init__(self, path: Path, fd: int) -> None:
+        self._path = path
+        self._fd = fd
+        self._released = False
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @property
+    def held(self) -> bool:
+        return not self._released
+
+    @classmethod
+    def try_acquire(cls, path: Path) -> WriterLease | None:
+        """Acquire the lease at *path* without waiting; ``None`` when held elsewhere.
+
+        The in-process registry is the fast path; the OS lock is the truth
+        across processes. The lock file is owner-only and opened with
+        delete-sharing on Windows so the session directory stays renamable.
+        The parent directory must already exist; open failures other than
+        contention propagate as ``SecureFileError``/``OSError``.
+        """
+        key = _lease_key(path)
+        with _HELD_GUARD:
+            if key in _HELD_LEASES:
+                return None
+            handle = secure_open_owner_only_append(path)
+            if not _try_lock_fd(handle.fd):
+                os.close(handle.fd)
+                return None
+            lease = cls(path, handle.fd)
+            _HELD_LEASES[key] = lease
+            return lease
+
+    @classmethod
+    def is_held_elsewhere(cls, path: Path) -> bool:
+        """Return whether another holder owns the lease at *path* right now.
+
+        Used by the tombstone sweep: a tombstone whose lease is still held may
+        still be written by a stuck worker in another process and must be left
+        alone. A missing lock file means no holder.
+        """
+        if not path.is_file():
+            return False
+        try:
+            probe = cls.try_acquire(path)
+        except SecureFileError, OSError:
+            # Cannot even open the lock file: fail closed, treat it as held.
+            return True
+        if probe is None:
+            return True
+        probe.release()
+        return False
+
+    @classmethod
+    def relocate(cls, old_path: Path, new_path: Path) -> None:
+        """Re-key a held lease whose lock file moved with its directory.
+
+        The lock lives on the inode, so the holder does not change — only the
+        name the in-process registry answers under. Without this a session
+        recreated at the old path is refused a writer that nothing holds.
+        """
+        old_key = _lease_key(old_path)
+        with _HELD_GUARD:
+            lease = _HELD_LEASES.pop(old_key, None)
+            if lease is None or lease._released:
+                # A released lease holds nothing; re-keying one would leave the
+                # registry answering "held" under the new name forever.
+                return
+            lease._path = new_path
+            _HELD_LEASES[_lease_key(new_path)] = lease
+
+    def release(self) -> None:
+        """Release the lease (idempotent)."""
+        # Whole body under the registry guard: the key to remove is derived
+        # from ``_path``, and ``relocate`` rewrites that field. Reading it
+        # outside lets a relocation land in between, so the removal looks for
+        # the old name while the registry now holds this lease under the new
+        # one — leaving a phantom holder that refuses every later writer.
+        with _HELD_GUARD:
+            if self._released:
+                return
+            self._released = True
+            key = _lease_key(self._path)
+            if _HELD_LEASES.get(key) is self:
+                del _HELD_LEASES[key]
+            _unlock_fd(self._fd)
+            with contextlib.suppress(OSError):
+                os.close(self._fd)
+            self._fd = -1

chrys/foundation/trajectory/metadata.py

@@ -0,0 +1,72 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Stable analytics identifiers stamped on persisted conversation items.
+
+``session.json`` stays the conversation truth; the trajectory log refers to
+its items by two additional-properties keys rather than by position:
+
+* ``_chrys_analytics_item_id`` — one per persisted message / tool-call
+  content / tool-result content, minted when the item is created (or, as a
+  backstop, right before the save that first persists it) and never changed
+  afterwards. Save/restore, compaction, fork and rollback copy the property
+  verbatim, which is what makes the id stable.
+* ``_chrys_operation_id`` — the trajectory operation the item belongs to:
+  the model exchange that produced an assistant message, or the tool
+  operation a call content and its paired result content share.
+
+Both are 32 lowercase hex characters (see :mod:`chrys.foundation.trajectory.ids`).
+Values that fail that shape are treated as absent.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+from typing import Any, Final
+
+from chrys.foundation.trajectory.ids import is_valid_analytics_id, new_analytics_id
+
+ANALYTICS_ITEM_ID_KEY: Final = "_chrys_analytics_item_id"
+OPERATION_ID_KEY: Final = "_chrys_operation_id"
+
+TOOL_PARENT_OPERATION_METADATA_KEY: Final = "_chrys_trajectory_parent_operation_id"
+"""Invocation-context key: the model exchange operation the tool call belongs to (never persisted)."""
+TOOL_RESULT_ITEM_ID_METADATA_KEY: Final = "_chrys_trajectory_result_item_id"
+"""Invocation-context key: the item id pre-minted for the call's result content (never persisted)."""
+TOOL_RESULT_CARRIER_ITEM_ID_METADATA_KEY: Final = "_chrys_trajectory_result_carrier_item_id"
+"""Invocation-context key: the item id pre-minted for the result batch's carrier message (never persisted)."""
+
+
+def read_analytics_item_id(additional_properties: object) -> str | None:
+    """Return the stamped item id, or ``None`` when absent or malformed."""
+    return _read(additional_properties, ANALYTICS_ITEM_ID_KEY)
+
+
+def read_operation_id(additional_properties: object) -> str | None:
+    """Return the stamped operation id, or ``None`` when absent or malformed."""
+    return _read(additional_properties, OPERATION_ID_KEY)
+
+
+def ensure_analytics_item_id(additional_properties: MutableMapping[str, Any], *, item_id: str | None = None) -> str:
+    """Return the item id, stamping *item_id* (or a fresh id) when none is set.
+
+    An existing valid id always wins: ids are minted once and never rewritten.
+    """
+    existing = read_analytics_item_id(additional_properties)
+    if existing is not None:
+        return existing
+    value = item_id if item_id is not None and is_valid_analytics_id(item_id) else new_analytics_id()
+    additional_properties[ANALYTICS_ITEM_ID_KEY] = value
+    return value
+
+
+def stamp_operation_id(additional_properties: MutableMapping[str, Any], operation_id: str) -> None:
+    """Bind the item to *operation_id*; malformed ids are ignored."""
+    if is_valid_analytics_id(operation_id):
+        additional_properties[OPERATION_ID_KEY] = operation_id
+
+
+def _read(additional_properties: object, key: str) -> str | None:
+    if not isinstance(additional_properties, Mapping):
+        return None
+    value = additional_properties.get(key)
+    return value if isinstance(value, str) and is_valid_analytics_id(value) else None

chrys/foundation/trajectory/reader.py

@@ -0,0 +1,271 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Read-only access to a trajectory events file with corruption diagnostics.
+
+The reader never writes back. A torn trailing line is reported (and handled
+by the writer's recovery path); a bad line in the *middle* of the file is
+corruption and yields an in-memory diagnostic gap rather than being skipped
+silently. Unknown event types — and events written under a schema this build
+does not know — are decoded, counted, and reported so that the region they
+fall in is never declared exact by downstream analysis.
+"""
+
+from __future__ import annotations
+
+from bisect import bisect_left
+from collections.abc import Iterable, Iterator, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from chrys.foundation.trajectory.envelope import (
+    SCHEMA_VERSION,
+    EnvelopeError,
+    TrajectoryEvent,
+    decode_event_line,
+    iter_complete_lines,
+    peek_envelope_header,
+)
+from chrys.foundation.trajectory.event_types import KNOWN_EVENT_TYPES, EventType
+
+
+@dataclass(frozen=True, slots=True)
+class CorruptLine:
+    """One undecodable complete line in the middle of the file."""
+
+    line_number: int
+    byte_offset: int
+    byte_length: int
+    reason: str
+    previous_sequence: int
+    """Sequence of the last valid event before this line (0 when none)."""
+
+
+@dataclass(frozen=True, slots=True)
+class UnsupportedLine:
+    """A complete line written under a schema this build was never meant to read."""
+
+    line_number: int
+    byte_offset: int
+    sequence: int
+    schema_version: int
+
+
+@dataclass(frozen=True, slots=True)
+class ReaderGap:
+    """A sequence range the reader cannot account for (diagnostic, in-memory)."""
+
+    after_sequence: int
+    before_sequence: int | None
+    reason: str
+
+
+@dataclass(slots=True)
+class TrajectoryReadResult:
+    """Decoded events plus everything the reader could not vouch for."""
+
+    events: list[TrajectoryEvent] = field(default_factory=list)
+    corrupt_lines: list[CorruptLine] = field(default_factory=list)
+    torn_tail_bytes: int = 0
+    unsupported_event_count: int = 0
+    """Events this build cannot vouch for: an unknown type, or a newer schema."""
+    unsupported_event_sequences: list[int] = field(default_factory=list)
+    unsupported_lines: list[UnsupportedLine] = field(default_factory=list)
+    """Newer-schema lines kept out of *events*: their slots are real, their content is not readable here."""
+    slots: list[TrajectoryEvent | UnsupportedLine] = field(default_factory=list)
+    """Every line the file kept, decoded or not, in file order — what the prefix invariant is checked over."""
+
+    @property
+    def corruption_gaps(self) -> list[ReaderGap]:
+        """Diagnostic gaps implied by corrupt lines, positioned between neighbours."""
+        gaps: list[ReaderGap] = []
+        for corrupt in self.corrupt_lines:
+            following = [e.sequence for e in self.events if e.sequence > corrupt.previous_sequence]
+            gaps.append(
+                ReaderGap(
+                    after_sequence=corrupt.previous_sequence,
+                    before_sequence=min(following) if following else None,
+                    reason=corrupt.reason,
+                )
+            )
+        return gaps
+
+
+def iter_file_lines(path: Path, *, chunk_size: int = 1 << 16) -> Iterator[tuple[int, bytes, bool]]:
+    """Yield ``(byte_offset, line_without_newline, complete)`` for each line.
+
+    The final tuple has ``complete=False`` only when the file ends without a
+    newline (a torn tail); its bytes are the partial line.
+    """
+    offset = 0
+    pending = b""
+    with path.open("rb") as handle:
+        while True:
+            chunk = handle.read(chunk_size)
+            if not chunk:
+                break
+            lines, pending = iter_complete_lines(pending + chunk)
+            for line in lines:
+                yield offset, line, True
+                offset += len(line) + 1
+    if pending:
+        yield offset, pending, False
+
+
+def read_trajectory(
+    path: Path,
+    *,
+    known_event_types: frozenset[str] = KNOWN_EVENT_TYPES,
+) -> TrajectoryReadResult:
+    """Decode every line of *path* into a :class:`TrajectoryReadResult`."""
+    result = TrajectoryReadResult()
+    if not path.is_file():
+        return result
+    line_number = 0
+    previous_sequence = 0
+    for offset, raw, complete in iter_file_lines(path):
+        if not complete:
+            result.torn_tail_bytes = len(raw)
+            break
+        line_number += 1
+        try:
+            event = decode_event_line(raw)
+        except EnvelopeError as exc:
+            newer = _newer_schema_line(raw, line_number=line_number, byte_offset=offset)
+            if newer is not None:
+                # A schema is bumped exactly when lines stop meaning what this
+                # build reads them as, so failing this build's shape is what a
+                # newer line is supposed to do — it is not damage. The slot is
+                # real and stays accounted for; only the content is out of
+                # reach.
+                result.unsupported_lines.append(newer)
+                result.slots.append(newer)
+                result.unsupported_event_count += 1
+                result.unsupported_event_sequences.append(newer.sequence)
+                previous_sequence = newer.sequence
+                continue
+            result.corrupt_lines.append(
+                CorruptLine(
+                    line_number=line_number,
+                    byte_offset=offset,
+                    byte_length=len(raw) + 1,
+                    reason=str(exc),
+                    previous_sequence=previous_sequence,
+                )
+            )
+            continue
+        result.events.append(event)
+        result.slots.append(event)
+        previous_sequence = event.sequence
+        if event.schema_version > SCHEMA_VERSION or event.event_type not in known_event_types:
+            # A newer line that still fits this build's shape is reported the
+            # same way an unknown type is: kept, accounted for, and named, so
+            # nothing downstream calls the region it sits in exact.
+            result.unsupported_event_count += 1
+            result.unsupported_event_sequences.append(event.sequence)
+    return result
+
+
+def verify_accounted_prefix(records: Iterable[TrajectoryEvent | UnsupportedLine]) -> list[str]:
+    """Check the accounted-prefix invariant over *records* in file order.
+
+    Physical sequences must be strictly increasing with no duplicates; every
+    hole must be covered by a ``trajectory.gap`` persisted **before** the first
+    event after the hole. Returns human-readable violations (empty = holds).
+
+    A line this build could not decode still took a slot on the disk it was
+    written to, and it took that slot *somewhere* — so pass
+    :attr:`TrajectoryReadResult.slots` to hold the file itself to the
+    invariant; ``events`` alone answers only for the decoded stream.
+    """
+    violations: list[str] = []
+    covered = CoveredSequenceRanges()
+    # The prefix starts at 1, so the file's own first line is held to the same
+    # rule as every later one: a log that opens at 2 is missing its head unless
+    # a gap on that first line says where it went.
+    previous = 0
+    for record in records:
+        sequence = record.sequence
+        if isinstance(record, TrajectoryEvent) and record.event_type == EventType.GAP:
+            first = record.payload.get("first_sequence")
+            last = record.payload.get("last_sequence")
+            if isinstance(first, int) and isinstance(last, int) and first <= last:
+                covered.add(first, last)
+        if sequence <= previous:
+            violations.append(f"sequence {sequence} does not increase after {previous}")
+        elif sequence > previous + 1:
+            hole = covered.first_uncovered(previous + 1, sequence - 1)
+            if hole is not None:
+                violations.append(f"sequence {hole} is missing and not covered by an earlier gap")
+        previous = sequence
+    return violations
+
+
+def _newer_schema_line(raw: bytes, *, line_number: int, byte_offset: int) -> UnsupportedLine | None:
+    header = peek_envelope_header(raw)
+    if header is None or header.schema_version <= SCHEMA_VERSION:
+        return None
+    return UnsupportedLine(
+        line_number=line_number,
+        byte_offset=byte_offset,
+        sequence=header.sequence,
+        schema_version=header.schema_version,
+    )
+
+
+class CoveredSequenceRanges:
+    """Union of gap-covered sequence ranges, kept sorted, disjoint and merged.
+
+    A log can carry a gap per event that failed to encode, so a long unhealthy
+    session accumulates thousands of them — and every hole consults the whole
+    accumulated history, which is quadratic when each lookup re-sorts the list.
+    Kept merged, both recording a range and finding a hole bisect instead.
+    """
+
+    __slots__ = ("_ranges",)
+
+    def __init__(self) -> None:
+        self._ranges: list[tuple[int, int]] = []
+
+    def add(self, first: int, last: int) -> None:
+        """Record that a gap accounts for every sequence in ``[first, last]``."""
+        if last < first:
+            return
+        ranges = self._ranges
+        # Every stored range that overlaps or touches the new one merges with
+        # it; over integers, "touches" reaches one past either end.
+        lo = bisect_left(ranges, first - 1, key=_range_end)
+        hi = bisect_left(ranges, (last + 2,))
+        if lo < hi:
+            first = min(first, ranges[lo][0])
+            last = max(last, ranges[hi - 1][1])
+        ranges[lo:hi] = [(first, last)]
+
+    def first_uncovered(self, first: int, last: int) -> int | None:
+        """The lowest sequence in ``[first, last]`` no gap accounts for, if any.
+
+        Checked as intervals rather than one sequence at a time: a file
+        claiming a jump of billions is corrupt, not a reason to count to a
+        billion.
+        """
+        if last < first:
+            return None
+        ranges = self._ranges
+        index = bisect_left(ranges, (first + 1,)) - 1
+        if index < 0 or ranges[index][1] < first:
+            return first
+        # Merged ranges are disjoint with a break between neighbours, so the
+        # first sequence past the covering range is uncovered.
+        cursor = ranges[index][1] + 1
+        return cursor if cursor <= last else None
+
+
+def _range_end(covered_range: tuple[int, int]) -> int:
+    return covered_range[1]
+
+
+def last_event_of_type(events: Sequence[TrajectoryEvent], event_type: str) -> TrajectoryEvent | None:
+    """Return the last event of *event_type* in *events*, if any."""
+    for event in reversed(events):
+        if event.event_type == event_type:
+            return event
+    return None