Crate soma_infra 

Product-neutral infrastructure read and verified mutation engines.

soma-infra defines typed host, Docker, Compose, filesystem, process, log, and ZFS contracts above soma-fleet, plus bounded mutation coordinators that preserve send state and verify postconditions. Product configuration, authorization, and CLI/MCP/REST presentation remain outside.

Structs

BollardClientProvider

Revision-aware Bollard provider for local and strict-SSH hosts.

BollardReadClient

Local Bollard implementation of the neutral Docker read contracts.

BuildContextFingerprint

Deterministic content fingerprint for one admitted build context.

BuildContextPolicy

Explicit roots and traversal ceilings for Docker build contexts.

CommandBuildContextInspector

Descriptor-confined build-context inspector backed by fleet command execution.

CommandComposeBuildMutator

Process-backed Compose build driver.

CommandComposeInspector

Compose inspector backed by a soma-fleet command executor.

CommandFileTransfer

Descriptor-confined local or strict-SSH file transfer driver.

CommandFilesystemQueryInspector

Descriptor-walking filesystem query driver backed by fleet command execution.

CommandHostExec

Process-backed host command driver with explicit per-host read roots.

CommandHostSystemInspector

Host-system inspector backed by a fleet command executor.

CommandImageBuildMutator

Process-backed Docker build driver.

CommandLogReader

Operating-system log reader backed by a fleet command executor.

CommandProcessInspector

Process inspector backed by a fleet command executor.

CommandZfsInspector

ZFS inspector backed by a fleet command executor.

ComposeBuildArtifact

One planned Compose service build artifact.

ComposeBuildEngine

Coordinates context drift checks, Compose build, and image verification.

ComposeBuildOutcome

Verified Compose build outcome.

ComposeBuildReceipt

Compose build process receipt.

ComposeBuildRequest

Deadline-bound Compose build request.

ComposeBuildServices

Borrowed services required for one Compose build execution.

ComposeBuiltImage

One verified Compose service build result.

ComposeConfig

Typed read-only Compose configuration summary.

ComposeDownEngine

Verified Docker Compose teardown coordinator.

ComposeDownOutcome

Verified Compose teardown outcome.

ComposeDownReceipt

Process driver receipt for Compose down.

ComposeDownRequest

Deadline-bound Compose teardown request.

ComposeLogRequest

Bounded Compose log request.

ComposeLogs

Bounded Compose log result.

ComposeMutationEngine

Coordinates a Compose mutation and independent service-state verification.

ComposeMutationOutcome

Verified Compose mutation outcome.

ComposeMutationReceipt

Receipt returned after a Compose mutation command was sent.

ComposeMutationRequest

Deadline-bound Compose mutation request.

ComposeProject

Project row returned by docker compose ls.

ComposeProjectRef

Validated reference to one Compose project configuration.

ComposePullEngine

Coordinates Compose image pulls and verifies every configured local image identity.

ComposePullOutcome

Verified Compose pull outcome.

ComposePullReceipt

Receipt returned when the Compose pull command completes.

ComposePullRequest

Deadline-bound Compose image pull request.

ComposePulledImage

One Compose service image verification row.

ComposeRecreateEngine

Coordinates Compose drift checks, force-recreate, and post-state verification.

ComposeRecreateFingerprint

Stable fingerprint of the Compose configuration and service pre-state.

ComposeRecreateOutcome

Verified Compose replacement outcome.

ComposeRecreateReceipt

Process driver receipt for Compose force-recreate.

ComposeRecreateRequest

Deadline-bound Compose replacement request.

ComposeServiceConfig

Selected read-only service configuration.

ComposeServiceStatus

Service row returned by docker compose ps.

ComposeStatus

Typed status for one Compose project.

ContainerExecReceipt

Completed non-interactive Docker exec.

ContainerExecRequest

One non-interactive bounded Docker exec request.

ContainerInspect

Selected neutral container inspection fields.

ContainerLifecycleEngine

Coordinates mutation and independent container-state verification.

ContainerLifecycleOutcome

Verified lifecycle mutation outcome.

ContainerLifecycleRequest

Deadline-bound container lifecycle request.

ContainerListOptions

Closed container-list options.

ContainerLogOptions

Bounded one-shot Docker log options.

ContainerLogs

Bounded one-shot Docker log result.

ContainerMutationReceipt

Receipt returned once a lifecycle mutation was accepted by the driver.

ContainerProcessTable

Process table returned by Docker top.

ContainerRecreateEngine

Coordinates configuration drift checks, replacement, and post-state verification.

ContainerRecreateFingerprint

Stable digest and selected identity captured before a container replacement.

ContainerRecreateOutcome

Verified container replacement outcome.

ContainerRecreateReceipt

