Crate rch_common 

Remote Compilation Helper - Common Library

Shared types, patterns, and utilities used by rch, rchd, and rch-wkr.

Re-exports

pub use artifact_cost::ArtifactCostReport;

pub use artifact_cost::ArtifactPhaseTimings;

pub use artifact_cost::GlobAdvice;

pub use artifact_cost::RetrievalMode;

pub use artifact_cost::assess_glob_expansion;

pub use artifact_cost::compute_artifact_cost;

pub use artifact_cost::is_broad_recursive_glob;

pub use artifact_pattern::ARTIFACT_OUTPUT_ROOTS;

pub use artifact_pattern::ArtifactPatternRewrite;

pub use artifact_pattern::ArtifactRetrievalDiagnostics;

pub use artifact_pattern::artifact_dest_is_safe;

pub use artifact_pattern::rewrite_artifact_pattern;

pub use artifact_verify::ArtifactManifest;

pub use artifact_verify::FileHash;

pub use artifact_verify::VerificationFailure;

pub use artifact_verify::VerificationResult;

pub use artifact_verify::compute_file_hash;

pub use artifact_verify::create_manifest;

pub use artifact_verify::verify_artifacts;

pub use binary_hash::BinaryHashResult;

pub use binary_hash::binaries_equivalent;

pub use binary_hash::binary_contains_marker;

pub use binary_hash::compute_binary_hash;

pub use bypass_record::AutoRejoinCriteria;

pub use bypass_record::BypassBackoff;

pub use bypass_record::BypassFailureClass;

pub use bypass_record::BypassRecord;

pub use bypass_record::BypassRecordStore;

pub use bypass_record::BypassState;

pub use bypass_record::DisabledMigration;

pub use bypass_record::DisabledWorkerSnapshot;

pub use bypass_record::MAX_DIAGNOSTIC_CHARS;

pub use bypass_record::bypass_record_schema;

pub use bypass_record::bypass_record_schema_version;

pub use bypass_record::classify_disable_reason;

pub use bypass_record::default_bypass_record_path;

pub use bypass_record::migrate_disabled_worker;

pub use bypass_record::truncate_diagnostic;

pub use bypass_recovery::CanaryDecision;

pub use bypass_recovery::CanaryOutcome;

pub use bypass_recovery::ProbeDecision;

pub use bypass_recovery::RecoveryProbe;

pub use bypass_recovery::decide_canary;

pub use bypass_recovery::decide_probe;

pub use cargo_path_deps::CargoPathDependencyEdge;

pub use cargo_path_deps::CargoPathDependencyError;

pub use cargo_path_deps::CargoPathDependencyErrorKind;

pub use cargo_path_deps::CargoPathDependencyGraph;

pub use cargo_path_deps::CargoPathDependencyPackage;

pub use cargo_path_deps::CargoPathMaterializationClosure;

pub use cargo_path_deps::resolve_cargo_path_dependency_graph;

pub use cargo_path_deps::resolve_cargo_path_dependency_graph_with_policy;

pub use cargo_path_deps::resolve_cargo_path_materialization_closure;

pub use cargo_path_deps::resolve_cargo_path_materialization_closure_with_policy;

pub use closure_explain::ClosureExplainEntry;

pub use closure_explain::ClosureExplainReport;

pub use closure_explain::RootConvergence;

pub use closure_explain::RootSyncOutcome;

pub use closure_explain::derive_outcome;

pub use closure_explain::explain_closure;

pub use dependency_closure_planner::DependencyClosurePlan;

pub use dependency_closure_planner::DependencyClosurePlanState;

pub use dependency_closure_planner::DependencyPlanIssue;

pub use dependency_closure_planner::DependencyRiskClass;

pub use dependency_closure_planner::DependencySyncAction;

pub use dependency_closure_planner::DependencySyncMetadata;

pub use dependency_closure_planner::DependencySyncReason;

pub use dependency_closure_planner::build_dependency_closure_plan;

pub use dependency_closure_planner::build_dependency_closure_plan_with_policy;

pub use dependency_closure_planner::plan_dependency_closure_from_graph;

pub use force_resync::ForceResyncPlan;

