iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/trajectory/event_types.py

@@ -0,0 +1,294 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Catalog of trajectory event types and closed enumerations.
+
+Readers skip (and count) event types outside :data:`KNOWN_EVENT_TYPES`. A value
+outside one of the enumerations below is never a reason to drop an event: it is
+decoded and handed on as written, and a consumer that groups by it shows it as
+``unknown`` rather than losing the row. Reason / error / failure fields carry
+these codes only — never free text.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Final
+
+
+class EventType:
+    """Every event type the writer may emit."""
+
+    # Coverage / runtime bookkeeping.
+    COVERAGE_STARTED = "trajectory.coverage.started"
+    COVERAGE_ENDED = "trajectory.coverage.ended"
+    GAP = "trajectory.gap"
+    CHECKPOINT = "trajectory.checkpoint"
+    RUNTIME_STARTED = "trajectory.runtime.started"
+    RUNTIME_RECOVERED = "trajectory.runtime.recovered"
+    RUNTIME_FINISHED = "trajectory.runtime.finished"
+    SEGMENT = "event.segment"
+
+    # Session lifecycle.
+    SESSION_STARTED = "session.started"
+    SESSION_FORKED = "session.forked"
+    SESSION_ROLLBACK = "session.rollback"
+    BRANCH_SUPERSEDED = "branch.superseded"
+    PROFILE_SWITCHED = "profile.switched"
+
+    # Turn lifecycle.
+    TURN_STARTED = "turn.started"
+    TURN_SUSPENDED = "turn.suspended"
+    TURN_RESUMED = "turn.resumed"
+    TURN_FINISHED = "turn.finished"
+    TURN_RESPONSE_SETTLED = "turn.response_settled"
+
+    WORKFLOW_RUN_STARTED = "workflow.run.started"
+    WORKFLOW_RUN_FINISHED = "workflow.run.finished"
+    WORKFLOW_NODE_STARTED = "workflow.node.started"
+    WORKFLOW_NODE_FINISHED = "workflow.node.finished"
+
+    # Admission / dispatch preparation. ``preparation.state`` is a marker,
+    # not a lifecycle terminal.
+    PREPARATION_STARTED = "preparation.started"
+    PREPARATION_FINISHED = "preparation.finished"
+    PREPARATION_STATE = "preparation.state"
+
+    # Model execution.
+    MODEL_RUN_STARTED = "model.run.started"
+    MODEL_RUN_FINISHED = "model.run.finished"
+    MODEL_CYCLE_STARTED = "model.cycle.started"
+    MODEL_CYCLE_FINISHED = "model.cycle.finished"
+    MODEL_EXCHANGE_STARTED = "model.exchange.started"
+    MODEL_EXCHANGE_FINISHED = "model.exchange.finished"
+    MODEL_VALIDATION_FINISHED = "model.validation.finished"
+
+    # Links, retries.
+    OPERATION_LINK_OBSERVED = "operation.link.observed"
+    RETRY_SCHEDULED = "retry.scheduled"
+    RETRY_STARTED = "retry.started"
+
+    # Tools, approvals, interrupts.
+    TOOL_OPERATION_STARTED = "tool.operation.started"
+    TOOL_OPERATION_FINISHED = "tool.operation.finished"
+    TOOL_PAYLOAD_OBSERVED = "tool.payload.observed"
+    APPROVAL_REQUESTED = "approval.requested"
+    APPROVAL_RESOLVED = "approval.resolved"
+    INTERRUPT_REQUESTED = "interrupt.requested"
+    INTERRUPT_OBSERVED = "interrupt.observed"
+
+    # Context revisions, hosted calls, compaction.
+    CONTEXT_REVISION_RECORDED = "context.revision.recorded"
+    HOSTED_CALL_OBSERVED = "hosted.call.observed"
+    COMPACTION_STARTED = "compaction.started"
+    COMPACTION_PHASE_FINISHED = "compaction.phase.finished"
+    COMPACTION_FINISHED = "compaction.finished"
+    COMPACTION_SKIPPED = "compaction.skipped"
+
+    # Sub-agents, waits, hooks, mutation summary.
+    SUB_AGENT_STARTED = "sub_agent.started"
+    SUB_AGENT_FINISHED = "sub_agent.finished"
+    WAIT_STARTED = "wait.started"
+    WAIT_FINISHED = "wait.finished"
+    HOOK_OPERATION_STARTED = "hook.operation.started"
+    HOOK_OPERATION_FINISHED = "hook.operation.finished"
+    TOOL_MUTATION_BATCH_SUMMARY = "tool.mutation_batch.summary"
+
+
+KNOWN_EVENT_TYPES: Final[frozenset[str]] = frozenset(
+    value for name, value in vars(EventType).items() if not name.startswith("_") and isinstance(value, str)
+)
+
+UNKNOWN: Final = "unknown"
+
+
+class WorkflowNodeOutcome(StrEnum):
+    """Terminal outcome of a workflow node attempt; retry waits are outside the attempt."""
+
+    COMPLETED = "completed"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+    CANCELLED = "cancelled"
+    ABANDONED = "abandoned"
+
+
+class CoverageReason:
+    """``trajectory.coverage.started.coverage_reason``."""
+
+    SESSION_STARTED = "session_started"
+    RUNTIME_RESUMED = "runtime_resumed"
+    FEATURE_INTRODUCED = "feature_introduced"
+
+
+class GapReason:
+    """``trajectory.gap.reason``."""
+
+    WRITE_TIMEOUT = "write_timeout"
+    WRITE_FAILURE = "write_failure"
+    LINE_BUDGET_EXCEEDED = "line_budget_exceeded"
+    VALUE_OUT_OF_RANGE = "value_out_of_range"
+    ENCODE_FAILURE = "encode_failure"
+    DEGRADED_CLOSE = "degraded_close"
+    RECOVERED_UNREADABLE = "recovered_unreadable"
+    """Slots an existing file spent on lines no reader can show (found at activation)."""
+
+
+class RuntimeFinishReason:
+    """``trajectory.runtime.finished.reason``."""
+
+    GRACEFUL_SHUTDOWN = "graceful_shutdown"
+    SESSION_SWITCH = "session_switch"
+
+
+class TurnEndReason:
+    """``turn.finished.end_reason`` — terminal states only."""
+
+    COMPLETED = "completed"
+    ERROR = "error"
+    INTERRUPTED = "interrupted"
+    CANCELLED = "cancelled"
+    SUPERSEDED = "superseded"
+    PROCESS_EXIT = "process_exit"
+
+
+class CompactionSkipReason:
+    """``compaction.skipped.reason_code`` — why usage past the trigger started no pass."""
+
+    DISABLED = "disabled"
+    """The agent's profile turns automatic compaction off."""
+    TURNS_UNRESOLVED = "turns_unresolved"
+    """The request's messages resolved to no turn, so there is nothing to compact against."""
+
+
+class TurnSuspendReason:
+    """``turn.suspended.reason``."""
+
+    AWAITING_SUB_AGENTS = "awaiting_sub_agents"
+
+
+class ExchangeOutcome:
+    """``model.exchange.finished.outcome``."""
+
+    SUCCESS = "success"
+    ERROR = "error"
+    CANCELLED = "cancelled"
+    ABANDONED = "abandoned"
+    STALLED = "stalled"
+    INTERRUPTED = "interrupted"
+
+
+class ValidationOutcome:
+    """``model.validation.finished.outcome``."""
+
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+
+
+class ValidationReason:
+    """``model.validation.finished.reason_code`` — why a response was rejected."""
+
+    NO_ASSISTANT_MESSAGE = "no_assistant_message"
+    EMPTY_CONTENTS = "empty_contents"
+    OUTPUT_TRUNCATED = "output_truncated"
+    REASONING_ONLY = "reasoning_only"
+    HOSTED_EVIDENCE_ONLY = "hosted_evidence_only"
+    CONTENT_FILTERED = "content_filtered"
+    WHITESPACE_ONLY = "whitespace_only"
+    LEAKED_TOOL_CALL = "leaked_tool_call"
+    RULE_VIOLATION = "rule_violation"
+    UNKNOWN = "unknown"
+
+
+class ToolOutcome:
+    """``tool.operation.finished.outcome``."""
+
+    SUCCESS = "success"
+    FAILED = "failed"
+    ERRORED = "errored"
+    INTERRUPTED = "interrupted"
+    TIMED_OUT = "timed_out"
+    REJECTED = "rejected"
+    INVALID_ARGUMENTS = "invalid_arguments"
+    UNKNOWN_TOOL = "unknown_tool"
+    FILTERED = "filtered"
+    UNKNOWN = "unknown"
+
+
+class TraceCoverage:
+    """``sub_agent.started.trace_coverage``."""
+
+    FULL = "full"
+    BOUNDARY_ONLY = "boundary_only"
+    UNAVAILABLE = "unavailable"
+
+
+class WaitCategory:
+    """``wait.started.category``."""
+
+    SUB_AGENT_CONCURRENCY = "sub_agent_concurrency"
+    USER_INPUT = "user_input"
+    MCP_CONNECT = "mcp_connect"
+    RATE_LIMIT = "rate_limit"
+    INPUT_ADMISSION = "input_admission"
+    TOOL_ADMISSION = "tool_admission"
+
+
+class ProfileKind:
+    """``profile.switched.kind``."""
+
+    AGENT = "agent"
+    MODEL = "model"
+
+
+class SourceRefKind:
+    """``source_ref.kind`` for derived summaries."""
+
+    SESSION_CHECKPOINT = "session_checkpoint"
+    SUB_AGENT_LOG = "sub_agent_log"
+    COMPRESSED_BLOCK = "compressed_block"
+
+
+class RetryMode:
+    """``retry.scheduled.retry_mode`` / ``retry.started.retry_mode``."""
+
+    WIRE = "wire"
+    """A wire attempt inside one model cycle is replayed (new exchange operation)."""
+    STALL_FALLBACK = "stall_fallback"
+    """A stalled stream is abandoned and re-acquired as a blocking exchange."""
+    RUN = "run"
+    """The whole model run is retried by the service-side retry loop."""
+    CONNECTION = "connection"
+    """An external agent connection/setup attempt is retried."""
+    COMPACTION = "compaction"
+    """A compaction side call is retried without replaying the model run."""
+    VALIDATION = "validation"
+    """The response was rejected by validation and the request is re-issued."""
+    CONTEXT_OVERFLOW = "context_overflow"
+    """The provider found the context window full; the request is re-issued once after compacting."""
+
+
+class RetryReason:
+    """``retry.scheduled.reason_code``."""
+
+    TRANSIENT_ERROR = "transient_error"
+    STREAM_STALL = "stream_stall"
+    VALIDATION_REJECTED = "validation_rejected"
+    RATE_LIMITED = "rate_limited"
+    CONNECTION = "connection"
+    UNKNOWN = "unknown"
+
+
+class ContinuationMode:
+    """``model.exchange.*.continuation_mode``."""
+
+    NONE = "none"
+    """A fresh create request."""
+    POLL = "poll"
+    """A retrieval of an already-created background response."""
+
+
+class ModelRunEndReason:
+    """``model.run.finished.outcome``."""
+
+    COMPLETED = "completed"
+    FAILED = "failed"
+    INTERRUPTED = "interrupted"

