Struct AdmittedTool 

pub struct AdmittedTool { /* private fields */ }

An executable with retained byte and version identities.

Self::admit requires a consumer-supplied digest. Self::admit_version records the installed identity without authenticating it against a pin. Self::observe_version records both identities without an expected version. Every execution rechecks digest/permission before spawning. Consumers must exclude concurrent writers to the executable and its parent directories: filesystem checks and exec are separate operations. This is not a file capability or verification of dynamic libraries, interpreters, or descendants.

Implementations

impl AdmittedTool

pub fn admit( spec: &VersionSpec<'_>, expected: Sha256Digest, expected_version: &str, context: &ExecutionContext<'_>, limits: OutputLimits, ) -> Result<Self, ToolError>

Admit exact executable bytes and require the selected version identity.

expected_version is exact UTF-8 stdout after Unicode whitespace trimming.

Errors

Rejects invalid inputs, non-executable files, digest/size mismatch, process failures, non-UTF-8 stdout, and a different successful version identity.

pub fn admit_no_follow( spec: &VersionSpec<'_>, expected: Sha256Digest, expected_version: &str, context: &ExecutionContext<'_>, limits: OutputLimits, ) -> Result<Self, ToolError>

Admit exact bytes without following the executable’s final-component symlink.

Performs one bounded no-follow hash before the version command. Parents and concurrent writers remain caller-owned. The retained canonical path also rejects final-component links during subsequent Self::run calls.

Errors

Returns the same admission failures as Self::admit, additionally refusing final-component symbolic links and special files before execution.

pub fn admit_version( spec: &VersionSpec<'_>, expected_version: &str, context: &ExecutionContext<'_>, limits: OutputLimits, ) -> Result<Self, ToolError>

Admit an exact version and record the caller-trusted installed bytes.

expected_version is exact UTF-8 stdout after Unicode whitespace trimming.

For tools built locally, no portable published digest may exist. This entry hashes the executable within the supplied budget before running the version command. The resulting Self::identity is an observation, not a trusted published pin. All later runs reject changed bytes using the same verification and capture engine as Self::admit.

The caller must trust the installation before admission: the version command executes those bytes. Exact version output does not establish authenticity. No version ranges, tool installation or PATH search occur. The caller must exclude concurrent executable/directory writers.

Errors

Rejects invalid inputs, non-executable or oversized files, process failures, non-UTF-8 stdout and a different successful version identity.

pub fn observe_version( spec: &VersionSpec<'_>, context: &ExecutionContext<'_>, limits: OutputLimits, ) -> Result<Self, ToolError>

Record installed bytes and their version with one version invocation.

This is suitable for provenance of a caller-trusted installation when no expected version is selected. Hashing precedes version dispatch; later runs recheck that byte identity. The complete UTF-8 version stdout must be nonempty after trimming. It does not authenticate the installation. Consumers must exclude concurrent executable/directory writers and own trust, output budgets, deadlines and environment, as for Self::admit_version.

Errors

Rejects invalid inputs, non-executable or oversized files, process failures, truncated output, non-UTF-8 stdout and an empty version. An empty observation returns ToolError::VersionMismatch with the original capture, just as an unmatched expected version does.

pub fn path(&self) -> &Path

Canonical absolute path selected during admission.

pub const fn identity(&self) -> ArtifactIdentity

Retained raw executable identity.

With Self::admit_version or Self::observe_version, this is an observed identity, not proof of a published binary pin or trusted installation provenance.

pub fn version_identity(&self) -> &str

Successfully observed, trimmed version identity.

pub fn run( &self, arguments: &[OsString], context: &ExecutionContext<'_>, limits: OutputLimits, ) -> Result<CompletedExecution, ToolError>

Run once with a cleared, explicitly supplied environment and null stdin.

Stdout/stderr are drained fairly through nonblocking pipes without reader threads. On overflow/deadline the direct child is killed and reaped; pipe handles are closed without waiting for descendants to close their copies. Descendant processes remain caller-owned. This must not be interpreted as a rollback or safe automatic retry of a command with external effects. Nonzero/signalled exits are completed results. Call CompletedExecution::require_success before success-only interpretation.

Errors

Returns invalid-input or identity failures before execution, or an execution failure retaining bounded prefixes and cleanup outcomes.