Driver receipt for one replacement attempt.

ContainerRecreateRequest

Deadline-bound request to replace one container from its captured configuration.

ContainerStatsSnapshot

Neutral one-shot Docker container statistics.

ContainerSummary

Neutral Docker container summary.

DockerCleanupEngine

Verified Docker image-removal and prune coordinator.

DockerDiskUsage

Neutral Docker disk-usage snapshot.

DockerPruneFingerprint

Deterministic pre-prune inventory.

DockerPruneOutcome

Verified prune result.

DockerPruneReceipt

Complete prune receipt.

DockerPruneRequest

Request to prune one exact inventory.

DockerPruneScopeReceipt

Backend receipt for one prune scope.

DockerSystemInfo

Neutral Docker daemon information.

DockerUsageCategory

Aggregate disk usage for one Docker resource category.

DoctorCheck

One doctor check.

DoctorReport

Typed doctor report.

FileFindRequest

Bounded recursive file search request.

FileHash

SHA-256 file digest.

FileMetadata

Typed filesystem metadata.

FilePreview

Bounded file preview.

FileReadPolicy

Closed read policy for one filesystem inspector.

FileSearch

Bounded file-search result.

FileTail

Bounded file tail.

FileTailRequest

Request for a bounded file tail.

FileTransferEngine

Verified bounded file-transfer coordinator.

FileTransferFingerprint

Complete authorization-relevant transfer fingerprint.

FileTransferPolicy

Explicit source and destination roots for one host.

FilesystemUsage

Byte-precise filesystem usage.

HostExecManyEngine

Bounded stable-order host execution fanout coordinator.

HostExecManyOutcome

Complete stable-order host execution fanout outcome.

HostExecPolicy

Explicit read roots used by the typed host command launcher.

HostExecReceipt

Completed bounded host execution.

HostExecRequest

One bounded allowlisted host execution request.

HostExecTargetResult

Stable-order outcome for one fanout target.

HostIdentity

Stable host identity fields collected from the operating system.

HostInspectRequest

Deadline-bound request for one host inspection.

HostInspection

Complete read-only host inspection result.

HostLoadAverage

Parsed Linux load averages.

HostMemory

Parsed host memory counters.

ImageBuildEngine

Coordinates context verification, image build, and image-store verification.

ImageBuildOutcome

Verified image build outcome.

ImageBuildReceipt

Receipt returned after a build command reaches a terminal process state.

ImageBuildRequest

Deadline-bound request for one Docker image build.

ImageBuildServices

Borrowed services required for one image build execution.

ImageIdentity

Stable image identity observed through the Docker read API.

ImageListOptions

Closed image-list options.

ImagePullEngine

Coordinates one image pull and independent image-store verification.

ImagePullOutcome

Verified image pull outcome.

ImagePullProgressFrame

One retained neutral image-pull progress frame.

ImagePullReceipt

Receipt returned after the image pull stream completes.

ImagePullRequest

Deadline-bound request to pull one Docker/OCI image reference.

ImageRemovalFingerprint

Stable identity bound into an image-removal plan.

ImageRemovalOutcome

Verified image-removal result.

ImageRemovalReceipt

Backend receipt for image removal.

ImageRemovalRequest

Request to remove one exact local image identity.

ImageSummary

Neutral Docker image summary.

JournalFilters

Validated journal filters.

LinuxCommandHostInspector

Host inspector backed by a soma-fleet command executor.

LinuxFilesystemInspector

Linux descriptor-confined filesystem reader.

LogPermissionDiagnostic

Structured permission diagnostic for a log source.

LogRead

Bounded log read result.

LogReadRequest

Bounded read request for one log source.

MountInfo

One mounted filesystem.

MutationFailure

Infrastructure mutation failure with explicit backend send state.

MutationVerification

Stable verification detail for a mutation outcome.

MutationVerificationPolicy

Bounded post-mutation verification policy.

NetworkAddress

One interface address.

NetworkInterface

One network interface.

NetworkSummary

Neutral Docker network summary.

PathRead

Bounded file or directory read.

PathReadRequest

Request for a bounded file or directory read.

PortInfo

One listening socket.

PortListRequest

Request for bounded listening-port inspection.

ProcessListRequest

Closed request for one process snapshot.

ProcessRow

Typed row from a process snapshot.

ProcessSnapshot

Bounded process snapshot for one host revision.

ServiceListRequest

Request for a bounded service listing.

ServiceStatus

One system service row.

TransferFileIdentity

Stable file content identity.

VerifiedFileTransferOutcome

Verified file-transfer result.

VerifiedFileTransferRequest

Deadline-bound transfer request.

VolumeSummary

Neutral Docker volume summary.

ZfsDatasetRequest

Request for a ZFS dataset listing.