chrys/foundation/trajectory/finalizers.py

@@ -0,0 +1,46 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Pending operation settlement owned by one recorder, across producer replacements."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Callable
+
+logger = logging.getLogger(__name__)
+
+
+class RecordingFinalizers:
+    """Retain unfinished operations until their result arrives or the recorder closes.
+
+    Registration may run in the writer's sequence callback on another thread.
+    Close runs callbacks outside the lock so they can queue their final events.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._callbacks: set[Callable[[], None]] = set()
+        self._closed = False
+
+    def add(self, callback: Callable[[], None]) -> None:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("Trajectory recorder closed before operation start")
+            self._callbacks.add(callback)
+
+    def discard(self, callback: Callable[[], None]) -> None:
+        with self._lock:
+            self._callbacks.discard(callback)
+
+    def close(self) -> None:
+        """Settle each remaining operation once, before the writer freezes."""
+        with self._lock:
+            self._closed = True
+            callbacks = tuple(self._callbacks)
+            self._callbacks.clear()
+        for callback in callbacks:
+            try:
+                callback()
+            except Exception:
+                logger.warning("Trajectory operation settlement failed", exc_info=True)

chrys/foundation/trajectory/fingerprint.py

@@ -0,0 +1,62 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Keyed, domain-separated fingerprints for content-minimized events.
+
+``argument_fingerprint`` / ``content_fingerprint`` / segment ``value_hash`` must
+never be bare digests: the fingerprinted value may be user content, and a bare
+SHA leaves an enumerable fingerprint behind. Every fingerprint is an HMAC over
+``domain || 0x00 || data`` with a per-installation secret key, so equal inputs
+in different domains never collide and nothing is recoverable without the key.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from collections.abc import Mapping
+from typing import Any, Final
+
+FINGERPRINT_KEY_BYTES: Final = 32
+
+DOMAIN_TOOL_ARGUMENTS: Final = "chrys.trajectory.tool_arguments"
+DOMAIN_TOOL_CONTENT: Final = "chrys.trajectory.tool_content"
+DOMAIN_SEGMENT_VALUE: Final = "chrys.trajectory.segment_value"
+DOMAIN_WORKSPACE: Final = "chrys.trajectory.workspace"
+DOMAIN_MEMBERSHIP: Final = "chrys.trajectory.context_membership"
+
+
+def keyed_fingerprint(key: bytes, domain: str, data: bytes) -> str:
+    """Return the hex HMAC-SHA256 of *data* under *key*, separated by *domain*."""
+    if not key:
+        raise ValueError("Fingerprint key must not be empty.")
+    if not domain or "\x00" in domain:
+        raise ValueError("Fingerprint domain must be a non-empty string without NUL bytes.")
+    mac = hmac.new(key, domain.encode("utf-8") + b"\x00" + data, hashlib.sha256)
+    return mac.hexdigest()
+
+
+def canonical_json_bytes(value: Mapping[str, Any] | list[Any] | str | int | float | bool | None) -> bytes:
+    """Encode a JSON value canonically (sorted keys, ASCII, compact) for hashing.
+
+    ``ensure_ascii=True`` keeps the encoding injective for surrogate-bearing
+    strings: a raw ``\\udcXX`` and a literal ``\\\\udcXX`` never alias.
+    """
+    return json.dumps(value, sort_keys=True, ensure_ascii=True, separators=(",", ":"), default=str).encode("ascii")
+
+
+def fingerprint_json(
+    key: bytes, domain: str, value: Mapping[str, Any] | list[Any] | str | int | float | bool | None
+) -> str:
+    """Fingerprint a JSON-compatible value under *domain*."""
+    return keyed_fingerprint(key, domain, canonical_json_bytes(value))
+
+
+def fingerprint_text(key: bytes, domain: str, text: str) -> str:
+    """Fingerprint a text value under *domain* (lone surrogates encoded, never raised).
+
+    ``surrogatepass`` is total like ``backslashreplace`` but also injective:
+    an escape sequence a user typed never encodes to the same bytes as the
+    surrogate it spells, so two different values never share a fingerprint.
+    """
+    return keyed_fingerprint(key, domain, text.encode("utf-8", errors="surrogatepass"))

chrys/foundation/trajectory/ids.py

@@ -0,0 +1,155 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Identifier minting and format classification for trajectory events.
+
+IDs are classified **by origin, not by suffix**:
+
+* Chrys-generated analytics IDs (``event_id``, ``operation_id``, ``turn_id``,
+  ``analytics_item_id``, ...) are 32 lowercase hex characters. Any ID field
+  not registered below defaults to this class.
+* Existing Chrys IDs keep their native shape: ``session_id`` is a canonical
+  UUID string (pre-refactor sessions: 12 hex), ``invocation_id`` /
+  ``sub_agent_log_id`` are 12 lowercase hex characters, profile IDs are
+  bounded opaque strings compared by fingerprint, and a compressed block's
+  ``compressed_context_id`` keeps the ``ctx_`` + 8 hex shape the session
+  already persists and shows (so pre-existing blocks stay referenceable).
+* External opaque IDs (provider ``response_id``, ``child_session_id``, ...)
+  and user-configured identifiers such as ``hook_id`` are bounded printable
+  strings and never validated as hex. A spilled tool result's ``artifact_id``
+  is the artifact's file *name* — bounded, printable and separator-free, so a
+  path can never be recorded in its place.
+
+Reference fields inherit the format of the ID they point to, so validation
+runs uniformly over every ``*_id`` key without per-field allow-lists.
+"""
+
+from __future__ import annotations
+
+import re
+import secrets
+from enum import Enum
+
+ANALYTICS_ID_HEX_LENGTH = 32
+INVOCATION_ID_HEX_LENGTH = 12
+OPAQUE_ID_MAX_LENGTH = 512
+
+_ANALYTICS_ID_RE = re.compile(r"^[0-9a-f]{32}$")
+_INVOCATION_ID_RE = re.compile(r"^[0-9a-f]{12}$")
+_SESSION_ID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+_COMPRESSED_CONTEXT_ID_RE = re.compile(r"^ctx_[0-9a-f]{8}$")
+ARTIFACT_ID_MAX_LENGTH = 128
+_ARTIFACT_ID_SEPARATORS = frozenset({"/", "\\", "\x00"})
+
+
+class IdClass(Enum):
+    """Format class of an identifier field."""
+
+    ANALYTICS = "analytics"
+    SESSION = "session"
+    INVOCATION = "invocation"
+    COMPRESSED_CONTEXT = "compressed_context"
+    ARTIFACT = "artifact"
+    PROFILE = "profile"
+    OPAQUE = "opaque"
+
+
+_OPAQUE_FIELDS = frozenset(
+    {
+        "response_id",
+        "child_session_id",
+        "hook_id",
+        "provider_request_id",
+        "transport_exchange_id",
+    }
+)
+_SESSION_FIELDS = frozenset({"session_id", "origin_session_id"})
+_INVOCATION_FIELDS = frozenset({"invocation_id", "sub_agent_log_id"})
+_COMPRESSED_CONTEXT_FIELDS = frozenset({"compressed_context_id"})
+_ARTIFACT_FIELDS = frozenset({"artifact_id"})
+_PROFILE_FIELDS = frozenset({"agent_profile_id", "model_profile_id"})
+
+
+def new_analytics_id() -> str:
+    """Mint a fresh 32-hex analytics identifier."""
+    return secrets.token_hex(ANALYTICS_ID_HEX_LENGTH // 2)
+
+
+def classify_id_field(field_name: str) -> IdClass:
+    """Return the format class for an ID-bearing field name.
+
+    Registered exact names win; everything else that looks like an ID
+    (``*_id``) is an analytics ID by default, which is exactly the
+    "any new ID falls into the analytics class unless registered" rule.
+    """
+    if field_name in _OPAQUE_FIELDS:
+        return IdClass.OPAQUE
+    if field_name in _SESSION_FIELDS:
+        return IdClass.SESSION
+    if field_name in _INVOCATION_FIELDS:
+        return IdClass.INVOCATION
+    if field_name in _COMPRESSED_CONTEXT_FIELDS:
+        return IdClass.COMPRESSED_CONTEXT
+    if field_name in _ARTIFACT_FIELDS:
+        return IdClass.ARTIFACT
+    if field_name in _PROFILE_FIELDS:
+        return IdClass.PROFILE
+    return IdClass.ANALYTICS
+
+
+def is_id_field(field_name: str) -> bool:
+    """Return whether a payload/envelope key carries an identifier."""
+    return field_name == "item_id" or field_name.endswith("_id")
+
+
+def is_valid_analytics_id(value: object) -> bool:
+    """Return whether *value* is a 32-hex analytics identifier."""
+    return isinstance(value, str) and _ANALYTICS_ID_RE.fullmatch(value) is not None
+
+
+def is_valid_session_id(value: object) -> bool:
+    """Return whether *value* is a canonical UUID string (or a legacy 12-hex id)."""
+    if not isinstance(value, str):
+        return False
+    return _SESSION_ID_RE.fullmatch(value) is not None or _INVOCATION_ID_RE.fullmatch(value) is not None
+
+
+def is_valid_invocation_id(value: object) -> bool:
+    """Return whether *value* is a 12-hex sub-agent invocation identifier."""
+    return isinstance(value, str) and _INVOCATION_ID_RE.fullmatch(value) is not None
+
+
+def is_valid_compressed_context_id(value: object) -> bool:
+    """Return whether *value* is a session compressed-block identifier (``ctx_`` + 8 hex)."""
+    return isinstance(value, str) and _COMPRESSED_CONTEXT_ID_RE.fullmatch(value) is not None
+
+
+def is_valid_artifact_id(value: object) -> bool:
+    """Return whether *value* is a bare artifact file name (never a path)."""
+    if not isinstance(value, str) or not value or len(value) > ARTIFACT_ID_MAX_LENGTH:
+        return False
+    if value in {".", ".."} or any(ch in _ARTIFACT_ID_SEPARATORS for ch in value):
+        return False
+    return all(ch.isprintable() for ch in value)
+
+
+def is_valid_opaque_id(value: object) -> bool:
+    """Return whether *value* is a bounded printable opaque identifier."""
+    if not isinstance(value, str) or not value or len(value) > OPAQUE_ID_MAX_LENGTH:
+        return False
+    return all(ch.isprintable() for ch in value)
+
+
+def is_valid_id(field_name: str, value: object) -> bool:
+    """Validate *value* against the format class implied by *field_name*."""
+    id_class = classify_id_field(field_name)
+    if id_class is IdClass.ANALYTICS:
+        return is_valid_analytics_id(value)
+    if id_class is IdClass.SESSION:
+        return is_valid_session_id(value)
+    if id_class is IdClass.INVOCATION:
+        return is_valid_invocation_id(value)
+    if id_class is IdClass.COMPRESSED_CONTEXT:
+        return is_valid_compressed_context_id(value)
+    if id_class is IdClass.ARTIFACT:
+        return is_valid_artifact_id(value)
+    return is_valid_opaque_id(value)

chrys/foundation/trajectory/keys.py

@@ -0,0 +1,99 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Per-installation fingerprint key for trajectory events.
+
+Mirrors the ACP audit key precedent (``~/.chrys/acp-audit-hmac.key``): an
+owner-only 32-byte secret published with a no-replace ``link`` so a racing
+creator can never overwrite a key another process already used.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import secrets
+import stat
+from pathlib import Path
+
+from chrys.foundation.platform.files import (
+    SecureFileError,
+    secure_open_owner_only,
+    secure_open_owner_only_binary,
+    secure_unlink_owner_verified,
+)
+from chrys.foundation.trajectory.fingerprint import FINGERPRINT_KEY_BYTES
+from chrys.foundation.util.lock import FileLock
+
+TRAJECTORY_KEY_FILE_NAME = "trajectory-hmac.key"
+
+
+def ensure_owner_only_directory(path: Path) -> None:
+    """Create *path* privately (0700) and tighten an existing POSIX mode."""
+    from chrys.foundation.platform import get_platform
+
+    path.mkdir(mode=0o700, parents=True, exist_ok=True)
+    if get_platform().is_windows:
+        return
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_CLOEXEC", 0)
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    fd = os.open(path, flags)
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISDIR(info.st_mode):
+            raise OSError(f"Owner-only path is not a directory: {path}")
+        os.fchmod(fd, 0o700)
+    finally:
+        os.close(fd)
+
+
+def load_or_create_fingerprint_key(config_dir: Path, *, timeout: float = 5.0) -> bytes:
+    """Validate or no-replace-create the installation trajectory fingerprint key."""
+    config_dir.mkdir(parents=True, exist_ok=True)
+    key_path = config_dir / TRAJECTORY_KEY_FILE_NAME
+    lock_path = config_dir / f"{TRAJECTORY_KEY_FILE_NAME}.lock"
+    with FileLock(lock_path, timeout=timeout):
+        if key_path.exists() or key_path.is_symlink():
+            return _read_key(key_path)
+        temp_path = config_dir / f".{TRAJECTORY_KEY_FILE_NAME}.{secrets.token_hex(8)}.tmp"
+        fd = secure_open_owner_only(temp_path, write=True, create=True)
+        try:
+            key = secrets.token_bytes(FINGERPRINT_KEY_BYTES)
+            with os.fdopen(fd, "wb") as file:
+                fd = -1
+                file.write(key)
+                file.flush()
+                os.fsync(file.fileno())
+            try:
+                os.link(temp_path, key_path, follow_symlinks=False)
+            except FileExistsError:
+                return _read_key(key_path)
+            _fsync_parent(config_dir)
+            return _read_key(key_path)
+        finally:
+            if fd >= 0:
+                os.close(fd)
+            secure_unlink_owner_verified(temp_path)
+
+
+def _read_key(path: Path) -> bytes:
+    try:
+        with secure_open_owner_only_binary(path) as file:
+            key = file.read(FINGERPRINT_KEY_BYTES + 1)
+    except OSError as exc:
+        raise SecureFileError("The trajectory fingerprint key failed secure verification.") from exc
+    if len(key) != FINGERPRINT_KEY_BYTES:
+        raise SecureFileError("The trajectory fingerprint key has an invalid length.")
+    return key
+
+
+def _fsync_parent(path: Path) -> None:
+    from chrys.foundation.platform import get_platform
+
+    if get_platform().is_windows:
+        return
+    with contextlib.suppress(OSError):
+        fd = os.open(path, os.O_RDONLY)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)