AppSurface Search
Section API Reference
API Reference Language: C# Component: Evidence Audience: developer

Contracts

Type

NormalizedDiffPath

Source

Describes a normalized changed path used for deterministic policy resolution.

Parameters

  • PathA repository-relative path with forward-slash separators.
  • KindThe source-control change kind, such as added, modified, deleted, or renamed.
  • PreviousPathThe previous normalized path for a rename; otherwise null.
Type

EvidenceArtifactSlot

Source

Declares one artifact slot that a producer is allowed to return.

Parameters

  • LogicalNameStable logical artifact name.
  • RelativeRootNormalized artifact-root-relative directory permitted for this slot.
  • MediaTypeExpected media type.
  • RequiredWhether a missing artifact invalidates the producer result.
  • MaximumBytesMaximum allowed artifact length.
Type

EvidenceArtifactResult

Source

Captures bounded metadata for one declared artifact without serializing its raw content.

Parameters

  • LogicalNameDeclared artifact slot identifier.
  • RelativePathNormalized path beneath the evidence artifact root.
  • MediaTypeDeclared media type.
  • LengthBytesWritten artifact length.
  • Sha256Lower-case SHA-256 digest of the written bytes.
Type

EvidenceCoverageGateRequirements

Source

Binds a coverage producer's declared assertion to the existing AppSurface coverage gate thresholds.

Parameters

  • MinLinePercentMinimum overall line coverage percentage.
  • MinBranchPercentMinimum overall branch coverage percentage.
  • MinPatchLinePercentOptional minimum changed-line coverage percentage.
  • MinPatchBranchPercentOptional minimum changed-branch coverage percentage.
  • PatchLineModeChanged-line calculation mode: measurable or codecov.
  • TolerancePercentConfigured coverage gate tolerance percentage.
Type

EvidenceProducerDeclaration

Source

Declares a producer selected by an evidence profile.

Parameters

  • IdStable producer identifier.
  • KindRegistered producer kind, such as coverage or browser-e2e.
  • VersionProducer implementation semantic version.
  • RequiredResourcesResource identifiers that must be ready before execution.
  • AssertionIdsAssertion identifiers that this producer may close.
  • ArtifactSlotsClosed artifact declarations for this producer.
  • TimeoutSecondsPositive producer deadline in seconds.
  • CoverageGateExplicit coverage gate requirements when this producer closes a coverage assertion.
Type

EvidenceResourceDeclaration

Source

Declares an evidence resource required by a profile.

Parameters

  • IdStable resource identifier.
  • ReadinessDeclared readiness mode, such as aspire_health or completion.
  • DeadlineSecondsPositive readiness deadline in seconds.
  • RequiresResource identifiers that must be ready first.
Type

EvidenceResourceResult

Source

Captures bounded terminal readiness metadata for one declared resource.

Parameters

  • ResourceIdDeclared resource identifier.
  • OutcomeTerminal readiness outcome.
  • ElapsedMillisecondsTime spent waiting for the resource.
  • DiagnosticSecret-safe readiness diagnostic.
Type

EvidenceObligation

Source

Defines a changed-risk requirement that must be closed before a claim is complete.

Parameters

  • IdStable obligation identifier.
  • RiskClassConsumer-defined risk class.
  • RationaleHuman explanation for why the obligation was selected.
  • RequiredProducerIdsEvery producer that must pass for closure.
  • RequiredAssertionIdThe assertion that confirms closure.
Type

EvidenceProfile

Source

Defines a closed profile of resources, producers, and obligations.

Parameters

  • IdStable profile identifier.
  • ScopeTargeted or release evidence breadth.
  • ResourcesResources required by the profile.
  • ProducersRegistered producers selected by the profile.
  • ObligationsRisk obligations selected by the profile.
Type

EvidenceProfileLimits

Source

Defines the shared v1 limits for one EvidenceHost profile declaration.

Type

EvidencePolicyRule

Source

Maps exact paths or segment globs to a single named evidence profile.

Parameters

  • IdStable rule identifier.
  • PatternExact repository path or segment glob.
  • ProfileIdProfile selected when the rule matches.
  • PrecedenceExplicit tie breaker for equal-specificity patterns.
Type

EvidencePolicy

Source

Represents a versioned, checked-in evidence policy.

Parameters

  • IdStable policy identifier.
  • VersionConsumer-controlled policy version.
  • ConservativeProfileIdProfile selected when a changed path has no direct match.
  • ProfilesClosed set of selectable profiles.
  • RulesPath-selection rules.
Type

EvidencePlan

Source

Captures the immutable result of policy resolution before resource or producer execution.