pub use force_resync::ForceResyncReport;

pub use force_resync::InvalidationAction;

pub use force_resync::RefusedInvalidation;

pub use force_resync::ResyncOutcome;

pub use force_resync::StaleRoot;

pub use force_resync::apply_force_resync;

pub use force_resync::is_safe_invalidation_target;

pub use force_resync::plan_force_resync;

pub use gc_roots::RCH_CARGO_CACHE_PREFIX;

pub use gc_roots::RCH_CARGO_HOME_BASE_VAR;

pub use gc_roots::RCH_CARGO_HOME_PREFIX;

pub use gc_roots::remote_cargo_cache_expr;

pub use gc_roots::remote_cargo_home_base_prelude;

pub use gc_roots::remote_cargo_home_expr;

pub use logging::LogConfig;

pub use logging::LogFormat;

pub use logging::LoggingGuards;

pub use logging::init_logging;

pub use logging::init_logging_with_layer;

pub use mock_worker::MockWorkerServer;

pub use path_topology::DEFAULT_ALIAS_PROJECT_ROOT;

pub use path_topology::DEFAULT_CANONICAL_PROJECT_ROOT;

pub use path_topology::NormalizationDecision;

pub use path_topology::NormalizedProjectPath;

pub use path_topology::PathNormalizationError;

pub use path_topology::PathNormalizationErrorKind;

pub use path_topology::PathTopologyPolicy;

pub use path_topology::normalize_project_path;

pub use path_topology::normalize_project_path_with_policy;

pub use patterns::Classification;

pub use patterns::ClassificationDetails;

pub use patterns::ClassificationTier;

pub use patterns::CompilationKind;

pub use patterns::TierDecision;

pub use patterns::classify_command;

pub use patterns::classify_command_detailed;

pub use patterns::compound_local_compilation_segments;

pub use patterns::declined_compilation_due_to_structure;

pub use patterns::split_shell_commands;

pub use protocol::HookInput;

pub use protocol::HookOutput;

pub use protocol::ToolInput;

pub use queue_contract::AdmissionState;

pub use queue_contract::QueueContractOutcome;

pub use queue_contract::QueueContractResponse;

pub use queue_contract::QueueOptions;

pub use queue_contract::StartState;

pub use queue_contract::WaitResult;

pub use queue_contract::resolve_queue_contract;

pub use repo_updater_contract::MockRepoUpdaterAdapter;

pub use repo_updater_contract::REPO_UPDATER_ALIAS_PROJECTS_ROOT;

pub use repo_updater_contract::REPO_UPDATER_CANONICAL_PROJECTS_ROOT;

pub use repo_updater_contract::REPO_UPDATER_CONTRACT_SCHEMA_VERSION;

pub use repo_updater_contract::REPO_UPDATER_DEFAULT_BINARY;

pub use repo_updater_contract::REPO_UPDATER_MIN_SUPPORTED_VERSION;

pub use repo_updater_contract::RepoUpdaterAdapter;

pub use repo_updater_contract::RepoUpdaterAdapterCommand;

pub use repo_updater_contract::RepoUpdaterAdapterContract;

pub use repo_updater_contract::RepoUpdaterAdapterRequest;

pub use repo_updater_contract::RepoUpdaterAdapterResponse;

pub use repo_updater_contract::RepoUpdaterFailure;

pub use repo_updater_contract::RepoUpdaterFailureKind;

pub use repo_updater_contract::RepoUpdaterFallbackMode;

pub use repo_updater_contract::RepoUpdaterIdempotencyGuarantee;

pub use repo_updater_contract::RepoUpdaterJsonEnvelope;

pub use repo_updater_contract::RepoUpdaterOutputFormat;

pub use repo_updater_contract::RepoUpdaterResponseStatus;

pub use repo_updater_contract::RepoUpdaterVersionCompatibility;

pub use repo_updater_contract::RepoUpdaterVersionPolicy;

pub use repo_updater_contract::build_invocation;

pub use repo_updater_contract::classify_exit_code;

pub use repo_updater_contract::evaluate_version_compatibility;

pub use repo_updater_contract::map_failure_kind_to_error_code;

