string Code { get; }
Source
Gets the stable failure classification.
Trusted, caller-supplied inputs for native coverage fan-in verification.
Verified fan-in counters and the identities of the four accepted inputs.
Verifies the existing coverage fan-in receipt, its inputs, and gate outputs.
Native capture and coverage fan-in composition operations.
ValueTask<EvidenceCoverageFanInResult> VerifyAsync(EvidenceCoverageFanInRequest request, CancellationToken cancellationToken = default)
Validates all fan-in evidence and returns counters only after every comparison succeeds.
ValueTask CaptureAsync(EvidenceCoverageCaptureRequest request, CancellationToken cancellationToken = default)
Validates and snapshots a producer report into a fresh manifest-backed capture directory.
Native captures require the exact NativeFilter
selection and the original collector XML. Solution captures require a complete successful timing inventory.
ValueTask ComposeAsync(EvidenceCoverageFanInRequest request, CancellationToken cancellationToken = default)
Validates four capture bundles and writes the composed report, primary-path report, and verification receipt.
Gate files are deliberately not required here because CI generates them from these outputs before calling VerifyAsync
. Fresh output is required; the final verifier must run after both gate reports exist.
Retains a Linux directory object so child writes cannot change its identity or permit inode reuse.
Linux CreationTimeUtc may fall back to mutable directory timestamps. Device/inode identity is independent of those timestamps. Opens reject links and nondirectories; the held descriptor keeps the original object alive across path replacement. This boundary supports the verified Linux x64 and ARM64 native stat layouts only.
EvidenceWorkspaceLinuxIdentity Open(string path)
Opens an existing directory without following its final path component.
bool Matches(string path)
Checks that a no-follow reopen still names the retained directory object.
void Dispose()
Releases the retained directory descriptor after owned cleanup or failed admission.
Shares one application cleanup across the readiness registrations created by its owner.
disposeApplication
A registration releases only its own interest. The last registration closes admission and runs cleanup; explicit owner disposal also closes admission. Callbacks run outside the admission lock. Direct owner disposal is reserved for callers that have already stopped all readiness work.
IAsyncDisposable Acquire()
Acquires one independently disposable readiness registration before cleanup begins.
A registration whose final release joins the shared application cleanup.
ObjectDisposedException
void ThrowIfDisposed()
Rejects creating readiness work after application cleanup has begun.
ObjectDisposedException
ValueTask DisposeAsync()
Closes registration admission and joins the one application cleanup result.
The shared cleanup completion, including its original failure.
Cleanup callback reentry returns immediately to avoid awaiting its own completion.
Identifies a bounded command execution failure without exposing command inputs or environment values.
string Code { get; }
Source
Gets the stable failure classification.
Describes one explicit, bounded command invocation.
FileName
Arguments
WorkingDirectory
Timeout
IReadOnlyDictionary<string, string> Environment { get; init; }
Source
Gets explicit environment entries added to the child process.
long MaximumOutputBytes { get; init; }
Source
Gets the combined UTF-8 byte budget for stdout and stderr.
Func<CancellationToken, ValueTask>? CheckBudget { get; init; }
Source
Gets an optional consumer budget check polled at most 250 milliseconds apart.
Contains bounded output and timing from a completed command.
ExitCode
StandardOutput
StandardError
ElapsedMilliseconds
bool OutputTruncated { get; init; }
Source
Gets whether the command exceeded its combined output capture budget.
Runs explicit argv commands with bounded output and owned process-tree cleanup.
Task<EvidenceCommandResult> RunAsync(EvidenceCommandRequest request, CancellationToken cancellationToken = default)
Runs the requested command without invoking a shell.
request
cancellationToken
A bounded command result.
EvidenceCommandException
Configures the HTTP condition and optional owned transport used by an Aspire readiness adapter.
Values are snapshotted when EvidenceAspireApplication.CreateHttpReadiness
is called. A custom client factory is called once for each admitted readiness wait and must return a fresh HttpClient
; the adapter disposes that client after the wait finishes.
EvidenceAspireHttpReadinessSettings Snapshot()
Validates and snapshots options without invoking the client factory.
HttpReadinessOptions Http { get; init; }
Source
Gets the status-only HTTP policy; defaults to exact HTTP 200, a three-second request timer, and a 250 ms retry delay.
Func<Uri, HttpClient>? CreateProbeClient { get; init; }
Source
Gets an optional factory for a fresh client configured for the resolved endpoint. The returned client becomes owned by the adapter and is disposed after its wait.
Immutable internal settings shared by all waits admitted through one adapter.
Owns a forward-only read stream and enforces a cumulative byte limit and caller cancellation.
Used for untrusted fan-in JSON and XML. The limit is checked after every read, including after file growth.
One resource's native-health and HTTP readiness operation with joined asynchronous disposal.
Task WaitUntilReadyAsync(CancellationToken cancellationToken)
Admits one independent wait unless cleanup has atomically closed admission.
cancellationToken
A task completing after readiness and per-wait client cleanup settle.
ObjectDisposedException
ValueTask DisposeAsync()
Closes admission, cancels and drains admitted waits, then disposes the existing application lease once.
The shared cleanup task observed by every external disposal caller.
Reentry from a cleanup callback does not wait on its own cleanup flow.
Uri ResolveEndpointUri(string? endpointValue)
Validates the allocated host-local value without retaining it in failure diagnostics.
endpointValue
An absolute HTTP(S) URI with a nonempty host.
ReadinessException
Exception? FindFatalCleanupFailure(Exception exception)
Preserves a fatal cleanup or diagnostic-storage leaf using the adapter's existing type policy.
exception
The first original fatal failure, or null when all failures are nonfatal.
Owns one consumer-composed Aspire application used only by an EvidenceHost run.
Build the supplied IDistributedApplicationBuilder
in test or CI composition code, then register readiness adapters from this lease with EvidenceHostBootstrap
. This type does not inspect the entry assembly and must not be added to normal application startup.
Task<EvidenceAspireApplication> StartAsync(IDistributedApplicationBuilder builder, CancellationToken cancellationToken = default)
Builds and starts an explicitly supplied consumer Aspire application.
builder
cancellationToken
An evidence-owned application lease that stops and disposes the application.
IEvidenceResourceReadiness CreateHealthReadiness(string evidenceResourceId, string aspireResourceName)
Creates a readiness adapter that waits for the named Aspire resource's healthy state.
evidenceResourceId
aspireResourceName
An explicitly registered health readiness adapter.
Dispose every returned adapter. It retains one application registration; only the final adapter release stops this application.
IEvidenceResourceReadiness CreateHttpReadiness(string evidenceResourceId, string resourceName, string endpointName, string probePath, TimeSpan timeout, EvidenceAspireHttpReadinessOptions? options = null)
Creates an EvidenceHost readiness adapter that waits for native Aspire health and then probes one named HTTP endpoint.
evidenceResourceId
resourceName
endpointName
probePath
timeout
options
A disposable readiness adapter that owns one fresh probe client per active wait and joins active waits before releasing its application registration.
The adapter resolves the exact resource and endpoint from the running application's DistributedApplicationModel
using Aspire.Hosting APIs. It does not require Aspire.Hosting.Testing. A custom client factory must return a fresh client for each wait; the adapter disposes each returned client after its probe completes. Each adapter retains this application until disposed. Only the last adapter release stops the application, so disposing one adapter cannot interrupt another adapter's admitted waits.
IEvidenceResourceReadiness CreateHttpReadinessCore(string evidenceResourceId, string probePath, TimeSpan timeout, HttpReadinessSettings settings, Func<CancellationToken, Task> waitForHealth, Func<CancellationToken, Task<string?>> resolveEndpoint, Func<Uri, HttpClient> createClient, Func<ValueTask> disposeLease, TimeProvider timeProvider)
Creates the adapter with controlled health, endpoint, transport, clock, and lease phases.
evidenceResourceId
probePath
timeout
settings
waitForHealth
resolveEndpoint
createClient
disposeLease
timeProvider
A disposable readiness adapter with atomic wait admission and joined owner cleanup.
EndpointReference ResolveEndpointReference(DistributedApplicationModel model, string resourceName, string endpointName)
Resolves a unique named endpoint shape without allocating its value.
model
resourceName
endpointName
The exact HTTP(S) Aspire endpoint reference; value allocation remains deferred until after health.
ReadinessException
Task<string?> ResolveEndpointValueAsync(EndpointReference endpoint, CancellationToken cancellationToken)
Allocates the already validated exact endpoint after native resource health succeeds.
endpoint
cancellationToken
The allocated absolute endpoint value, or null
when Aspire returns none.
ReadinessException
ValueTask DisposeAsync()
Stops and disposes the owned Aspire application. Repeated calls join the same cleanup result.
A task that completes after bounded application cleanup.
Stop all readiness work before directly disposing this owner. Adapter disposal releases only its own registration.
Configures an explicit EvidenceHost lifecycle.
RequireTrustedEnvelope
ArtifactDirectory
TestResults/evidence/artifacts
.TimeSpan ProducerCleanupTimeout { get; init; }
Source
Gets the separate grace period for cancelled producers to finish before owned registrations are disposed.
Defaults to ten seconds. If a producer remains active, cleanup fails and its registrations are preserved.
Describes a secret-safe execution-envelope validation result.
Accepted
Attested
false
.Diagnostic
Validates a CI-provided trusted execution envelope without exposing its secret values to a manifest.
ValueTask<EvidenceEnvelopeResult> VerifyAsync(EvidencePlan plan, CancellationToken cancellationToken)
Validates the caller's protected CI context for the resolved plan.
plan
cancellationToken
A constrained acceptance result.
Represents an explicitly registered readiness probe for a plan resource.
Task WaitUntilReadyAsync(CancellationToken cancellationToken)
Waits until the consumer-owned resource is ready or the supplied deadline cancels.
cancellationToken
A task that completes only when the resource is ready.
string Id { get; }
Source
Gets the stable plan resource identifier handled by this probe.
Collects the only resource, producer, and envelope registrations an EvidenceHost may use.
void AddResource(IEvidenceResourceReadiness resource)
Adds one explicitly named readiness probe.
resource
void AddProducer(IEvidenceProducer producer)
void SetEnvelopeVerifier(IEvidenceExecutionEnvelopeVerifier verifier)
Sets the single trusted execution-envelope verifier used by this host.
verifier
IReadOnlyDictionary<string, IEvidenceResourceReadiness> Resources { get; }
Source
Gets explicitly registered resource readiness probes.
IReadOnlyDictionary<string, IEvidenceProducer> Producers { get; }
Source
Gets explicitly registered typed producers.
IEvidenceExecutionEnvelopeVerifier? EnvelopeVerifier { get; set; }
Source
Gets the optional trusted execution-envelope verifier.
Runs a separate, consumer-owned EvidenceHost with explicit registrations and bounded cleanup.
EvidenceHostBootstrap Create(EvidencePlan plan, Action<EvidenceHostRegistration> configure, EvidenceHostOptions? options = null, TimeProvider? timeProvider = null)
Creates a host with registrations supplied only by explicit caller code.
plan
configure
options
timeProvider
A single-use EvidenceHost instance.
Task<EvidenceManifest> RunAsync(bool observationOnly = false, CancellationToken cancellationToken = default)
Validates envelope and registrations, waits for resources, runs selected producers, and collects a manifest.
observationOnly
cancellationToken
A terminal immutable manifest.
ValueTask DisposeAsync()
Disposes registered resources and producers if the host has not already cleaned them up.
A task that completes when owned cleanup settles.
bool IsNonFatalException(Exception exception)
Classifies failures that the host and readiness adapters may summarize or retain as secondary errors.
exception
False for out-of-memory, stack-overflow, access-violation, and unloaded-domain failures; true otherwise.
Fatal failures must propagate unchanged. Classification does not perform cleanup or handle corrupted process state.
EvidencePlan Plan { get; }
Source
Gets the immutable plan owned by this host instance.
EvidenceHostState State { get; set; }
Source
Gets the current one-way EvidenceHost lifecycle state.
Represents a stable, user-facing EvidenceHost lifecycle failure.
string Code { get; }
Source
Gets the stable diagnostic code.
string Fix { get; }
Source
Gets the concrete recovery action.
Retains a Windows directory object and its volume/128-bit file identity through workspace cleanup.
Opens the final component without following reparse points and rejects nondirectories. Sharing permits ordinary producer writes, rename and deletion; a renamed original remains alive until release. Creation timestamps are not identity because Windows can preserve them when a path is recreated.
EvidenceWorkspaceWindowsIdentity Open(string path)
Retains an existing directory using an extended absolute path and no-follow native open.
bool Matches(string path)
Checks a no-follow reopen against the still-retained original directory.
void Dispose()
Releases the original directory after cleanup or failed admission.
bool IsUsableFileId(ulong low, ulong high)
Rejects an unavailable all-zero native file ID before it can authorize a root.
string ExtendedPath(string absolutePath)
Formats an already absolute drive or UNC path for a Unicode native open.
The caller normalizes navigation before adding this prefix; it grants no filesystem access.
Configures the private scratch directory owned by an EvidenceWorkspace
.
MaximumBytes
MinimumFreeBytes
MaxEntries
MaxDepth
Reports that an EvidenceWorkspace has exhausted its configured storage allowance.
long LogicalBytes { get; }
Source
Gets the observed logical file size.
long MaximumBytes { get; }
Source
Gets the configured logical size limit.
long FreeBytes { get; }
Source
Gets the observed free bytes on the workspace volume.
long MinimumFreeBytes { get; }
Source
Gets the configured minimum free-space requirement.
Owns a fresh random scratch directory beneath a caller-owned parent directory.
The parent and any durable evidence beside the workspace remain caller-owned. Disposal removes only the fresh workspace after validating its ownership marker and retained filesystem metadata. A missing, replaced, or linked root is treated as invalid evidence. Inventory is bounded by EvidenceWorkspaceOptions.MaxEntries
and EvidenceWorkspaceOptions.MaxDepth
before any cleanup deletion begins. The retained metadata combines a unique marker with retained metadata, a held device/inode identity on Linux, and a held volume/file identity on Windows. Creation timestamps alone cannot establish directory identity. Callers must treat the workspace as trusted and must not concurrently replace or mutate its paths while it is in use. No portable implementation can eliminate every time-of-check/time-of-use race against a hostile concurrent process.
EvidenceWorkspace Create(string parent, EvidenceWorkspaceOptions? options = null)
Creates a new random workspace beneath parent
.
parent
options
An owned workspace lease.
EvidenceWorkspace CreateWithAdmissionHooksForTests(string parent, Action<string>? beforeIdentity, Action<string>? beforeMarker)
Exercises admission rollback with faults at the two ownership boundaries.
parent
beforeIdentity
beforeMarker
The production workspace when neither hook fails.
Hooks are restricted to friend-assembly failure tests. They do not replace filesystem observations or cleanup. Any hook failure must preserve its original exception and the ordinary preservation rules.
void CheckBudget()
Checks logical scratch usage and actual volume free space.
EvidenceWorkspaceBudgetException
string GetPath(string relativePath)
Returns a normalized absolute path for an owned artifact beneath the workspace.
relativePath
ValueTask DisposeAsync()
Removes only the owned workspace after revalidating its identity.
long MeasureWithRetry(Func<long> measure, Action validateOwnedRoot, bool retryTransientWindowsErrors)
Retries a complete inventory only for transient Windows filesystem access failures.
measure
validateOwnedRoot
retryTransientWindowsErrors
A complete measurement after successful ownership validation.
Maintenance can delete descendants while a budget sample inventories them. At most three measurements are attempted, separated by 10 ms, for exact access-denied, sharing-violation or delete-pending HRESULTs. Ownership validation, inventory bounds, quota checks and volume checks are never retried or suppressed. The delegates allow friend assemblies to verify the retry boundary without replacing production checks.
string RootPath { get; }
Source
Gets the newly created absolute workspace path.
Explicit inputs used to snapshot one successful coverage producer run.
RepositoryRoot
OutputDirectory
ReportPath
RawReportPath
TimingsPath
Scope
solution
or native
.Commit
Tree
Sdk
Configuration
Run
Platform
ExpectedTestProjects
The caller supplies source identity and workflow provenance through a trusted channel. Capture is a local snapshot, not a signature.
Adapts one bounded command to the typed EvidenceHost producer contract.
ValueTask<EvidenceProducerResult> ProduceAsync(EvidenceProducerContext context, CancellationToken cancellationToken)
Runs the command and evaluates assertions only after a zero exit code.
string Id { get; }
Source
Gets the stable producer identifier.
Describes the lifecycle state of an explicit consumer-owned EvidenceHost instance.