Parameters

  • ContractVersionEvidence contract version.
  • PolicyIdResolved policy identifier.
  • PolicyDigestSHA-256 digest of canonical policy bytes.
  • DiffDigestSHA-256 digest of canonical normalized diff bytes.
  • ProfileSelected closed profile.
  • ChangedPathsNormalized paths used during selection.
  • MatchedRuleIdsRules that explain selection.
  • PlanDigestSHA-256 digest of canonical plan bytes excluding this digest field.
  • PolicySnapshotCanonical checked-in policy snapshot used for resolution and later verification.
Type

EvidenceProducerResult

Source

Captures a bounded producer result returned to the EvidenceHost.

Parameters

  • ProducerIdProducer that emitted the result.
  • OutcomeTerminal producer outcome.
  • SatisfiedAssertionIdsAssertion identifiers returned by the producer.
  • DiagnosticSecret-safe human diagnostic; never include raw logs or values.
  • ArtifactsBounded metadata for artifacts written through the declared artifact writer.
  • ElapsedMillisecondsMeasured producer execution time.
Type

EvidenceExecutionMetrics

Source

Captures bounded, secret-free lifecycle timing and cleanup status for one evidence execution.

Parameters

  • PlanningMillisecondsTime spent resolving the policy and plan.
  • ResourceReadinessMillisecondsCumulative time spent awaiting declared resources.
  • ProducerMillisecondsCumulative producer execution time.
  • CleanupMillisecondsTime spent disposing evidence-owned registrations.
  • TotalMillisecondsTotal measured execution duration.
  • CleanupCompletedWhether owned cleanup completed without a terminal failure.
  • CleanupDiagnosticSecret-safe cleanup diagnostic when cleanup did not complete.
Type

EvidenceManifest

Source

Captures the immutable claim and execution result of an evidence run.

Parameters

  • ContractVersionEvidence contract version.
  • PlanDigestDigest of the resolved plan.
  • ExecutionVerdictWhether declared execution requirements completed.
  • ClaimKindClaim emitted by this run.
  • EligibilityDownstream consumers permitted to use the claim.
  • EnvelopeStatusConstrained CI-envelope status; it is not an implied runtime sandbox attestation.
  • ResourceResultsBounded readiness outcomes for selected resources.
  • SelectedObligationIdsObligations selected by the plan.
  • ClosedObligationIdsObligations closed by returned assertions.
  • UnmediatedObligationIdsSelected obligations that remain open.
  • ProducerResultsBounded producer terminal results.
  • MetricsSecret-free lifecycle timing and cleanup state.
  • ManifestDigestSHA-256 digest of canonical manifest bytes excluding this digest field.
Type

EvidenceProducerContext

Source

Supplies the immutable execution context exposed to a registered evidence producer.

Parameters

  • PlanResolved evidence plan.
  • ProducerThe producer declaration being executed.
  • TimeProviderClock seam used for deadlines and deterministic tests.
  • ArtifactsBounded writer for declared artifact slots. It exposes no raw host path.
Type

IEvidenceProducer

Source

Represents an explicitly registered typed evidence producer.

Method

ProduceAsync

ValueTask<EvidenceProducerResult> ProduceAsync(EvidenceProducerContext context, CancellationToken cancellationToken) Source

Produces bounded assertions and diagnostics for one resolved declaration.

Parameters

  • contextImmutable plan and producer context.
  • cancellationTokenCancellation requested by the EvidenceHost lifecycle.

Returns

A terminal producer result.

Property

Id

string Id { get; } Source

Gets the stable declaration identifier handled by this producer.

Type

EvidenceArtifactWriter

Source

Writes only declared producer artifacts beneath a consumer-selected evidence root.

Method

WriteAsync

ValueTask<EvidenceArtifactResult> WriteAsync(string logicalName, string relativePath, ReadOnlyMemory<byte> contents, CancellationToken cancellationToken = default) Source

Writes one declared artifact and returns only its bounded metadata.

Parameters

  • logicalNameDeclared artifact slot identifier.
  • relativePathNormalized artifact-root-relative destination path.
  • contentsArtifact bytes to write.
  • cancellationTokenCancellation requested by the EvidenceHost lifecycle.

Returns

Hash and metadata for the written artifact.

Method

VerifyWrittenArtifactsAsync

Task<bool> VerifyWrittenArtifactsAsync(CancellationToken cancellationToken = default) Source

Revalidates the final on-disk bytes for every artifact written through this writer.

Parameters

  • cancellationTokenCancellation requested by the EvidenceHost lifecycle.

Returns

true when every artifact still has its declared length and digest.

Property

WrittenArtifacts

IReadOnlyList<EvidenceArtifactResult> WrittenArtifacts { get; } Source

Gets completed artifact metadata emitted through this writer in ordinal logical-name order.

Type

EvidenceArtifactValidation

Source