pub use repo_updater_contract::repo_updater_envelope_schema;

pub use repo_updater_contract::repo_updater_request_schema;

pub use repo_updater_contract::repo_updater_response_schema;

pub use ssh_utils::CommandResult;

pub use ssh_utils::EnvPrefix;

pub use ssh_utils::build_env_prefix;

pub use ssh_utils::is_retryable_transport_error;

pub use ssh_utils::is_retryable_transport_error_text;

pub use ssh_utils::shell_escape_value;

pub use ssh::KnownHostsPolicy;

pub use ssh::SshClient;

pub use ssh::SshOptions;

pub use ssh::SshPool;

pub use test_change::TestChangeGuard;

pub use test_change::TestCodeChange;

pub use toolchain::ToolchainInfo;

pub use toolchain::wrap_command_with_color;

pub use toolchain::wrap_command_with_toolchain;

pub use transfer_hardening::FirstFailure;

pub use transfer_hardening::RetryDecision;

pub use transfer_hardening::RsyncFailureClass;

pub use transfer_hardening::classify_rsync_outcome;

pub use transfer_hardening::is_ephemeral_path;

pub use types::AffinityConfig;

pub use types::ApiConfig;

pub use types::BoxRole;

pub use types::BuildCancellationMetadata;

pub use types::BuildCancellationWorkerHealth;

pub use types::BuildHeartbeatPhase;

pub use types::BuildHeartbeatRequest;

pub use types::BuildLocation;

pub use types::BuildRecord;

pub use types::BuildStats;

pub use types::CircuitBreakerConfig;

pub use types::CircuitState;

pub use types::CircuitStats;

pub use types::ColorMode;

pub use types::CommandPriority;

pub use types::CommandTimingBreakdown;

pub use types::CompilationConfig;

pub use types::CompilationMetrics;

pub use types::CompilationTimer;

pub use types::CompilationTimingBreakdown;

pub use types::DashboardConfig;

pub use types::DoctorConfig;

pub use types::DoctorWebhookEndpoint;

pub use types::DoctorWebhookFormat;

pub use types::DoctorWebhooksConfig;

pub use types::EnvironmentConfig;

pub use types::ExecutionConfig;

pub use types::FairnessConfig;

pub use types::FleetConfig;

pub use types::GeneralConfig;

pub use types::MetricsAggregator;

pub use types::OS_TAG_PREFIX;

pub use types::OutputConfig;

pub use types::OutputVisibility;

pub use types::PathTopologyConfig;

pub use types::RchConfig;

pub use types::ReleaseRequest;

pub use types::RemoteBuildJobs;

pub use types::RequiredRuntime;

pub use types::RetryConfig;

pub use types::SELECTION_RESPONSE_PROTOCOL_VERSION;

pub use types::SavedTimeStats;

pub use types::SelectedWorker;

pub use types::SelectionConfig;

pub use types::SelectionDiagnostics;

pub use types::SelectionReason;

pub use types::SelectionRequest;

pub use types::SelectionResponse;

pub use types::SelectionStrategy;

pub use types::SelectionWeightConfig;

pub use types::SelfHealingConfig;

pub use types::SelfHealingLogLevel;

pub use types::SelfTestConfig;

pub use types::SelfTestFailureAction;

pub use types::SelfTestWorkers;

pub use types::TransferConfig;

pub use types::WorkerCapabilities;

pub use types::WorkerConfig;

pub use types::WorkerId;

pub use types::WorkerSelectionDiagnostic;

pub use types::WorkerSelectionDiagnosticDecision;

pub use types::WorkerStatus;

pub use types::declared_os;

pub use types::default_socket_path;

pub use types::os_tag;

pub use types::validate_remote_base;

pub use types::x86_64_microarch_level_from_flags;

pub use testing::TestLogEntry;

pub use testing::TestLogger;

pub use testing::TestPhase;

pub use testing::TestResult;

pub use config::ConfigSource;

pub use config::ConfigValueSource;

pub use config::ConfigWarning;

pub use config::EnvError;

pub use config::EnvParser;

pub use config::Profile;

pub use config::Severity;

