AppSurface Search
API Reference

Coverage

Type

CoverageArtifactCapability

Source

Describes the native filesystem guarantees verified for an artifact root.

Method

Verify

CoverageArtifactCapability Verify(string root)

Verifies that an existing private root supports the optional artifact operations.

Parameters

  • root
    An existing private directory on a supported local filesystem.

Returns

The filesystem and physical identity observed while the native probes succeeded.

Remarks

The probe uses only a uniquely named, manager-owned child directory and removes that exact child through the retained private-root lease. It never invokes another process.

Method

IsSupportedFileSystem

bool IsSupportedFileSystem(string platform, string? fileSystem, bool isLocalVolume)

Pure filesystem/platform classification seam used by the supported-lane tests.

Method

InvokeUnixFStatFs

int InvokeUnixFStatFs(string platform, Architecture architecture, int descriptor, nint buffer, Func<int, nint, int> unixFStatFs, Func<int, nint, int> darwinX64FStatFs)

Dispatches fstatfs to the symbol matching the native filesystem-stat structure ABI.

Remarks

Intel Darwin uses fstatfs$INODE64 ; arm64 Darwin and Linux use fstatfs .

Method

ReadFileSystem

(string FileSystem, bool IsLocal) ReadFileSystem(CoverageRunOutputLease root, string platform, Func<string, CoverageArtifactVolumeObservation> windowsVolumeObservation, Func<int, nint, int> unixFStatFs, Func<string, IEnumerable<string>> linuxMountInfo)

Reads filesystem metadata through narrow platform observations while keeping the retained directory handle and all path validation under the normal capability probe.

Parameters

  • root
    The already-validated retained private-root lease.
  • platform
    The platform lane: windows , macos , or linux .
  • windowsVolumeObservation
    Reads readiness, filesystem format, and drive type for a Windows volume root. It is called only in the Windows lane and should avoid reading the format when the volume is not ready.
  • unixFStatFs
    Runs fstatfs against the retained directory descriptor and supplied buffer.
  • linuxMountInfo
    Returns Linux mountinfo lines for the retained directory path.

Returns

The observed filesystem name and whether the volume is local.

Remarks

Production supplies DriveInfo , the native fstatfs call, and File.ReadLines(string) . Tests may inject observations to verify result and failure orchestration; injected values do not establish native filesystem guarantees. The platform argument exists to exercise each decision lane on any test host. All callers still need a real retained lease, and the public capability probe continues its no-follow path, identity, locking, and rename checks after this observation succeeds.

Method

ReadLinuxMountType

string ReadLinuxMountType(string path, IEnumerable<string> mountInfoLines)

Finds the filesystem type of the longest Linux mountpoint containing a path.

Parameters

  • path
    An absolute Linux path, normally taken from the retained directory lease.
  • mountInfoLines
    Lines from /proc/self/mountinfo ; ordering does not affect the result.

Returns

The filesystem type from the matching mountinfo record.

Remarks

Structurally malformed records and records with non-absolute mountpoints are skipped. Mount paths are decoded using mountinfo octal escapes and matched on path-component boundaries; if no valid record contains path , the parser throws IOException . Callers should pass the retained absolute Linux path and the complete mountinfo snapshot.

Type

CoverageArtifactVolumeObservation

Source

Windows volume metadata returned by a capability filesystem observation.

Parameters

  • IsReady
    Whether the volume can currently be inspected.
  • FileSystem
    The reported volume format; ignored when IsReady is false.
  • DriveType
    The reported drive type used to classify local storage.
Type

CoverageArtifactObjectState

Source

Native file identity and mutation fingerprint captured from one open handle.

Parameters

  • Identity
    Stable native volume/object identity.
  • Length
    Native file length in bytes.
  • ModifiedSeconds
    Last-write timestamp seconds or Windows FILETIME seconds.
  • ModifiedSubseconds
    Last-write subsecond component in native units.
  • ChangedSeconds
    Change timestamp seconds or Windows FILETIME seconds.
  • ChangedSubseconds
    Change subsecond component in native units.
Type

CoverageArtifactProvenanceReader

Source

Reads bounded, informational Git fingerprints for a coverage artifact run.

Remarks

Only hashes and the clean/dirty/unknown label leave this reader; Git output is never retained.

Method

ReadAsync

Task<CoverageArtifactProvenance> ReadAsync(string repository, CoverageArtifactProvenance policy, CancellationToken token = default)

Combines caller policy metadata with repository HEAD and working-tree state fingerprints.

Parameters

  • repository
    Repository root supplied by the coverage invocation.
  • policy
    Caller-provided provenance whose configuration fingerprint is preserved.
  • token
    Cancellation token for the bounded probes.
Method

ReadWithOutcomeAsync

Task<CoverageArtifactProvenanceReadResult> ReadWithOutcomeAsync(string repository, CoverageArtifactProvenance policy, CancellationToken token = default)

Reads provenance and returns a safe outcome for the Git-state probe.

Parameters

  • repository
    Repository root supplied by the coverage invocation.
  • policy
    Caller-provided provenance whose configuration fingerprint is preserved.
  • token
    Cancellation token for the bounded probes.

Returns

Fingerprints and a non-sensitive state describing whether the status probe completed.

Type

CoverageArtifactProvenanceReadResult

Source

Pairs provenance fingerprints with the safe outcome of its Git-state probe.

Parameters

  • Provenance
    The fingerprints to retain with the coverage artifact.
  • GitStateProbeOutcome
    A non-sensitive status-probe outcome for diagnostics and verification.
Type

CoverageTextWriters

Source

Caller-owned streams used for coverage progress and diagnostics.

Remarks

The coverage core never disposes, flushes, or retains these writers after an operation returns. Normal progress is written to Output and watchdog or critical diagnostics are written to Error .

Method

Create

CoverageTextWriters Create(TextWriter output, TextWriter error)

Validates the supplied writer pair before it enters the core.

Type

CoverageExecutionException

Source

Represents a stable execution failure raised by the private coverage core.

Remarks

Command adapters map this exception to their host-specific error contract. The rendered message deliberately preserves the existing ASCOV diagnostic text, while ExitCode preserves terminal watchdog exit 124.

Property

Code

string? Code { get; } Source

Gets the existing stable diagnostic code when the rendered diagnostic starts with one.

Property

ExitCode

int? ExitCode { get; } Source

Gets the optional host process exit code.

Type

CoverageEvidenceExecutionWorkflow

Source

Runs coverage collection and gate evaluation in their required order for first-party Evidence.

Method

RunAndGateAsync

Task<CoverageEvidenceExecutionResult> RunAndGateAsync(CoverageRunRequest runRequest, CoverageGateRequest gateRequest, CoverageTextWriters writers, CancellationToken cancellationToken)

Runs collection, then evaluates and writes the supplied gate only after a successful collection.

Type

CoverageEvidenceExecutionResult

Source

Captures the two ordered operation results produced for an Evidence coverage declaration.

Property

Run

CoverageRunResult Run { get; } Source

Gets the nonnull coverage collection result.

Property

Gate

CoverageGateResult? Gate { get; } Source

Gets the optional coverage-gate result produced after successful collection.

Remarks

This value is null when Run reports failure because the workflow deliberately skips gate evaluation and report writing. Callers must check CoverageRunResult.Success and handle a null value before accessing gate details.

Type

CoverageArtifactDiagnostic

Source

Describes a bounded, local storage diagnostic that never changes a primary coverage result.

Parameters

  • Code
    Stable ASCOV200–ASCOV211 identifier.
  • Operation
    Trusted operation name.
  • Cause
    Sanitized, bounded cause; arbitrary exception messages are forbidden.
  • Recovery
    Trusted recovery template, independent of report content.
  • SideEffects
    none, partial, complete, or unknown.
  • RunId
    Safe opaque run identifier, when available.
  • ObservedBytes
    An observed byte count, when known.
  • AllowedBytes
    The corresponding effective byte limit.
  • SourceStillAvailable
    Whether the original current output is still available.
  • SourceReplaced
    Whether the documented replacement already occurred.
  • Trace
    Sanitized bounded stack information for an unexpected local error.
Method

Failure

CoverageArtifactDiagnostic Failure(string code, string operation, Exception exception, string sideEffects = "none")

Creates a cause-specific optional-storage failure without disclosing exception text.