Validates declared evidence artifact metadata and containment without reading raw artifact contents into manifests.

Method

AreValid

bool AreValid(EvidenceProducerDeclaration producer, IReadOnlyList<EvidenceArtifactResult>? artifacts) Source

Validates producer artifact metadata against its closed declaration set.

Parameters

  • producerProducer declaration that owns the slots.
  • artifactsProducer-returned artifact metadata.

Returns

true when every artifact is declared, bounded, and valid.

Method

NormalizeRelativePath

string NormalizeRelativePath(string relativePath) Source

Normalizes an artifact-root-relative path or throws when it escapes the artifact boundary.

Parameters

  • relativePathArtifact-root-relative candidate path.

Returns

Normalized forward-slash path.

Method

ValidatePathForSlot

void ValidatePathForSlot(EvidenceArtifactSlot slot, string relativePath) Source

Validates that an artifact path remains beneath the declared slot root.

Parameters

  • slotDeclared artifact slot.
  • relativePathArtifact-root-relative candidate path.
Method

GetContainedPath

string GetContainedPath(string rootPath, string relativePath) Source

Returns an absolute path contained beneath a controlled artifact root.

Parameters

  • rootPathControlled artifact root.
  • relativePathValidated root-relative artifact path.

Returns

Contained absolute destination path.

Type

EvidenceCanonicalJson

Source

Serializes contract objects deterministically for evidence identity and verification.

Method

Serialize

byte[] Serialize<TValue>(TValue value) Source

Serializes a value as canonical UTF-8 JSON with ordinal object-property order.

Type Parameters

  • TValueValue type to serialize.

Parameters

  • valueValue to serialize.

Returns

Canonical UTF-8 JSON bytes.

Method

Deserialize

TValue Deserialize<TValue>(ReadOnlySpan<byte> utf8Json) Source

Deserializes a JSON document using the contract serializer options.

Type Parameters

  • TValueValue type to deserialize.

Parameters

  • utf8JsonJSON bytes.

Returns

The deserialized value.

Type

EvidenceManifestBuilder

Source

Builds and verifies manifest claims from a resolved plan and bounded producer results.

Method

Build

EvidenceManifest Build(EvidencePlan plan, IReadOnlyList<EvidenceProducerResult> producerResults, bool observationOnly = false, EvidenceEnvelopeStatus envelopeStatus = EvidenceEnvelopeStatus.NotRequired, IReadOnlyList<EvidenceResourceResult>? resourceResults = null, EvidenceExecutionMetrics? metrics = null) Source

Produces a manifest and closes obligations only when every declared producer and assertion requirement passed.

Parameters

  • planResolved plan.
  • producerResultsTerminal results returned by selected producers.
  • observationOnlyWhether the caller intentionally requested a non-gate observation.
  • envelopeStatusConstrained CI-envelope status bound to the manifest.
  • resourceResultsTerminal readiness results for selected resources.
  • metricsSecret-free lifecycle timing and cleanup state.

Returns

A digest-bound manifest.

Method

Verify

bool Verify(EvidencePlan plan, EvidenceManifest manifest) Source

Validates that a manifest still binds to a supplied plan and canonical manifest content. This detects inconsistent or edited claim fields, but does not authenticate the origin of a plan or manifest. Gates must obtain both values through a trusted CI channel.

Parameters

  • planPlan expected by the verifier.
  • manifestManifest to verify.

Returns

true when the binding and digest are valid.

Type

EvidenceDigest

Source

Computes SHA-256 evidence identities from canonical bytes.

Method

Sha256

string Sha256(ReadOnlySpan<byte> bytes) Source

Computes a lower-case hexadecimal SHA-256 digest.

Parameters

  • bytesBytes to digest.

Returns

The digest.

Method

CanonicalSha256

string CanonicalSha256<TValue>(TValue value) Source

Computes a canonical-object digest.

Type Parameters

  • TValueValue type to digest.

Parameters

  • valueValue to serialize and digest.

Returns

The canonical SHA-256 digest.

Enum

EvidenceProfileScope

Source

Defines the scope selected by a versioned evidence policy.

Enum

EvidenceExecutionVerdict

Source

Describes whether a resolved evidence execution satisfied its declared contract.

Enum

EvidenceClaimKind

Source

Defines the machine-readable claim that a manifest may make.

Enum

EvidenceClaimEligibility

Source

Defines the allowed downstream consumers of an evidence claim.

Enum

EvidenceEnvelopeStatus

Source

Describes the constrained status of the CI execution envelope bound to an evidence run.

Enum

EvidenceProducerOutcome

Source

Defines a terminal producer outcome.

Enum

EvidenceResourceOutcome

Source

Defines the terminal readiness outcome for one declared evidence resource.