pub use config::Sourced;

pub use config::validate_config;

pub use discovery::DiscoveredHost;

pub use discovery::DiscoverySource;

pub use discovery::discover_all;

pub use discovery::parse_shell_aliases;

pub use discovery::parse_shell_aliases_content;

pub use discovery::parse_ssh_config;

pub use discovery::parse_ssh_config_content;

pub use ui::ErrorPanel;

pub use ui::ErrorSeverity;

pub use ui::Icons;

pub use ui::IntoErrorPanel;

pub use ui::OutputContext;

pub use ui::RchTheme;

pub use ui::ResultExt;

pub use ui::anyhow_to_json;

pub use ui::anyhow_to_panel;

pub use ui::display_anyhow_error;

pub use ui::display_error;

pub use ui::display_error_with_code;

pub use ui::error_to_json;

pub use ui::error_to_panel;

pub use capability_probe::CapabilityRequirement;

pub use capability_probe::CapabilityVerdict;

pub use capability_probe::EligibilityVerdict;

pub use capability_probe::ProbeSpec;

pub use capability_probe::ProbedFacts;

pub use capability_probe::WorkerLiveness;

pub use capability_probe::assess_admissibility;

pub use capability_probe::assess_worker_eligibility;

pub use capability_probe::build_capability_probe_script;

pub use capability_probe::parse_capability_probe;

pub use capability_probe::remote_worker_binary_path;

pub use incident::ControlState;

pub use incident::IncidentEvent;

pub use incident::IncidentEventType;

pub use incident::IncidentReasonCode;

pub use incident::IncidentSource;

pub use incident::SelectedMode;

pub use incident::incident_schema_version;

pub use incident_ledger::IncidentFilter;

pub use incident_ledger::IncidentLedger;

pub use incident_ledger::IncidentLedgerConfig;

pub use incident_ledger::LedgerReadStats;

pub use incident_ledger::default_ledger_path;

pub use placement::ControlDiagnostic;

pub use placement::ControlDiagnosticLevel;

pub use placement::ControlKind;

pub use placement::PlacementControl;

pub use placement::PlacementPlan;

pub use placement::QueuePolicy;

pub use placement::RequestedWorkerFacts;

pub use placement::RequestedWorkerOutcome;

pub use placement::RequestedWorkerStatus;

pub use placement::StrictRemotePolicy;

pub use placement::TargetDirPolicy;

pub use placement::VisibilityMode;

pub use placement::evaluate_requested_worker;

pub use placement::placement_controls;

pub use placement::resolve_placement;

pub use proof_intent::ProofIntent;

pub use proof_intent::ProofIntentStore;

pub use proof_intent::ReplayConstraints;

pub use proof_intent::ReplayContext;

pub use proof_intent::ReplayDecision;

pub use proof_intent::SourceFingerprint;

pub use proof_intent::StaleSourcePolicy;

pub use proof_intent::derive_intent_id;

pub use proof_intent::proof_intent_schema;

pub use proof_intent::proof_intent_schema_version;

pub use proof_intent::validate_replay;

pub use telemetry_explain::ProbeOutcome;

pub use telemetry_explain::TelemetrySignals;

pub use telemetry_explain::TelemetryUnavailabilityReason;

pub use telemetry_explain::WhyUnhealthy;

pub use telemetry_explain::explain_unavailability;

pub use telemetry_freshness::FreshnessAssessment;

pub use telemetry_freshness::FreshnessInputs;

pub use telemetry_freshness::FreshnessVerdict;

pub use telemetry_freshness::assess as assess_telemetry_freshness;

pub use worker_config_validation::ConfigDriftFinding;

pub use worker_config_validation::ConfigDriftKind;

pub use worker_config_validation::LiveHostObservation;

pub use worker_config_validation::validate_worker_config;

pub use worker_facts::DiskFacts;

pub use worker_facts::DiskRootFacts;

pub use worker_facts::HostFacts;

pub use worker_facts::RuntimeFacts;

pub use worker_facts::RustFacts;

pub use worker_facts::UserFacts;

pub use worker_facts::WorkerBinaryFacts;

pub use worker_facts::WorkerFacts;