Parameters

  • code
    Stable diagnostic identifier.
  • operation
    Trusted operation name.
  • exception
    Failure whose type and bounded source frames may be displayed.
  • sideEffects
    Known publication or mutation state.
Method

WriteAsync

Task WriteAsync(TextWriter writer)

Writes one bounded trusted diagnostic to stderr; writer failures remain secondary.

Parameters

  • writer
    Caller-owned diagnostic writer.
Property

Reason

string? Reason { get; init; } Source

Gets the stable store-open failure reason, when classification is available; it is never ownership authority.

Property

Documentation

string Documentation { get; } Source

Gets the canonical reference anchor for the diagnostic.

Property

MaxRetries

int MaxRetries { get; } Source

Gets the maximum automatic retry count after the named condition has been resolved.

Property

Version

string Version { get; } Source

Gets the producing engine version for troubleshooting effective defaults.

Property

EnvironmentNames

IReadOnlyList<string> EnvironmentNames { get; } Source

Gets environment names relevant to local management, without their values.

Property

PolicySchemaVersion

int PolicySchemaVersion { get; } Source

Gets the schema defining the fixed storage limits used by this diagnostic.

Type

CoverageArtifactDisplay

Source

Bounds strings and renders local paths without exposing user prefixes or control characters.

Method

PathLabel

string PathLabel(string path, string? repositoryRoot = null)

Renders an observed path for local diagnostics, with no credential-bearing URI support.

Parameters

  • path
    A local filesystem path, never a command template.
  • repositoryRoot
    Optional repository prefix to replace with a relative path.
Method

Bound

string Bound(string value)

Escapes controls and bounds an informational value; it never creates executable shell text.

Parameters

  • value
    Local informational text.
Type

CoverageArtifactWorkBudget

Source

Tracks one cumulative monotonic deadline for optional storage work.

Method

Check

void Check(CancellationToken token)

Checks cancellation and the work deadline before the next bounded chunk.

Parameters

  • token
    The original caller cancellation token.
Property

Elapsed

TimeSpan Elapsed { get; } Source

Gets elapsed wall-clock work time, including waits and filesystem operations.

Property

Remaining

TimeSpan? Remaining { get; } Source

Gets the remaining cooperative allowance, or null for explicit cancellable operations.

Type

CoverageArtifactStoreFailure

Source

Classifies failures without parsing exception messages or disclosing persisted identities.

Remarks

Schema-v1 native identities bind live objects but contain no independent continuity proof. A differing device/volume therefore remains a refusal, including when the file ID matches. The classification is diagnostic only: it never replaces retained-handle validation or authorizes repair.

Method

Invalid

InvalidDataException Invalid(CoverageArtifactStoreFailureKind kind, Exception? inner = null)

Annotates an ordinary invalid-data error, preserving the existing exception contract.

Method

PrivateAccess

IOException PrivateAccess()

Annotates a native permission refusal while preserving its IOException contract.

Method

MarkMissing

IOException MarkMissing(IOException exception)

Classifies a nonempty unmarked root without changing the existing IOException refusal contract.

Method

Mark

T Mark<T>(T exception, CoverageArtifactStoreFailureKind kind)

Attaches only a trusted bounded classification while retaining the original exception type.

Method

Kind

CoverageArtifactStoreFailureKind? Kind(Exception exception)

Gets a trusted classification, or null for unclassified errors; messages and payloads are never inspected.

Method

CompareIdentity

CoverageArtifactStoreFailureKind CompareIdentity(string persisted, string observed)

Distinguishes an observed volume change only when both complete legacy tuples parse.

Remarks

Matching file IDs across volumes are insufficient. Unknown formats remain a generic identity mismatch.

Method

TryReadIdentity

bool TryReadIdentity(string value, out ulong volume)

Parses nonempty unsigned tuple fields in the complete schema-v1 record format; malformed fields fail closed without slicing outside their bounds.

Method

Cause

string Cause(CoverageArtifactStoreFailureKind kind)

Gets actionable trusted text for a known refusal, without raw paths, metadata or native IDs.

Method

Recovery

string Recovery(CoverageArtifactStoreFailureKind kind)

Gets the conservative schema-v1 recovery path; no operation rebinds uncertain registrations.

Type

CoverageArtifactObservation

Source

A bounded, read-only lower-bound observation of known coverage output.

Property

ContinuationDirectories

IReadOnlyList<string> ContinuationDirectories { get; init; } Source

Gets bounded relative directories to inspect first on the next observation; these grant no ownership.

Type

CoverageArtifactContributor

Source

A relative path and size observed during coverage inspection.

Type

CoverageArtifactInspectionError

Source

A sanitized inspection failure, scoped to a repository-relative path.

Type

CoverageCollectorRisk

Source

Collector settings state and a precise reason for the result.

Type

CoverageArtifactInspector

Source

Inspects known test output without reading report payloads or modifying files.

Method

Inspect

CoverageArtifactObservation Inspect(string repositoryRoot, TimeProvider clock, TimeSpan budget, int maximumEntries, CancellationToken token, IReadOnlyList<string>? continuationDirectories = null)

Counts regular files below repository TestResults and coverage-output roots.

Remarks

Budgets include directory enumerations and entry metadata checks. Incomplete results are lower bounds.

Method

ReadCollectorRisk

CoverageCollectorRisk ReadCollectorRisk(string settingsPath)

Reads a supplied effective settings file safely; this reports configured risk, not execution.

Method

TryOpenRegularFile

bool TryOpenRegularFile(string path, out FileStream? stream, out long length, CoverageArtifactCandidateCalls? nativeCalls = null)

Opens a candidate without following links and validates native regular-file facts.

Parameters

  • path
    Observed local path inside the caller's bounded scan.
  • stream
    A caller-owned stream on success; null when native facts reject the candidate.
  • length
    Observed nonnegative byte length on success.
  • nativeCalls
    Optional per-call native observations for decoding and cleanup tests.

Remarks

Injected observations verify managed decisions; native platform acceptance is separate.

Type

CoverageArtifactCandidateCalls

Source

Per-call native candidate-file observations; defaults always inspect the real host.

Remarks

Fake opens must return caller-owned native handles. Tests do not establish another OS's ABI or containment.

Property

Default

CoverageArtifactCandidateCalls Default { get; } Source

Gets the real host's immutable observation set.

Property

IsWindows

bool IsWindows { get; init; } Source

Gets whether Windows handle metadata is selected.

Property

IsMacOS

bool IsMacOS { get; init; } Source

Gets whether Darwin stat decoding is selected.

Property

IsLinux

bool IsLinux { get; init; } Source

Gets whether Linux stat decoding is supported.

Property

Architecture

Architecture Architecture { get; init; } Source

Gets the process architecture used to decode Linux stat mode.

Property

WindowsOpen

Func<string, SafeFileHandle> WindowsOpen { get; init; } Source

Gets the Windows no-follow regular-candidate open operation.

Property

WindowsType

Func<SafeFileHandle, uint> WindowsType { get; init; } Source

Gets the Windows object-type observation.

Property

WindowsInformation

CoverageArtifactStateCalls.ReadWindowsInformation WindowsInformation { get; init; } Source

Gets the Windows native size and attribute observation.

Property

UnixOpen

Func<string, int, int> UnixOpen { get; init; } Source

Gets the Unix no-follow candidate open operation.

Property

UnixStat

Func<int, nint, int> UnixStat { get; init; } Source

Gets the Unix native stat operation.

Type

CoverageArtifactInventory

Source

Collects explicitly writer-owned paths without adopting pre-existing output contents.

Remarks

Writers register each attempted file publication and only invocation-unique subtrees. Hashing occurs after producers drain, under the caller's output lease. An incomplete inventory cannot publish complete history.

Method

RecordFile

void RecordFile(string path)

Registers a path that this invocation creates or overwrites; absent failed writes are not invented.

Parameters

  • path
    A known writer destination within this output.
Method

RecordFreshTree

void RecordFreshTree(string path)

Registers a newly created invocation-unique subtree, never a reused project or output directory.

Parameters

  • path
    A newly created raw collector, diagnostic or generator directory.
Method

ObserveBeforeWrite

FileObservation? ObserveBeforeWrite(string path)

Captures the pre-write state of a fixed-name artifact so a retained stale file is not adopted.

Parameters

  • path
    A writer destination under this output.

Returns

The prior length and write timestamp, or null when the destination did not exist.