ZfsPoolRequest

Request for a ZFS pool listing.

ZfsSnapshotRequest

Request for a bounded ZFS snapshot listing.

ZfsTable

Structured ZFS tabular output.

Enums

ComposeMutationAction

Supported Compose mutations in the first reversible slice.

ContainerLifecycleAction

Supported reversible container lifecycle mutations.

ContainerRecreateStage

Furthest destructive stage reached by a container recreation.

ContainerState

Neutral container runtime state.

DockerLogStream

Selected Docker log stream.

DockerPruneTarget

Closed Docker prune scope.

FileKind

Read-only filesystem object kind.

FileTransferPathRole

Policy role used while inspecting a transfer path.

HostExecCommand

Closed allowlist of host commands admitted by canonical Synapse execution.

HostExecTargetStatus

Terminal classification for one host-exec fanout target.

InfraError

Product-neutral infrastructure operation failure.

JournalPriority

Journal priority accepted by journalctl.

LogSource

Supported read-only operating-system log sources.

PortProtocol

Supported listening-port protocols.

ProcessSort

Supported deterministic process sort orders.

ZfsDatasetType

Allowlisted ZFS dataset types.

Constants

MAX_FILE_TRANSFER_BYTES

Maximum bytes copied by one canonical file-transfer mutation.

Traits

BuildContextInspector

Reads one build context through descriptor-confined traversal.

ComposeBuildMutator

Driver for one Compose build command.

ComposeDownClient

Complete Compose client required by teardown verification.

ComposeDownMutator

Executes Docker Compose teardown.

ComposeInspector

Product-neutral Compose inspection engine.

ComposeMutationClient

Complete client required by the Compose mutation coordinator.

ComposeMutator

Driver for Compose mutation commands.

ComposePullClient

Complete Compose client required by the pull coordinator.

ComposePullMutator

Driver for one Compose image pull command.

ComposeRecreateClient

Complete Compose client required by the replacement engine.

ComposeRecreateMutator

Executes Docker Compose force-recreate.

ContainerExecClientProvider

Supplies one host-bound Docker exec client.

ContainerExecMutator

Product-neutral non-interactive Docker exec driver.

ContainerLifecycleMutator

Driver for one reversible container lifecycle mutation.

ContainerReader

Docker container read operations.

ContainerRecreateClient

Complete client required by the verified recreate engine.

ContainerRecreateClientProvider

Supplies one host-bound container replacement client.

ContainerRecreateInspector

Reads a driver-native replacement fingerprint without leaking SDK models.

ContainerRecreateMutator

Performs one container replacement while preserving partial-stage evidence.

DockerArtifactClient

Complete Docker client required by artifact mutations.

DockerArtifactClientProvider

Factory for host- and revision-bound artifact mutation clients.

DockerCleanupClient

Complete Docker cleanup client used by verification engines.

DockerCleanupClientProvider

Host-bound cleanup client provider.

DockerCleanupMutator

Product-neutral Docker cleanup mutations.

DockerClientProvider

Factory for host- and revision-bound Docker read clients.

DockerMutationClient

Complete Docker client required by the lifecycle coordinator.

DockerMutationClientProvider

Factory for host- and revision-bound Docker mutation clients.

DockerReadClient

Complete neutral Docker read surface.

DockerSystemReader

Docker system-level read operations.

DockerTelemetryReader

Docker telemetry read operations.

FileTransferInspector

Reads file identities for transfer planning and verification.

FilesystemInspector

Product-neutral filesystem inspection engine.

FilesystemQueryInspector

Descriptor-confined filesystem queries usable locally or over SSH.

HostExecMutator

Product-neutral bounded host command driver.

HostInspector

Product-neutral host inspection engine.

HostSystemInspector

Remaining product-neutral host-system reads.

ImageBuildMutator

Driver for one Docker image build command.

ImagePullMutator

Driver for one image-pull stream.

ImageReader

Docker image read operations.

LogReader

Product-neutral operating-system log reader.

MutationProgressReporter

Object-safe adapter for canonical operation progress delivery.

NetworkReader

Docker network read operations.

ProcessInspector

Product-neutral process inspection engine.

VerifiedFileTransferClient

Complete transfer client used by the verified engine.

VolumeReader

Docker volume read operations.

ZfsInspector

Product-neutral ZFS read engine.

Functions

canonical_image_reference

Returns the canonical tag used by Docker when no tag or digest is supplied.

compose_recreate_fingerprint

Produces deterministic replacement material from canonical Compose reads.

resolve_compose_build_context

Resolves an absolute or Compose-file-relative build context without permitting root escape.

Type Aliases

InfraResult

Result type for neutral infrastructure operations.

MutationResult

Result type for infrastructure mutations.