pub use worker_facts::derive_target_triple;

pub use worker_facts::worker_facts_schema;

pub use worker_facts::worker_facts_schema_version;

pub use errors::CodeExplanation;

pub use errors::CodeNamespace;

pub use errors::ErrorCategory;

pub use errors::ErrorCode;

pub use errors::ErrorEntry;

pub use errors::ReliabilityCategoryKind;

pub use errors::ReliabilityReasonCode;

pub use errors::RunbookEntry;

pub use schema_versions::current_version as schema_version;

pub use schema_versions::ALL_COMPONENTS as SCHEMA_VERSION_COMPONENTS;

pub use schema_versions::SchemaComponent;

pub use api::API_VERSION;

pub use api::ApiError;

pub use api::ApiResponse;

pub use api::ErrorContext;

pub use api::LegacyErrorCode;

pub use hooks::HookResult;

pub use hooks::is_claude_code_installed;

pub use hooks::verify_and_install_claude_code_hook;

Modules

admission_recommendation

Admission next-action recommendations (bd-session-history-remediation-ocv9i.6.4).

admission_rejection

Admission rejection aggregation with a stable reason vocabulary (bd-session-history-remediation-ocv9i.6.2).

admit_preflight

rch admit preflight core (bd-session-history-remediation-ocv9i.6.1).

api

Unified API Types for Remote Compilation Helper

artifact_cost

File-count-aware artifact retrieval cost model and manifest advice (bd-session-history-remediation-ocv9i.9.2).

artifact_pattern

Target-dir-aware artifact pattern rewriting (bd-session-history-remediation-ocv9i.9.1).

artifact_verify

Artifact integrity verification using blake3 hashes (bd-377q).

binary_hash

Binary hash computation utility for verifying remote compilation correctness.

bypass_record

Temporary-bypass record schema and persistent store (bd-session-history-remediation-ocv9i.1.2).

bypass_recovery

Recovery-probe + canary decision state machine for temporarily bypassed workers (bd-session-history-remediation-ocv9i.1.3).

capability_probe

Exact user/path capability probes for runtimes, toolchains, and targets (bd-session-history-remediation-ocv9i.12.2).

cargo_path_deps

Cargo local path-dependency graph resolver.

classifier_drift

Classifier drift detection and bounded refresh (bd-session-history-remediation-ocv9i.6.3).

closure_explain

Path-dependency closure sync explanation (bd-session-history-remediation-ocv9i.8.1).

config

Configuration system for RCH.

dependency_closure_planner

Dependency-closure planning on top of Cargo local path-dependency resolution.

discovery

Worker discovery from SSH config and shell aliases.

disk_pressure_report

Per-worker disk / inode / target-root / cargo-home / log pressure report for rch doctor and status (bd-session-history-remediation-ocv9i.11.4).

disk_reclaim

Safe disk-reclaim receipts with active-build protection (bd-session-history-remediation-ocv9i.11.3).

e2e

E2E Test Infrastructure

errors

Error catalog and definitions for Remote Compilation Helper

exec_misuse

Detect quoted single-command misuse in rch exec (bd-session-history-remediation-ocv9i.13.1).

exec_policy

Explicit-exec policy for non-compilation commands (bd-session-history-remediation-ocv9i.13.2).

exec_response

rch exec execution-location contract (bd-session-history-remediation-ocv9i.13.3).

fleet_diff

Desired-state inventory and live-eligibility diff (bd-session-history-remediation-ocv9i.2.1).

fleet_provenance

Release provenance, signature/checksum verification, and deploy audit for fleet binary updates (bd-session-history-remediation-ocv9i.7.4).

fleet_smoke_profile

Real-fleet smoke and soak validation profile planning (bd-session-history-remediation-ocv9i.16.6).

fleet_status

Fleet status report: desired/live grouping + dominant-problem summary + absence alerts (bd-session-history-remediation-ocv9i.2.2).

force_resync

Agent-safe force-resync for stale path-dependency roots (bd-session-history-remediation-ocv9i.8.3).

gc_roots

The single source of truth for the directory roots rch gc scans.

hooks

Daemon hook verification and installation.

incident