Method

RecordAfterWrite

void RecordAfterWrite(string path, FileObservation? before)

Records a newly created producer file; ambiguous retained destinations make the inventory incomplete.

Parameters

  • path
    Writer destination.
  • before
    State immediately before the participating producer.
Method

Capture

IReadOnlyList<CoverageArtifactInventoryEntry> Capture(CancellationToken token)

Hashes the writer-owned regular files after producers stop, preserving exact original bytes.

Parameters

  • token
    Caller cancellation; terminal failure inventory may use its independent bounded budget.

Returns

A bounded complete inventory, or an exception that prevents optional complete publication.

Method

Provenance

CoverageArtifactProvenance Provenance(string driver, string configuration, IEnumerable<string> projects, string? include, string? exclude)

Creates bounded informational provenance from an invocation's declared policy.

Parameters

  • driver
    Selected collector integration.
  • configuration
    Selected build configuration.
  • projects
    Ordered project identities.
  • include
    Coverage include policy.
  • exclude
    Coverage exclude policy.

Returns

Fingerprints contain no test arguments, environment values or source contents.

Property

OutputDirectory

string OutputDirectory { get; } Source

Gets the absolute output root whose writers own this inventory.

Property

ProducingVersion

string ProducingVersion { get; } Source

Gets the exact producing assembly version without reading environment or process arguments.

Type

FileObservation

Source

Length and timestamp used to distinguish a writer's output from a retained fixed-name file.

Type

CoverageArtifactGateContext

Source

Coordinates a gate's read roots and report-write destination before evaluation starts.

Method

AcquireAsync

Task<CoverageArtifactGateContext> AcquireAsync(CoverageGateRequest request, TextWriter errors, CancellationToken token)

Acquires strongest modes in deterministic physical-object order, reusing an explicit nested session.

Parameters

  • request
    Numeric gate request with owned input/report roots.
  • errors
    Local diagnostics writer.
  • token
    Caller cancellation before acquiring authority.

Returns

A disposable context retained through report publication and caller hashing.

Method

RecordReportsAsync

Task RecordReportsAsync(CoverageGateRequest request, CoverageGateResult result, CancellationToken token)

Extends compatible current inventory with gate report bytes after publication.

Parameters

  • request
    Original report destination.
  • result
    Report paths actually published by this gate.
  • token
    Caller cancellation.
Method

Dispose

void Dispose()

Releases all acquired leases in reverse deterministic order.

Type

CoverageArtifactWarnings

Source

Coordinates bounded repository observations and persistent, local warning cooldowns.

Remarks

Each instance shares one second and 10,000 entries across preflight and terminal inspection. Discovered files remain observations: they never become artifact ownership or deletion authority. Warning-state failure cannot replace the primary coverage result.

Method

ObserveAsync

Task ObserveAsync(bool terminal, IReadOnlyList<CoverageArtifactInventoryEntry>? inventory, CancellationToken token)

Inspects at preflight or terminal publication with the remaining cumulative observation budget.

Parameters

  • terminal
    Whether the remaining inspection allowance is available.
  • inventory
    Newly produced files, accounted even if traversal reaches its limit.
  • token
    Caller cancellation; optional inspection never swallows a primary caller cancellation.
Method

SettingsAsync

Task SettingsAsync(IEnumerable<CoverageArtifactSettingsResult> observations)

Reports configured collector risk or unknown settings, under the same persistent cooldown.

Parameters

  • observations
    Effective observations for selected projects/frameworks.
Method

EmitAsync

Task EmitAsync(CoverageArtifactDiagnostic diagnostic, string condition, long bytes)

Emits one trusted condition unless an equivalent persisted observation is still in cooldown.

Parameters

  • diagnostic
    Bounded diagnostic supplied by an AppSurface observer.
  • condition
    Internal condition fingerprint input; never emitted or used as a path.
  • bytes
    Observed lower-bound bytes; repeated observations are not accumulated.
Type

CoverageRunOutputLease

Source

Extends the existing retained-directory boundary for private artifact storage.

Method

GetArtifactObjectIdentity

string GetArtifactObjectIdentity(SafeFileHandle handle)

Gets the physical identity of an already-opened regular file or directory.

Parameters

  • handle
    A validated native object handle retained by the caller.
Method

GetArtifactObjectState

CoverageArtifactObjectState GetArtifactObjectState(SafeFileHandle handle, CoverageArtifactStateCalls? nativeCalls = null)

Reads native identity, length, last-write time and change time from an open regular file.

Parameters

  • handle
    A retained native handle to the file.
  • nativeCalls
    Optional per-call native observations for decision tests; omission uses the actual host APIs.

Returns

The file state used to detect in-place changes across an archive read.

Remarks

Injected observations verify managed decoding and rejection decisions, not the native filesystem or ABI.

Method

AcquireArtifactDirectory

CoverageRunOutputLease? AcquireArtifactDirectory(string path, bool createMissing, bool requirePrivate, bool allowWindowsRenameSharing = false, Func<int, uint, int>? unixFChmod = null, Action<string>? beforeWindowsCreate = null)

Opens a retained directory without coverage-output ownership semantics.

Parameters

  • path
    Absolute directory path, traversed without links.
  • createMissing
    Whether missing components may be privately created.
  • requirePrivate
    Whether current-user private permissions are required.
  • allowWindowsRenameSharing
    Whether a cooperative lease needs compatible writer sharing rather than restore-parent exclusion.
  • unixFChmod
    Optional per-lease native permission operation for failure tests; defaults to fchmod.
  • beforeWindowsCreate
    Optional race seam immediately before creating a missing Windows component; production omits it.

Returns

A retained directory, or null when an existing-only path is missing.

Remarks

Existing permissions are validated, never repaired. Callers separately validate store/schema authority.

Method

VerifyArtifactBinding

void VerifyArtifactBinding()

Rechecks the entire pathname against the directory objects originally acquired.

Method

OpenArtifactOperationLock

SafeFileHandle OpenArtifactOperationLock(string name = ".appsurface-coverage-operation.lock", bool requirePrivate = false, bool readExistingOnly = false)

Opens the Windows cooperative-lock file without following links or allowing replacement.

Parameters

  • name
    One fixed protocol filename owned by the caller's output or private domain.
  • requirePrivate
    Whether to require private ownership and a zero-length candidate coordination file.
  • readExistingOnly
    Whether an existing lock requires only read access. A missing protocol lock may still be created in a writable root.
Method

ReadArtifactCoordinationFileLength

long ReadArtifactCoordinationFileLength(string name)

Validates an existing zero-length private coordination file without creating or changing it.

Parameters

  • name
    One fixed domain protocol filename.

Returns

The validated length, always zero.

Method

VerifyArtifactOperationLockBinding

void VerifyArtifactOperationLockBinding(SafeFileHandle lockHandle, string expectedIdentity, string name = ".appsurface-coverage-operation.lock")

Verifies the named Windows operation lock still identifies the retained lock object.

Parameters

  • lockHandle
    The retained lock-file handle used by the operation lease.
  • expectedIdentity
    The lock-file identity captured when the lease was acquired.
  • name
    The fixed filename selected by the same lease protocol.
Method

CreateArtifactDirectory

CoverageRunOutputLease CreateArtifactDirectory(string name, Action? beforeCreate = null, Action? onCreated = null)

Creates a private immediate child and retains its complete no-follow path.

Parameters

  • name
    One portable path component.
  • beforeCreate
    Optional per-call race observation after preflight; native creation still requires a fresh destination.
  • onCreated
    Optional observation immediately after native creation, before validation that may fail; never called on a no-replace refusal.

Returns

The privately created child directory.

Method

OpenArtifactFile

FileStream OpenArtifactFile(string name, bool createNew, bool requirePrivate = true)

Opens an immediate regular, singly-linked file through the retained directory.

Parameters

  • name
    One portable filename.
  • createNew
    Whether to atomically create a new private file; otherwise read existing bytes.
  • requirePrivate
    Whether to enforce current-user private file access.

Returns

A caller-owned stream bound to the opened object.

Method

EnumerateArtifactEntries

IReadOnlyList<CoverageArtifactDirectoryEntry> EnumerateArtifactEntries(int maximumEntries)

Enumerates at most a caller-supplied number of immediate entries without following links.

Parameters

  • maximumEntries
    Strict positive allocation and traversal bound.

Returns

Validated regular-file and directory names.

Method

MoveArtifactEntry

void MoveArtifactEntry(string sourceName, CoverageRunOutputLease destination, string destinationName, bool replaceFile = false, string? expectedSourceIdentity = null)

Atomically renames an immediate child, optionally replacing one regular metadata file.

Parameters

  • sourceName
    Existing immediate entry.
  • destination
    Retained destination directory on the same volume.
  • destinationName
    New immediate entry name.
  • replaceFile
    Whether one already-validated regular file may be replaced.
  • expectedSourceIdentity
    Previously verified source identity, required for staged-directory publication.
Method

DeleteArtifactEntry

void DeleteArtifactEntry(string name, int maximumEntries, string? expectedIdentity = null)

Deletes only a previously authorized immediate entry through the retained directory.

Parameters

  • name
    Manager-authorized entry name; authority must be established by its caller.
  • maximumEntries
    Bound for the complete child snapshot, including directories.
  • expectedIdentity
    Optional identity previously verified by a reader.

Remarks

Unknown trees, links, changed identities and excessive depth fail closed; they are not repaired. Windows deletion completes after retained handles to the entry close. Callers keep their candidate lease through deletion and metadata publication, then dispose it before asserting namespace disappearance.

Method

ValidateArtifactComponent

void ValidateArtifactComponent(string name)

Validates one cross-platform path component before any filesystem call.

Parameters

  • name
    A manifest-derived filename or directory name.
Method

AcquirePrivateWindowsDirectory

bool AcquirePrivateWindowsDirectory(bool createMissing, bool allowRenameSharing, Action<string>? beforeCreate)

Retains and validates each Windows path component, reopening a competing creator without repairing its access.

Method

CreateMissingWindowsDirectory

void CreateMissingWindowsDirectory(string path, Action<string> createDirectory)

Accepts only an already-existing-name race during an idempotent Windows component walk.

Parameters

  • path
    The missing component observed beneath the retained parent.
  • createDirectory
    Private native creation operation; injectable for managed error-contract tests.

Remarks

The caller must reopen and verify kind, no-follow identity and required private access. Fresh destinations never use this helper.

Method

CreatePrivateWindowsDirectory

void CreatePrivateWindowsDirectory(string path)

Atomically creates one new directory with the current-user owner and protected private ACL.

Method

CreateArtifactWindowsDirectory

void CreateArtifactWindowsDirectory(string path, byte[] descriptor, Func<string, nint, bool>? createDirectory = null)

Publishes a fresh Windows directory with its already-built private security descriptor in the native create call.

Parameters

  • path
    The validated absolute Windows path beneath a retained parent.
  • descriptor
    The complete private security descriptor, pinned until native creation returns.
  • createDirectory
    Optional per-call native creation seam; omission calls CreateDirectoryW. Simulations do not prove Windows ACL enforcement.
Method

ValidateArtifactWindowsAccess

void ValidateArtifactWindowsAccess(string? owner, string user, IEnumerable<CoverageArtifactAccessRule> rules)

Rejects Windows ownership or allow rules granting access beyond the current user and system administrators.

Parameters

  • owner
    Owner SID observed from the retained object's access control descriptor.
  • user
    The effective current-user SID from the native identity observation.
  • rules
    SID-normalized access rules, including inherited and explicit allow/deny entries.

Remarks

These are policy decisions over observed facts; caller tests do not establish native ACL retrieval or Windows handle binding.

Method

ValidateArtifactUnixMetadata

void ValidateArtifactUnixMetadata(SafeFileHandle handle, bool directory, bool requirePrivate, CoverageArtifactStateCalls? nativeCalls = null, uint? effectiveUserId = null)

Validates ownership, link count and private permissions from one retained Unix object.

Parameters

  • handle
    The retained native file or directory.
  • directory
    Whether directory permissions and link-count semantics apply.
  • requirePrivate
    Whether exact private permissions and current-user ownership are required.
  • nativeCalls
    Optional per-call stat observation for decoding tests; defaults to the actual host.
  • effectiveUserId
    Optional effective user identity for policy-decision tests; defaults to geteuid.

Remarks

Synthetic observations test rejection policy and stat decoding, not another platform's native ABI.

Method

ReadArtifactWindowsNames

IReadOnlyList<string> ReadArtifactWindowsNames(SafeFileHandle directory, int maximumEntries, Func<SafeFileHandle, IEnumerable<string>>? enumerate = null)

Collects bounded immediate Windows names from the retained directory.

Parameters

  • directory
    Retained directory handle.
  • maximumEntries
    Strict bound, checked before retaining another name.
  • enumerate
    Optional per-call name observation for iterator failure tests; defaults to the native bound path.

Remarks

Injected names verify the count and iterator decisions; they do not prove Windows enumeration.

Method

ReadArtifactUnixNames

IReadOnlyList<string> ReadArtifactUnixNames(SafeFileHandle directory, int maximumEntries, CoverageArtifactEnumerationCalls? nativeCalls = null)

Enumerates a bounded Unix directory with explicit descriptor/stream ownership.

Parameters

  • directory
    Retained source directory handle, never disposed by this method.
  • maximumEntries
    Strict entry count bound, excluding dot entries.
  • nativeCalls
    Optional per-call native enumeration operations for failure/cleanup tests.

Remarks

Omission uses the host APIs; fake results exercise orchestration, not the kernel ABI.

Method

DuplicateCloseOnExec

int DuplicateCloseOnExec(int descriptor)

Atomically duplicates a Unix descriptor with close-on-exec set.

Parameters

  • descriptor
    The retained descriptor to duplicate.

Returns

A close-on-exec duplicate, or a negative value on native failure.

Method

RenameArtifactWindows

void RenameArtifactWindows(SafeFileHandle source, SafeFileHandle destination, string name, bool replace, Func<SafeFileHandle, nint, uint, int>? publish = null, Func<int, uint>? translateError = null)

Encodes a Windows handle-relative rename and rejects unsuccessful native publication.

Parameters

  • source
    Source object retained for the whole native call.
  • destination
    Retained destination directory handle.
  • name
    An immediate filename already validated by the caller.
  • replace
    Whether the caller authorized replacing one regular metadata file.
  • publish
    Optional native call for buffer and failure tests; defaults to NtSetInformationFile.
  • translateError
    Optional native error translation for tests; defaults to RtlNtStatusToDosError.

Remarks

Tests can inspect the encoded request without executing Windows or attesting to its ABI.

Property

ArtifactDirectoryPath

string ArtifactDirectoryPath { get; } Source

Gets the canonical path whose binding is retained by this lease.

Property

ArtifactDirectoryIdentity

string ArtifactDirectoryIdentity { get; } Source

Gets an operating-system object identity, independent of path spelling.

Property

ArtifactDirectoryHandle

SafeFileHandle ArtifactDirectoryHandle { get; } Source

Gets the retained directory handle for a cooperative native lock; the caller must not dispose it.

Type

CoverageArtifactEnumerationCalls

Source

Per-call native Unix enumeration results with production descriptor ownership defaults.

Remarks

Fake results must describe their own descriptors and pointers; they do not establish filesystem support.

Property

Default

CoverageArtifactEnumerationCalls Default { get; } Source

Gets the immutable default call set.

Property

Duplicate

Func<int, int> Duplicate { get; init; } Source

Gets a fresh close-on-exec descriptor for the same directory.

Property

Seek

Func<int, long, int, long> Seek { get; init; } Source

Gets the rewind operation on the fresh descriptor.

Property

OpenDirectory

Func<int, nint> OpenDirectory { get; init; } Source

Gets the operation transferring descriptor ownership to a directory stream.

Property

ReadDirectory

Func<nint, nint> ReadDirectory { get; init; } Source

Gets the next native directory entry or zero at end/failure.

Property

Close

Func<int, int> Close { get; init; } Source

Gets the close operation before stream ownership transfers.

Property

CloseDirectory

Func<nint, int> CloseDirectory { get; init; } Source

Gets the operation closing the directory stream and its descriptor.

Type

CoverageArtifactDirectoryEntry

Source

Describes a bounded, no-follow directory observation; it does not grant deletion authority.

Parameters

  • Name
    One immediate component.
  • IsDirectory
    Whether the opened object is a directory.
  • Identity
    Native volume/object identity of the opened entry.
Type

CoverageArtifactStateCalls

Source