Shared incident event schema and stable reason-code registry.

incident_ledger

Append-only, bounded, corruption-tolerant incident ledger.

job_identity

Durable local/remote job identity and lifecycle correlation (bd-session-history-remediation-ocv9i.10.1).

job_recovery

Stuck-wrapper recovery: reattach / cancel / recover decisions (bd-session-history-remediation-ocv9i.10.3).

log_retention

Daemon log rotation + doctor log-pressure reporting (bd-session-history-remediation-ocv9i.14.3).

logging

Structured logging initialization for RCH components.

mock

Mock transport layer for testing.

mock_worker

Mock worker server helper for tests.

orphan_quarantine

Evidence-cleared E104 orphan quarantines (issue #62, bd-g8m4g).

path_topology

Canonical path topology utilities for host/worker project mapping.

patterns

Command classification patterns for identifying compilation commands.

placement

Canonical placement / visibility / strict-remote controls (bd-session-history-remediation-ocv9i.13.5).

pooled_target_key

Pooled target-dir cache key (bd-session-history-remediation-ocv9i.11.2).

process_identity

Kernel process birth identity shared by durable clients and the daemon.

proof_handoff

Agent-facing proof handoff output (bd-session-history-remediation-ocv9i.5.4).

proof_intent

Durable proof-intent schema and store (bd-session-history-remediation-ocv9i.5.2).

proof_policy

Proof-mode fail-closed execution policy (bd-session-history-remediation-ocv9i.5.1).

proof_replay

Deferred proof replay conveyor and state machine (bd-session-history-remediation-ocv9i.5.3).

protocol

Claude Code hook protocol definitions.

queue_contract

Queue wait/stream/no-start CLI contract (bd-session-history-remediation-ocv9i.10.2).

readiness

Readiness split + diagnose incident-chain replay (bd-session-history-remediation-ocv9i.4.3).

redaction

Shared secret-redaction and privacy policy for all remediation data (bd-session-history-remediation-ocv9i.16.8).

remediation_config

Central config schema and default policy for the session-history remediation features (bd-session-history-remediation-ocv9i.17.1).

remediation_view

Operator-facing remediation view: a compact, redacted, deterministic snapshot of the remediation state the dashboards (TUI + web) render (bd-session-history-remediation-ocv9i.14.4).

remote_compilation

Remote Compilation Verification via SSH.

remote_verification

Remote compilation verification via SSH.

repo_updater_contract

Stable contract for integrating RCH with repo_updater (ru).

rsync_flavor

rsync flavour detection, binary resolution, and argv compatibility (issue #66).

schema_versions

Central registry of schema versions across the workspace.

ssh

SSH client utilities for remote command execution.

ssh_utils

Platform-independent SSH utilities.

stale_target_reap

Shared predicate + shell-snippet builder for reaping stale per-job remote CARGO_TARGET_DIR directories.

storm_control

Multi-agent load fairness and storm-control modeling (bd-session-history-remediation-ocv9i.10.4).

telemetry_explain

Telemetry age explanations and “why unhealthy” status model.

telemetry_freshness

Adaptive telemetry freshness model.

test_change

Test code change generator for verifying remote compilation.

testing

Test utilities for RCH.

toolchain

Rust toolchain information types.

transfer_hardening

Transfer hardening against volatile files and retryable transport failures (bd-session-history-remediation-ocv9i.8.2).

types

Common types used across RCH components.

ui

UI utilities for RCH terminal output.

util

Shared utilities for RCH.

worker_config_validation

workers.toml vs SSH-config / live-fact validation (bd-session-history-remediation-ocv9i.12.4).

worker_facts

Worker capability fact schema — exact host/user/path inventory.

Macros

e2e_test

Macro for creating E2E tests with automatic harness setup and cleanup

test_guard

Create a TestGuard using the current function name.

Constants

BUILD_COMMIT_ENV_VARS

REMOTE_PROCESS_IDENTITY_SCRIPT

Shared Linux launch and cancellation protocol; callers select their receipt.

Functions

build_commit

The validated build revision stamped into this binary, if any.

build_version_value

build_version_value_static

build_version_value_with_commit