Per-call native observations used to verify file-state decoding without altering global platform state.

Remarks

Defaults call the host APIs. Tests may supply a platform, native results and retained-object identity; callers must not mix synthetic stat bytes with a real filesystem claim. No ownership check is bypassed in production.

Property

Default

CoverageArtifactStateCalls Default { get; } Source

Gets the host-bound default operations.

Property

IsWindows

bool IsWindows { get; init; } Source

Gets whether Windows file-state decoding is selected.

Property

IsMacOS

bool IsMacOS { get; init; } Source

Gets whether Darwin stat decoding is selected.

Property

IsLinux

bool IsLinux { get; init; } Source

Gets whether Linux stat decoding is available.

Property

Architecture

Architecture Architecture { get; init; } Source

Gets the native process architecture used for Linux stat layouts.

Property

WindowsBasic

ReadWindowsBasic WindowsBasic { get; init; } Source

Gets the native Windows timestamp call, including its success result.

Property

WindowsInformation

ReadWindowsInformation WindowsInformation { get; init; } Source

Gets the native Windows size and identity metadata call.

Property

UnixStat

Func<int, nint, int> UnixStat { get; init; } Source

Gets the native Unix stat call; failure leaves the P/Invoke error available.

Property

Identity

Func<SafeFileHandle, string> Identity { get; init; } Source

Gets the identity observer for the same retained handle.

Type

CoverageArtifactAccessRule

Source

One SID-normalized Windows access rule observed through the native ACL API.

Parameters

  • Principal
    Security-identifier text returned for the rule's principal.
  • Rights
    The observed unsigned access mask; zero grants no access.
  • Allows
    Whether the native rule allows the observed access mask.
Type

CoverageArtifactPolicy

Source

Describes the user-editable retention and warning thresholds for coverage artifacts.

Remarks

Policy values control optional history retention and growth warnings. They do not change coverage collection, test execution, or gate thresholds. Hard resource limits are defined by CoverageArtifactLimits and cannot be raised by this policy. The JSON object requires schemaVersion with value 1 ; its optional fields are historyMaxBytes , historyMaxAgeDays , repositoryWarningBytes , domainWarningBytes , and warningCooldownHours . Omitted optional fields retain the property defaults shown below. Field names are case-sensitive. Unknown fields, duplicate names, missing or unsupported schema versions, and nesting deeper than 16 levels are rejected. Callers should apply only the returned complete policy; an invalid document never produces a partially applied result and does not make coverage collection optional.

Method

Read

CoverageArtifactPolicy Read(Stream policyStream)

Reads and validates a version 1 coverage artifact policy from a bounded UTF-8 JSON stream. Integer fields must use JSON integer syntax and satisfy their documented ranges; fractions, exponents, negative values where prohibited, unknown fields, duplicate fields, and documents deeper than 16 levels are rejected. The parser reads no more than 65,537 bytes to distinguish an allowed 65,536-byte document from an oversized one.

Parameters

  • policyStream
    A readable stream positioned at the start of the JSON document. The stream is not disposed by this method and need not support seeking.

Returns

The complete policy, with defaults applied to omitted optional fields.

Exceptions

  • ArgumentNullException
    policyStream is null.
  • ArgumentException
    policyStream cannot be read.
  • InvalidDataException
    The document is malformed, exceeds the byte or nesting limit, uses an unsupported schema, contains duplicate or unknown fields, or supplies a value outside its range.
  • IOException
    The underlying stream fails while being read.

Remarks

The stream remains open and must begin at the document's first byte. Reading is bounded even for a non-seekable or untrusted stream; the complete document is validated before a policy value is returned.

Property

HistoryMaxBytes

long HistoryMaxBytes { get; init; } Source

Gets the maximum eligible history size in bytes. Its default is 2 GiB and its allowed range is zero through 1 TiB. Zero disables new history and allows only eligible unpinned history to expire during maintenance.

Property

HistoryMaxAgeDays

int HistoryMaxAgeDays { get; init; } Source

Gets the maximum age in days for eligible history before it may expire. Its default is 7 days and its allowed range is 1 through 365 days.

Property

RepositoryWarningBytes

long RepositoryWarningBytes { get; init; } Source

Gets the repository-growth warning threshold in bytes. Its default is 1 GiB and its allowed range is 1 byte through 1 TiB.

Property

DomainWarningBytes

long DomainWarningBytes { get; init; } Source

Gets the domain-growth warning threshold in bytes. Its default is 2 GiB and its allowed range is 1 byte through 1 TiB.

Property

WarningCooldownHours

int WarningCooldownHours { get; init; } Source

Gets the minimum number of hours between repeated equivalent growth warnings. Its default is 24 hours and its allowed range is 1 through 168 hours.

Type

CoverageArtifactLimits

Source

Defines fixed resource caps and cooperative work budgets for coverage artifact storage.

Remarks

These limits protect optional storage management from unbounded work or metadata growth. They are not user-configurable and do not constrain coverage collection or gate behavior.

Type

CoverageArtifactJson

Source

Reads bounded private metadata, rejecting ambiguous duplicate keys before deserialization.

Method

Read

T Read<T>(Stream stream, long maximumBytes, JsonSerializerOptions options)

Reads at most the metadata limit plus one byte, even if an opened file grows.

Type parameters

  • T
    Expected metadata record type.

Parameters

  • stream
    Caller-owned stream positioned at the document start.
  • maximumBytes
    Strict encoded-byte admission limit.
  • options
    Schema-specific serializer options, including the nesting bound.

Returns

The unambiguous schema record; callers validate its semantic facts.

Type

CoverageArtifactMetadataPublication

Source

Publishes bounded observation state through one fixed, private staging slot.

Remarks

The caller must hold the directory's exclusive operation lease. A fixed slot bounds crash remnants; only a validated private regular slot with its retained identity may be reconciled. Unknown names and oversized, linked, or nonprivate slots remain untouched. This grants no current-output authority.

Method

Write

void Write(CoverageRunOutputLease directory, string destinationName, byte[] bytes, long maximumBytes, Action? beforePublish = null)

Writes and atomically replaces one bounded state file without accumulating unique remnants.

Parameters

  • directory
    Private observation directory under an exclusive operation lease.
  • destinationName
    Immediate metadata name authorized by the observation writer.
  • bytes
    Complete, validated encoded state.
  • maximumBytes
    Category-specific encoded-byte bound, also applied to abandoned staging.
  • beforePublish
    Optional per-call fault/scheduling seam after durable staging and before rename.

Remarks

The hook verifies cleanup decisions; production omits it. It must not be used as ownership authority.

Type

CoverageArtifactSession

Source

Holds one compatible output mutation context across collection, gate reports and evidence hashing.

Remarks

Required output coordination remains authoritative even when optional private history is unavailable.

Method

BeginAsync

Task<CoverageArtifactSession> BeginAsync(string output, string repository, bool clean, CoverageTextWriters writers, TimeProvider clock, CancellationToken token, CoverageArtifactOperationLease? operationLease = null)

Acquires output mutation authority, then attempts a prior-run snapshot at the normal clean boundary.

Parameters

  • output
    Absolute safe output root, already validated by the command.
  • repository
    Repository/worktree root whose outputs are accounted together.
  • clean
    Whether existing canonical artifacts will undergo normal pre-run cleanup.
  • writers
    Primary command's local output streams.
  • clock
    Shared monotonic clock.
  • token
    Original cancellation token.
  • operationLease
    Optional exclusive output lease acquired with other roots in deterministic identity order.

Returns

A required run-long lease plus best-effort optional storage.

Method

VerifyBinding

void VerifyBinding()

Verifies the required output identity before a participating mutation or read.

Method

CompleteAsync

Task CompleteAsync(string outcome, CoverageArtifactProvenance provenance)

Publishes current-run registration without replacing the primary command outcome.

Parameters

  • outcome
    success, failed or interrupted; never inferred from stored historical XML.
  • provenance
    Bounded informational driver/configuration policy facts.
Method

RecordPublishedArtifactsAsync

Task RecordPublishedArtifactsAsync(IEnumerable<string> publishedFiles)

Records reports written under this session and republishes the same run metadata.

Parameters

  • publishedFiles
    Report paths successfully written by the current gate call.
Method

UpdateRegisteredInventoryAsync

Task UpdateRegisteredInventoryAsync(string outputDirectory, IEnumerable<string> publishedFiles, TextWriter errors, CoverageArtifactOperationLease outputLease)

Updates an existing registered run's sidecar and registry after an independent gate writes reports.

Parameters

  • outputDirectory
    The gate output directory already held under an exclusive lease.
  • publishedFiles
    Report paths successfully written by the current gate call.
  • errors
    Best-effort diagnostic output; failures never replace the gate result.
  • outputLease
    The gate's retained exclusive operation lease, captured before evaluation and report publication.

Remarks

The sidecar and existing non-report files must still match their registered lengths and hashes. Publication remains bound to the caller's leased physical output, including after a directory rename. A nonparticipating writer's changes are never adopted under earlier provenance.

Method

Dispose

void Dispose()

Releases compatible output authority after every participating caller has finished.

Method

PublishSidecar

void PublishSidecar(CoverageRunOutputLease output, byte[] json, Action? beforePublish = null)

Publishes the current sidecar and removes only this call's staging file when publication fails.

Parameters

  • output
    Retained output directory under the caller's exclusive operation lease.
  • json
    Bounded serialized sidecar bytes.
  • beforePublish
    Optional per-call scheduling/failure seam after durable staging; omitted in production.

Remarks

Cleanup checks the staged file's retained object identity. A replacement entry is preserved, and cleanup failure never replaces the original publication failure.

Method

FindOwnedInputRoot

string? FindOwnedInputRoot(string coveragePath, IDictionary<string, bool>? observedRoots = null)

Finds a physically bound managed input root without adopting copied metadata.

Parameters

  • coveragePath
    An input report whose containing directories are inspected, up to 32 levels.
  • observedRoots
    Optional acquisition-local observations shared by one merge's shard discovery; never retain or reuse across commands.

Returns

The nearest root whose bounded sidecar names its actual physical output, or null.

Remarks

Missing, malformed, inaccessible and foreign sidecars do not grant ownership or require an input lock. A copied report remains eligible for the existing arbitrary-XML numeric gate. First-party Evidence retains its explicit execution session; this observation is neither source attestation nor registration.

Method

ReadCurrent

CoverageArtifactCurrentRun ReadCurrent(Stream input)

Reads one bounded current sidecar, requiring compatible explicit producer inventory.

Parameters

  • input
    A caller-owned no-follow regular-file stream.
Method

IsOptionalFailure

bool IsOptionalFailure(Exception exception)

Classifies expected optional store, filesystem, and metadata failures without catching programming errors broadly.

Property

Inventory

CoverageArtifactInventory Inventory { get; } Source

Gets this invocation's explicit writer-owned inventory.

Property

Warnings

CoverageArtifactWarnings Warnings { get; } Source

Gets the shared, bounded warning context for preflight, settings, and terminal observations.

Type

CoverageArtifactCurrentRun

Source

Describes the explicitly owned current-run files eligible for a verified snapshot.

Parameters

  • ManifestBase
    Bounded run metadata used as the base of the completed archive manifest.
  • Inventory
    The producer-supplied inventory; the store never discovers files to adopt.
  • OutputPath
    The existing output directory containing current artifacts.
  • RepositoryPath
    The repository or worktree associated with the output.
Type

CoverageArtifactStoreStatus

Source

A bounded point-in-time view of the private coverage artifact domain.

Property

PinnedBytes

long PinnedBytes { get; init; } Source

Gets archived bytes protected by explicit pins, separate from current output bytes.

Property

StagingReservedBytes

long StagingReservedBytes { get; init; } Source

Gets bytes reserved for active or unreconciled staging; not a measurement of reclaimable bytes.

Property

MetadataBytes

long MetadataBytes { get; init; } Source

Gets bounded metadata bytes read for this observation.

Property

ExpiryReceiptCount

int ExpiryReceiptCount { get; init; } Source

Gets bounded expiry receipts retained for the last seven days.

Property

OverflowObservations

IReadOnlyList<CoverageArtifactOverflowObservation> OverflowObservations { get; init; } Source

Gets recent overflow observations; repeated observations are never added to exact current totals.

Type

CoverageArtifactOverflowObservation

Source

A recent capacity observation, never ownership authority or an exact domain total.

Type

CoverageArtifactStore

Source

Coordinates private coverage artifact metadata and verified historical snapshots.

Remarks

The store manages only producer-registered inventories and its own complete archives. Current output remains at its existing path. Metadata is versioned and bounded; unknown or invalid state fails closed and is never treated as permission to adopt or delete files.

Method

CreateNewDomain

string CreateNewDomain(string destination, bool apply, CancellationToken cancellationToken, Action? beforeRegistryPublication = null, Action? onDirectoryCreated = null, Action? beforeDestinationInspection = null, Action? beforeDestinationReopen = null)

Previews or explicitly creates a separate, empty private domain without accessing the configured old domain.

Parameters

  • destination
    Explicit fresh absolute directory beneath an existing non-linked parent.
  • apply
    False validates a non-mutating preview; true atomically creates the private destination.
  • cancellationToken
    Cancellation checked before creation and each initialization step.
  • beforeRegistryPublication
    Optional per-call interruption seam after marker publication; production omits it.
  • onDirectoryCreated
    Optional observation immediately after native root creation, including when later validation fails.
  • beforeDestinationInspection
    Optional race seam after retaining the parent and before inspecting the destination; production omits it.
  • beforeDestinationReopen
    Optional per-call race seam after the attributes probe and before reopening the destination; production omits it.

Returns

The normalized destination path. No history, registrations, pins or deletion authority are transferred.

Remarks

Existing destinations are always refused, including empty or valid stores. Creation uses the retained parent's no-replace primitive. Cancellation or failure preserves any created private directory and metadata for inspection; retry with a different fresh destination rather than adopting a partial result. This is the safe schema-v1 alternative when independent continuity cannot be established.

Method

Open

CoverageArtifactStore Open(string? overrideHome = null, TimeProvider? clock = null, Func<CoverageRunOutputLease, string>? observeIdentity = null)

Opens or creates the current user's private artifact domain.

Parameters

  • overrideHome
    Optional isolated domain root, primarily for explicit local configuration and tests.
  • clock
    Optional clock for deterministic timestamps and maintenance budgets.
  • observeIdentity
    Per-call marker comparison seam; omission observes the retained native directory. It never replaces live binding checks.

Exceptions

  • IOException
    The root is broad, linked, unsupported, or contains unknown store state.
  • InvalidDataException
    The marker, registry, or policy has an unsupported or invalid schema.
Method

OpenReadOnly

CoverageArtifactStore OpenReadOnly(string? overrideHome = null, TimeProvider? clock = null, Func<CoverageRunOutputLease, string>? observeIdentity = null)

Opens an existing private domain for status reads without creating or repairing any filesystem entry.

Parameters

  • overrideHome
    Optional isolated domain root used by explicit configuration and tests.
  • clock
    Optional clock retained for API symmetry; reads do not use it.
  • observeIdentity
    Per-call marker comparison seam; omission observes the retained native directory. Simulated observations are not native lifecycle evidence.

Returns

A read-only store; an absent domain is represented by an empty in-memory status view.

Method

RegisterAsync

Task RegisterAsync(CoverageArtifactCurrentRun run, CancellationToken cancellationToken)

Registers one producer-owned current output and inventory.

Parameters

  • run
    The explicit current run supplied by the producer.
  • cancellationToken
    The caller's cancellation token.
Method

SnapshotAsync

Task<CoverageArtifactRunManifest> SnapshotAsync(CoverageArtifactCurrentRun run, bool pin, bool automatic, CancellationToken cancellationToken, bool sourceLeaseHeld = false, CoverageArtifactWorkBudget? routineBudget = null)

Creates a complete, verified archive of the supplied registered current run.

Parameters

  • run
    The current output and explicit inventory to snapshot.
  • pin
    Whether to protect the resulting archive from automatic expiry.
  • automatic
    Whether automatic-work byte and time caps apply.
  • cancellationToken
    The caller's cancellation token.
  • sourceLeaseHeld
    Whether the caller already holds exclusive source-output authority.
  • routineBudget
    Optional invocation-wide cooperative budget shared with maintenance.

Returns

The complete manifest published in the archive.

Method

GetCurrentRun

CoverageArtifactCurrentRun? GetCurrentRun(string outputPath)

Returns the registered current run for the same physical output directory, if present.

Parameters

  • outputPath
    The output directory whose recorded physical identity is checked.
Method

HasVerifiedArchiveAsync

Task<bool> HasVerifiedArchiveAsync(string outputPath, CancellationToken token)

Checks whether a registered current output already has a complete, integrity-verified archive.

Parameters

  • outputPath
    Existing output whose current registration is inspected without adoption.
  • token
    Caller cancellation while verifying payloads.
Method

GetStatus

CoverageArtifactStoreStatus GetStatus()

Reads a bounded status snapshot without changing current outputs or archives.

Method

AcquireCandidateLease

CoverageArtifactOperationLease AcquireCandidateLease(string candidatePath, bool exclusive)

Acquires candidate authority outside a deletable Windows directory, using the private domain's fixed lock file.

Parameters

  • candidatePath
    An existing archive or stage already selected by the caller's ownership checks.
  • exclusive
    Whether the operation mutates the candidate.

Returns

A retained candidate lease; disposal never removes the domain lock file.

Method

MaintainAsync

Task<IReadOnlyList<string>> MaintainAsync(bool apply, CancellationToken cancellationToken, CoverageArtifactWorkBudget? routineBudget = null, Action<string>? onArchiveDeleted = null, CoverageArtifactOperationLease? heldSourceLease = null)

Applies or previews eligible archive expiry under the shared retention policy.

Parameters

  • routineBudget
    Optional invocation-wide maintenance budget; explicit maintenance has no deadline.
  • apply
    False returns candidates without deleting them.
  • cancellationToken
    The caller's cancellation token.
  • heldSourceLease
    Optional live exclusive source lease owned by the calling session; reused only for its matching physical output, never disposed by maintenance.
  • onArchiveDeleted
    Receives each run identifier immediately after physical deletion, even if later metadata persistence fails. The callback must not throw.

Remarks

Apply reconciles absent, unpinned historical archive registrations before selecting candidates. Reconciliation changes metadata only, preserves current/pinned entries and active snapshot reservations, and records an explicit missing-archive receipt without reporting a new physical deletion. Before deleting a candidate, apply verifies every stored and expanded payload length and hash under its exclusive candidate lease and the same cumulative work budget. Corruption preserves the archive.

Method

PinAsync

Task PinAsync(string runId, bool pin, CancellationToken cancellationToken)

Changes pin state for a verified archived run.

Parameters

  • runId
    The opaque N-format run identifier.
  • pin
    True to pin; false to permit normal expiry.
  • cancellationToken
    The caller's cancellation token.
Method

RestoreAsync

Task RestoreAsync(string runId, string freshOutputPath, CancellationToken cancellationToken)

Restores a verified archive into a fresh private output directory.

Parameters

  • runId
    The opaque N-format run identifier.
  • freshOutputPath
    A new destination path that must not already exist.
  • cancellationToken
    The caller's cancellation token.

Remarks

The destination is made absolute with Path.GetFullPath(string) and normalized with Path.TrimEndingDirectorySeparator(string) before checking existence or deriving its parent and final name. A trailing directory separator is accepted. The parent must already exist and pass safe traversal checks; an existing destination is never overwritten.

Method

Dispose

void Dispose()

Releases store resources.

Method

ReadMarker

StoreMarker? ReadMarker(CoverageRunOutputLease directory)

Reads bounded schema-v1 ownership metadata; missing is distinguished from malformed bytes.

Method

ValidateMarker

void ValidateMarker(StoreMarker marker, string identity)

Requires the complete native identity; schema-v1 contains no independent remount continuity proof.

Method

MetadataBytes

long MetadataBytes(CoverageRunOutputLease root)

Counts bounded domain metadata, including the non-authoritative warning and inspection observations.

Property

RootPath

string RootPath { get; } Source

Gets the canonical private domain root.

Property

Policy

CoverageArtifactPolicy Policy { get; } Source

Gets the fully validated effective retention policy.

Type

StoreRegistration

Source
Property

ArchivedAtUtc

DateTimeOffset? ArchivedAtUtc { get; init; } Source

Gets the verified archive publication time, independent of later current-output observations.

Type

CoverageArtifactRunManifest

Source

Describes the versioned metadata and integrity facts for one archived coverage run.

Remarks

This is bounded local storage metadata. It describes the bytes observed during the original run and is not an attestation that those bytes match any later source tree.

Property

SchemaVersion

int SchemaVersion { get; init; } Source

Gets the manifest schema version. Version 1 is the only supported version.

Property

RunId

string RunId { get; init; } Source

Gets the run identifier encoded as 32 hexadecimal GUID N-format characters.

Property

OutputIdentity

string OutputIdentity { get; init; } Source

Gets the native identity of the output directory that produced the run.

Property

RepositoryIdentity

string RepositoryIdentity { get; init; } Source

Gets the native identity of the repository or worktree containing the run.

Property

Version

string Version { get; init; } Source

Gets the producing AppSurface version.

Property

Outcome

string Outcome { get; init; } Source

Gets the producing run outcome.

Property

CreatedAtUtc

DateTimeOffset CreatedAtUtc { get; init; } Source

Gets the time the original coverage run was created.

Property

ArchivedAtUtc

DateTimeOffset ArchivedAtUtc { get; init; } Source

Gets the time this archive was completed.

Property

Provenance

CoverageArtifactProvenance? Provenance { get; init; } Source

Gets optional bounded Git and configuration fingerprints.

Property

Files

IReadOnlyList<CoverageArtifactFileEntry> Files { get; init; } Source

Gets the ordered file inventory and its verified compressed payload facts.

Property

Complete

bool Complete { get; init; } Source

Gets whether every payload and the manifest passed integrity verification.

Type

CoverageArtifactFileEntry

Source

Describes one archived file and the opaque payload that stores its gzip representation.

Parameters

  • Path
    The portable path relative to the original output root.
  • PayloadId
    An opaque eight-digit identifier used as the stored payload filename stem.
  • OriginalLength
    The verified original file length in bytes.
  • OriginalSha256
    The lowercase SHA-256 hash of the original bytes.
  • StoredLength
    The verified compressed payload length in bytes.
  • StoredSha256
    The lowercase SHA-256 hash of the compressed payload bytes.
  • Complete
    Whether this payload was fully written and round-trip verified.
Type

CoverageArtifactInventoryEntry

Source

Captures the expected path, length, and content hash observed by the archive inventory writer.

Parameters

  • Path
    The portable path relative to the source output root.
  • Length
    The expected source length in bytes.
  • Sha256
    The expected lowercase or uppercase SHA-256 hash of the source bytes.
Type

CoverageArtifactProvenance

Source

Contains optional bounded fingerprints that describe original-run provenance.

Parameters

  • GitRevisionFingerprint
    An optional fingerprint for the observed Git revision.
  • GitStateFingerprint
    An optional fingerprint for the observed clean, dirty, or unknown state.
  • ConfigurationFingerprint
    An optional fingerprint for effective coverage configuration.
Type

CoverageArtifactArchive

Source

Streams, verifies, and restores private gzip payloads for coverage-run archives.

Remarks

Staging writes only inside a caller-owned private staging directory and never removes source files. The manager remains responsible for atomic directory publication, locking, quotas, and cleanup.

Method

StageAsync

Task<CoverageArtifactRunManifest> StageAsync(string sourceRoot, string stageRoot, CoverageArtifactRunManifest manifestBase, IReadOnlyList<CoverageArtifactInventoryEntry> inventory, long maxOriginalBytes, long maxStoredBytes, TimeProvider clock, TimeSpan? budget, CancellationToken cancellationToken)

Creates and verifies a complete archive in an existing private staging directory.

Parameters

  • sourceRoot
    The output root containing the inventoried source files.
  • stageRoot
    An existing, empty, private directory owned by the artifact manager.
  • manifestBase
    Run metadata captured before archive staging.
  • inventory
    The explicit writer-owned source inventory with expected lengths and hashes.
  • maxOriginalBytes
    The strict aggregate uncompressed byte limit.
  • maxStoredBytes
    The strict aggregate compressed byte limit.
  • clock
    The clock used to enforce the cooperative time budget and archive timestamp.
  • budget
    An optional cooperative deadline measured from operation start.
  • cancellationToken
    A token whose cancellation is preserved.

Returns

The complete manifest after every stored payload has been verified by decompression.

Method

WriteManifest

void WriteManifest(Stream destination, CoverageArtifactRunManifest manifest)

Writes one complete version 1 manifest to a caller-owned stream under the JSON size limit.

Parameters

  • destination
    A writable stream positioned at the start of a new manifest.
  • manifest
    The complete run manifest to serialize.
Method

ReadManifest

CoverageArtifactRunManifest ReadManifest(Stream source)

Reads and validates one bounded version 1 manifest without disposing the input stream.

Parameters

  • source
    A readable stream positioned at the start of the manifest.

Returns

The validated complete archive manifest.

Method

RestorePayloadsAsync

Task RestorePayloadsAsync(string archiveRoot, string freshStageRoot, CoverageArtifactRunManifest manifest, long expandedLimit, TimeProvider clock, TimeSpan? budget, CancellationToken cancellationToken)

Restores all verified payloads into an existing, empty, private staging directory.

Parameters

  • archiveRoot
    A private archive directory containing payload files named by opaque IDs.
  • freshStageRoot
    A fresh, private destination stage that must remain unpublished.
  • manifest
    A complete validated version 1 manifest.
  • expandedLimit
    The strict aggregate expanded-byte limit.
  • clock
    The clock used to enforce the cooperative time budget.
  • budget
    An optional cooperative deadline measured from operation start.
  • cancellationToken
    A token whose cancellation is preserved.

Returns

A task that completes after all restored bytes pass length and SHA-256 verification.

Method

VerifyPayloadsAsync

Task VerifyPayloadsAsync(string archiveRoot, CoverageArtifactRunManifest manifest, CancellationToken token, CoverageArtifactWorkBudget? sharedBudget = null)

Verifies every stored and original payload fact without publishing extracted files.

Parameters

  • archiveRoot
    Private archive whose shared or exclusive candidate lease the caller holds.
  • manifest
    Completed bounded manifest.
  • token
    Caller cancellation token.
  • sharedBudget
    Optional cumulative maintenance allowance.
Type

CoverageArtifactInspectionCursorStore

Source

Persists bounded, non-authoritative directory cursors for incremental coverage inspection.

Method

Read

IReadOnlyList<string>? Read(CoverageArtifactStore? store, string scopeId, TimeProvider clock)

Reads the cursor for one scope without creating or modifying any store entry.

Parameters

  • store
    Existing private domain, or null when optional management is unavailable.
  • scopeId
    A 64-character hexadecimal repository observation fingerprint.
  • clock
    Clock used to expire observations after seven days.

Returns

Ordered pending directories, or null when no unexpired observation exists.

Remarks

Only observation hints are returned. Callers must revalidate every path and must not infer ownership or sum overlapping scans.

Method

Write

void Write(CoverageArtifactStore? store, string scopeId, IReadOnlyList<string> paths, TimeProvider clock)

Writes a bounded cursor for one scope into the existing store's private staging tree.

Parameters

  • store
    Existing private domain, or null to skip persistence.
  • scopeId
    A 64-character hexadecimal repository observation fingerprint.
  • paths
    Up to 128 portable relative directories, in next-scan order.
  • clock
    Clock used for observation timestamps and expiry.

Remarks

State is private and atomically replaced. At most 32 scopes and 64 KiB are retained; older scopes and trailing paths are dropped before publication.

Type

CoverageArtifactNativeLockResult

Source

Reports whether one native operation-lock request acquired the lock and its native error code.

Parameters

  • Acquired
    Whether the lock request succeeded.
  • ErrorCode
    The native error captured immediately after a failed request; zero on success.
Type

CoverageArtifactOperationLeaseOptions

Source

Provides per-acquisition observations for coverage artifact operation-lock orchestration.

Remarks

Unset delegates use the production filesystem and native calls. Setting IsWindows selects only the operation-lock branch: directory acquisition and physical identity inspection always use the real host OS. To exercise the Windows branch on another OS, callers must supply a real open lock-file handle through OpenWindowsLock and fake TryWindowsLock and VerifyWindowsLockBinding delegates. Disposing that handle is the Windows lock-release operation. These delegates verify orchestration only; they do not emulate or validate LockFileEx or Windows path binding. Native acceptance must be verified separately on the target OS. Instances are passed to one CoverageArtifactOperationLease.Acquire(string, bool, CoverageArtifactOperationLeaseOptions?, string?) call and are never stored globally.

Property

IsWindows

bool? IsWindows { get; init; } Source

Gets the optional lock-platform selector; null uses the real host OS.

Property

UnixFlock

Func<int, int, CoverageArtifactNativeLockResult>? UnixFlock { get; init; } Source

Gets an optional Unix flock operation receiving the retained directory descriptor and flags.

Remarks

It receives lock flags 5 for shared and 6 for exclusive acquisition, and 8 for unlock.

Property

OpenWindowsLock

Func<CoverageRunOutputLease, SafeFileHandle>? OpenWindowsLock { get; init; } Source

Gets an optional Windows lock-file opener for the retained directory.

Remarks

The returned handle is owned by the operation lease and is disposed on failure or lease disposal.

Property

TryWindowsLock

Func<SafeFileHandle, uint, CoverageArtifactNativeLockResult>? TryWindowsLock { get; init; } Source

Gets an optional Windows lock request receiving the owned file handle and LockFileEx flags.

Remarks

It receives flags 1 for shared and 3 for exclusive nonblocking acquisition.

Property

VerifyUnixBinding

Action<CoverageRunOutputLease>? VerifyUnixBinding { get; init; } Source

Gets an optional verifier for the retained Unix directory binding.

Remarks

It runs after successful acquisition and on each live lease binding verification.

Property

VerifyWindowsLockBinding

Action<CoverageRunOutputLease, SafeFileHandle, string>? VerifyWindowsLockBinding { get; init; } Source

Gets an optional verifier for the retained Windows lock-file binding.

Remarks

It receives the retained directory, lock handle, and identity captured when the lease was constructed. The default verifier checks the current named lock file against that identity using the host's native APIs.

Type

CoverageArtifactOperationLease

Source

Holds a fail-fast cooperative shared or exclusive lease on one physical output.

Remarks

Unix uses nonblocking flock on the retained directory object; Windows uses LockFileEx on a persistent, no-follow regular lock file. Older binaries and external readers do not participate in this protocol. Multiple-output callers must acquire their strongest modes in deterministic physical-identity order.

Method

Acquire

CoverageArtifactOperationLease Acquire(string existingDirectory, bool exclusive, CoverageArtifactOperationLeaseOptions? options = null, string? windowsLockRoot = null)

Acquires one nonblocking strongest-mode lease without performing output cleanup.

Parameters

  • existingDirectory
    An existing directory validated without following ancestor links.
  • exclusive
    Whether the operation mutates this physical output.
  • options
    Optional per-call lock and binding observations; omitted in production.
  • windowsLockRoot
    Optional private domain holding the fixed Windows lock file for a deletable archive or stage. Locks use a deterministic physical-identity byte range; Unix still locks the candidate directory.

Returns

A disposable lease; contention fails with ASCOV202 before caller mutation.

Remarks

The directory is always opened and validated with the actual host's filesystem APIs. Supplying options can substitute only the lock orchestration observations for this call. A forced Windows branch on a non-Windows host requires an injected lock-file opener, lock result, and binding observer, so it cannot accidentally call Windows native exports on that host.

Method

VerifyBinding

void VerifyBinding()

Rejects a changed physical output binding before a participating operation publishes.

Method

Dispose

void Dispose()

Releases native authority once; lock files remain persistent and are never removed to force admission.

Method

CandidateLockOffset

ulong CandidateLockOffset(string physicalIdentity)

Maps a physical candidate identity to one nonzero Windows byte-range offset without growing the lock file.

Remarks

A hash collision only rejects concurrent work; it cannot admit conflicting work. The fixed file is distinct from the root metadata lock.

Property

PhysicalIdentity

string PhysicalIdentity { get; } Source

Gets the physical volume/object identity used to order compatible operations.

Property

IsExclusive

bool IsExclusive { get; } Source

Gets whether this retained lease authorizes mutation and recovery of its physical output.

Enum

CoverageArtifactGitStateProbeOutcome

Source

Describes whether the bounded Git-state probe produced a fingerprint or a safe unknown.

Enum

CoverageArtifactStoreFailureKind

Source

Trusted failure categories for bounded store-open diagnostics; these grant no ownership.