AppSurface Search
API Reference

PackageIndex

Type

DurableTemplateSampleReplacement

Source

Applies the documented Work-only sample replacement to one generated FirstDurableWorker copy.

Remarks

This proof is deliberately fixed to the reviewed sample and generated project name. It validates all four expected Work source files before writing any of them, then changes only the definition, executor, registration, and producer. The template source and the installed proof consumer remain untouched.

Method

Apply

IReadOnlyList<string> Apply(string generatedRoot, string projectName)

Replaces the sample only after all expected generated Work files match the reviewed template shape.

Parameters

  • generatedRoot
    Root directory of the separate generated consumer, named by projectName .
  • projectName
    The exact generated project name, FirstDurableWorker .

Returns

The four changed slash-separated paths, relative to generatedRoot .

Exceptions

  • PackageIndexException
    The root, project name, links, encoding, or sample shape is invalid.

Remarks

The input/result public type names and their Value properties remain compatible with first-Work tests.

Method

ComputeContentSha256

string ComputeContentSha256(string generatedRoot, IReadOnlyList<string> relativePaths)

Computes a stable hash over only the approved changed Work files.

Parameters

  • generatedRoot
    Root of the generated consumer.
  • relativePaths
    Changed relative paths returned by Apply .

Returns

Lowercase SHA-256 over ordinal-sorted path/byte pairs.

Exceptions

  • PackageIndexException
    The root or path inventory is outside the approved Work shape.
Type

TailwindCommandOptions

Source

Tailwind-specific command inputs, separated from established PackageIndex option parsing.

Type

CloudTasksPackageConsumerProof

Source

Proves the packed Cloud Tasks API, invalid-token no-I/O behavior, and neutral Durable graph isolation.

Method

ExtractBaselineAsync

Task ExtractBaselineAsync(string repositoryRoot, string target, string commit, CancellationToken token, ICommandRunner? runner = null)

Extracts the selected source snapshot through the shared bounded, cancellation-cleaned process runner.

Parameters

  • repositoryRoot
    Repository checkout containing the selected commit object.
  • target
    Destination directory for the archived source tree.
  • commit
    Canonical 40-character Git commit SHA selected by the proof mode.
  • token
    Cancellation token forwarded to archive and extraction commands.
  • runner
    Optional command runner seam; production uses the bounded process runner.
Method

AssertNeutralPackageContracts

void AssertNeutralPackageContracts(IReadOnlyList<CloudTasksPackageFileIdentity> identities)

Preserves packed contracts and library entry sets after the required unchanged-source proof.

Type

CloudTasksPackageConsumerProofRequest

Source

Inputs for validating a packed Cloud Tasks consumer and its paired neutral package graphs.

Parameters

  • RepositoryRoot
    Candidate source checkout root.
  • ArtifactsDirectory
    Directory containing the exact locally validated package archives.
  • PackageVersion
    Coordinated package version used by the validated artifacts and isolated consumers.
  • Source
    Configured package source for consumer restores.
  • SourceCommit
    Optional canonical candidate commit SHA; omitted resolves checked-out HEAD.
  • BaselineRef
    Optional fetched historical target ref; the unique merge-base with the candidate commit is required. Omitted uses the candidate source snapshot.
Type

CloudTasksPackageConsumerProofReport

Source

Evidence generated by the paired Cloud Tasks package consumer proof.

Parameters

  • CloudTasksPackageSha512
    Validated Cloud Tasks archive hash.
  • BaselineCommit
    Selected candidate snapshot or unique historical merge-base commit.
  • BaselineMode
    Either candidate-source or historical-acceptance .
  • BaselineAssetsPath
    Isolated restore assets path for the baseline neutral consumer.
  • CandidateAssetsPath
    Isolated restore assets path for the candidate neutral consumer.
  • BaselineGraph
    Resolved baseline neutral package graph.
  • CandidateGraph
    Resolved candidate neutral package graph.
  • CloudTasksGraph
    Resolved packed Cloud Tasks consumer graph.
  • NeutralPackageFiles
    Retained baseline and candidate archive/library hashes and packed contracts.
  • NeutralSourceSha256
    Raw source/build-input hashes for both sides of source parity.
  • ReportPath
    Path where the human-readable proof report was written.
Type

DurableTemplateStaging

Source

Creates an owned candidate copy of the standalone starter before template packing.

Remarks

Authored C# is copied unchanged. Only direct coordinated package-reference versions and the explicit install-command version in the two first-use documents are stamped. The native template engine remains responsible for name expansion. Staging is release preparation, never an install-time package selector or a source checkout mutation.

Method

Stage

string Stage(string source, string destination, string version)

Copies reviewed content into a previously absent owned directory and stamps its candidate package graph.

Parameters

  • source
    Maintained content directory; all entries must be regular files/directories.
  • destination
    Previously absent candidate directory; callers own its lifetime.
  • version
    Exact release workflow version, without build metadata.

Returns

Absolute candidate directory suitable for the pack project's TemplateContentRoot property.

Exceptions

  • PackageIndexException
    Unsafe source, unexpected graph, or invalid candidate version.
Method

EnumerateContent

IEnumerable<string> EnumerateContent(string root)

Enumerates maintained regular files, excluding only ordinary generated build and test output.

Parameters

  • root
    Content root.

Returns

Files in deterministic relative-path order.

Method

RequireRegularPath

void RequireRegularPath(string path)

Rejects linked/reparse components before proof IO or cleanup.

Parameters

  • path
    Absolute or relative file/directory path; existing ancestors are inspected.

Remarks

Absent final components are permitted; an existing ancestor must never redirect ownership.

Type

ICommandRunner

Source

Runs external commands for repository validation workflows.

Method

RunAsync

Task<CommandRunResult> RunAsync(CommandRunRequest request, CancellationToken cancellationToken)

Runs the requested command and returns captured output when it exits successfully.

Parameters

  • request
    Command request with process, timeout, and user-facing error context.
  • cancellationToken
    Cancellation token used while waiting for command completion.

Returns

Captured process output.

Exceptions

  • PackageIndexException
    Thrown when the process fails to start, times out, or exits unsuccessfully. Nonzero-exit errors include stderr and, when requested, a bounded tail of stdout.
Type

CommandRunRequest

Source

Describes one external command invocation and the language to use when it fails.

Parameters

  • FileName
    Executable name or path.
  • Arguments
    Command-line arguments supplied without shell interpolation.
  • WorkingDirectory
    Working directory for the process.
  • OperationName
    Human-readable operation name, such as dotnet pack .
  • Subject
    Repository item being processed, such as a project path.
  • FailureVerb
    Verb phrase used in nonzero exit messages, such as pack or evaluate .
  • TimeoutDescription
    Gerund phrase used in timeout messages, such as packing .
  • TimeoutMilliseconds
    Timeout applied to the process wait.
  • Environment
    Optional environment variable overrides.
  • IncludeStandardOutputOnFailure
    Whether to include the final 16,384 characters of stdout in a nonzero-exit error. Use only for commands whose output is safe to log.
Type

CommandRunResult

Source

Captured stdout and stderr from a successful command.

Parameters

  • StandardOutput
    Captured standard output.
  • StandardError
    Captured standard error.
Type

ProcessCommandRunner

Source

Process-backed command runner with timeout and failure cleanup.

Type

StableDocsDependencyContract

Source

Defines the exact parser and sanitizer identities approved for stable AppSurface Docs packages.

Remarks

This is the single source of truth for the stable-exit package contract tracked by issue #682. Package archive validation, isolated consumer graph verification, and generated proof guidance all consume these identities so a future dependency update cannot change one proof surface without changing the others.

Method

ExactVersionRange

string ExactVersionRange(StableDocsPackageDependency dependency)

Gets the exact NuGet dependency declaration required for the supplied stable dependency.

Parameters

  • dependency
    Approved parser or sanitizer dependency.

Returns

An exact bracketed NuGet version range.

Property

Dependencies

IReadOnlyList<StableDocsPackageDependency> Dependencies { get; } Source

Gets the approved parser and sanitizer package identities in reader-facing order.

Property

MarkdownDependencyList

string MarkdownDependencyList { get; } Source

Gets the Markdown-formatted dependency list used in maintainer guidance.

Property

PlainTextDependencyList

string PlainTextDependencyList { get; } Source

Gets a plain-text dependency list used in actionable diagnostics.

Type

StableDocsPackageDependency

Source

One approved stable Docs parser or sanitizer dependency identity.

Parameters

  • Id
    NuGet package id.
  • Version
    Exact resolved stable version.
Type

TailwindConsumerLock

Source

Materializes the reviewed net10.0 native-consumer NuGet lock before restore. The checked-in template fixes every third-party entry, including its version, hash, and dependencies. Only producer-bound first-party versions and archive hashes may change for a release candidate.

Method

Materialize

byte[] Materialize(string templatePath, string outputPath, IReadOnlyList<TailwindSubjectPackage> packages)

Write a candidate lock from the reviewed template and exact producer package identities.

Exceptions

  • PackageIndexException
    The template, candidate closure, or output is unsafe or inconsistent.
Method

RequireUnchanged

void RequireUnchanged(string path, byte[] expected)

Reject a lock rewritten, removed, or linked by either restore before it becomes host evidence.

Type

PackageArtifactValidator

Source

Validates package artifacts against the resolved publish plan.

Method

Validate

PackageArtifactValidationReport Validate(PackagePublishPlan plan, string artifactsDirectory, string packageVersion, string? repositoryRoot = null, PackagePayloadInventory? payloadInventory = null)

Validates the package output directory and returns a markdown-ready report.

Parameters

  • plan
    Resolved package publish plan.
  • artifactsDirectory
    Directory containing produced .nupkg files.
  • packageVersion
    Exact package version expected in every artifact.
  • repositoryRoot
    Optional repository root used to resolve source-path and version-source evidence when payload inventory validation is enabled.
  • payloadInventory
    Optional redistributed payload inventory to validate against the produced package artifacts.

Returns

A validation report for the inspected artifacts.

Method

ReadPackageEntryBytes

byte[] ReadPackageEntryBytes(string packagePath, string entryPath, string packageId)

Reads the bytes of a required package archive entry.

Parameters

  • packagePath
    Path to the package archive.
  • entryPath
    Repository-style path of the required archive entry.
  • packageId
    Package identifier used in a validation failure message.

Returns

The archive entry bytes.

Exceptions

  • PackageIndexException
    Thrown when the archive does not contain the required entry or its uncompressed contents exceed the validation limit.
Type

PackageArtifactReportRenderer

Source

Renders package artifact validation results for workflow artifacts.

Method

RenderMarkdown

string RenderMarkdown(PackageArtifactValidationReport report, CoverageCliConsumerProofReport? coverageProofReport = null, DocsPackageConsumerProofReport? docsProofReport = null)

Renders the validation report as markdown.

Parameters

  • report
    Validation report to render.
  • coverageProofReport
    Optional packaged coverage CLI proof details to append.
  • docsProofReport
    Optional packed Docs consumer proof details to append.

Returns

Markdown report content.

Type

PackageVersionValidator

Source

Ensures package versions used by release workflows are safe for NuGet identity.

Method

RequirePrerelease

void RequirePrerelease(string packageVersion)

Validates that the package version is a prerelease SemVer identity without build metadata.

Parameters

  • packageVersion
    Package version to validate.
Method

Require

void Require(string packageVersion, PackageVersionPolicy policy)

Validates a package version against the requested release classification policy.

Parameters

  • packageVersion
    Package version to validate.
  • policy
    Version policy required by the calling workflow.
Type

PackageArtifactValidationReport

Source

Result of a successful package artifact validation run.

Parameters

  • PackageVersion
    Exact package version inspected.
  • Entries
    Validated package report rows.
Type

PackageArtifactValidationReportEntry

Source

One validated package row in the artifact report.

Parameters

  • PackageId
    Validated package id.
  • ProjectPath
    Project that produced the package.
  • Decision
    Publish decision from the manifest.
  • ExpectedDependencyPackageIds
    Expected same-version package dependency ids.
  • ArtifactPath
    Validated .nupkg artifact path.
  • IsTool
    Whether the package is a .NET tool package.
  • ToolCommandName
    Validated command shim token from tool_command_name . It is empty for non-tool packages and required for tool packages so artifact reports show the exact command that publish smoke tests execute.
  • PayloadResults
    Redistributed package payload evidence rows validated for this package.
  • SuspiciousPayloadCount
    Number of suspicious package entries found in this artifact.
  • CoveredSuspiciousPayloadCount
    Number of suspicious package entries covered by notice or audit evidence.
Type

PackagePayloadValidationResult

Source

One redistributed package payload evidence row rendered into the artifact validation report.

Parameters

  • PackageId
    Package id whose artifact carried or embedded the payload evidence.
  • RecordId
    Inventory record id from packages/third-party-payloads.yml .
  • ComponentOrRule
    Third-party component name or audit rule shown to release reviewers.
  • EvidenceKind
    Evidence type, such as notice or generated_first_party .
  • Status
    Validation status rendered for release evidence.
  • PayloadEntries
    Package entries covered by this record.
  • NoticePaths
    Package notice paths checked by this record.
  • VersionSource
    Repository path or audit source that anchors the version/evidence.
Type

InspectedPackage

Source

Metadata and payload facts inspected from one NuGet package artifact.

Parameters

  • PackagePath
    Absolute or caller-supplied path to the inspected .nupkg file.
  • PackageId
    Nuspec package id. Expected to be non-empty after inspection.
  • PackageVersion
    Nuspec package version. Expected to be non-empty after inspection.
  • Authors
    Nuspec authors metadata, or null when absent.
  • Description
    Nuspec description metadata, or null when absent.
  • License
    Nuspec license expression or value, or null when absent.
  • ProjectUrl
    Nuspec project URL, or null when absent.
  • RepositoryUrl
    Nuspec repository URL, or null when absent.
  • Tags
    Nuspec package tags, or null when absent.
  • Readme
    Nuspec README path, or null when absent.
  • PackageTypes
    Declared nuspec package type names such as DotnetTool .
  • Dependencies
    Dependency ids mapped to all distinct nuspec versions observed across dependency groups.
  • DependencyContainers
    Raw nuspec dependency containers retained in document order for package-specific validation.
  • HasMixedRootAndGroups
    Whether the nuspec declares both root dependencies and target-framework groups.
  • EntryPaths
    Normalized archive entry paths contained in the package.
  • FirstPartyAssemblyVersions
    First-party implementation assemblies and their informational versions.
  • ToolCommandNames
    Command names declared by any DotnetToolSettings.xml files.
  • ToolSettingsFiles
    Tool command settings files with their package entry paths and declared commands.
Type

InspectedDependencyContainer

Source

One dependency container preserved from a package nuspec.

Parameters

  • Label
    Deterministic label used in diagnostics.
  • TargetFramework
    Raw target framework value for a group, or null for root dependencies.
  • IsGroup
    Whether this container originated from a nuspec group element.
  • Dependencies
    Raw dependency occurrences in source order.
Type

InspectedDependency

Source

One raw dependency occurrence preserved from a package nuspec.

Parameters

  • Id
    Raw dependency id, or null when omitted.
  • Version
    Raw dependency version, or null when omitted.
Type

DependencyContainerInspection

Source

Dependency-container facts collected from a package nuspec.

Parameters

  • Containers
    Containers in declaration order.
  • HasMixedRootAndGroups
    Whether root dependencies and groups coexist.
Type

StableDocsDependencyViolation

Source

One stable Docs dependency-contract violation.

Parameters

  • ContainerLabel
    Dependency container label.
  • DependencyId
    Required dependency or metadata field.
  • Observed
    Observed artifact value.
  • Expected
    Exact required value.
Type

InspectedToolSettingsFile

Source

Tool command declarations found in one packaged DotnetToolSettings.xml file.

Parameters

  • EntryPath
    Normalized package entry path for the settings file.
  • CommandNames
    Distinct command names declared in the settings file.
Type

InspectedAssemblyVersion

Source

Informational version metadata read from a first-party assembly inside a package artifact.

Parameters

  • EntryPath
    Archive path for the inspected assembly entry.
  • InformationalVersion
    Assembly informational version value read from metadata.
Type

CliWrapCommandRunner

Source

Runs external commands through CliWrap for protected package publishing and smoke-install workflows.

Type

IExternalCommandRunner

Source

External command runner used by publish and smoke workflows when non-zero exit codes are meaningful results.

Method

RunAsync

Task<ExternalCommandResult> RunAsync(ExternalCommandRequest request, CancellationToken cancellationToken)

Runs a command and returns stdout, stderr, and exit code without throwing for non-zero exits.

Parameters

  • request
    Command request.
  • cancellationToken
    Cancellation token.

Returns

Captured command result.

Type

ExternalCommandRequest

Source

Command invocation for CliWrap-backed release automation.

Parameters

  • FileName
    Executable to launch without a shell.
  • Arguments
    Argument tokens passed without shell expansion.
  • WorkingDirectory
    Existing working directory for the child process.
  • OperationName
    Safe operation label used in diagnostics.
  • TimeoutDescription
    Safe description of the bounded operation.
  • TimeoutMilliseconds
    Positive child-process timeout.
  • Environment
    Optional environment overrides; do not serialize secret values in diagnostics.
  • CapturePolicy
    Optional per-stream byte cap; omitted retains legacy buffered capture.
Type

ExternalCapturePolicy

Source

Limits the number of bytes retained from each external-command stream while continuing to drain both streams. Use this for provenance proof commands, whose diagnostics must remain bounded even if a child process is noisy. The default of four MiB per stream is the release proof contract; ordinary existing commands retain their buffered behavior unless they explicitly pass a policy. CompleteOnProcessExit is reserved for launchers whose descendants intentionally outlive the direct child. It cancels only output observation, preserves the child's exit code and command deadline, and marks output incomplete if EOF was not observed. Do not use it for complete structured-output proofs. Native pg_ctl startup uses independent postmaster ownership, listening, authentication and version checks to establish readiness.

Parameters

  • MaximumBytesPerStream
    Positive byte cap for stdout and, independently, stderr.
  • CompleteOnProcessExit
    Whether to end output observation when the direct child exits, even if a descendant retains its pipes. Defaults to false.
Property

ReleaseProof

ExternalCapturePolicy ReleaseProof { get; } Source

The standard bounded capture policy for release proof commands.

Type

ExternalCommandResult

Source

Captured command result including non-zero exit codes.

Parameters

  • ExitCode
    Process exit code, or -1 for a launch/timeout failure.
  • StandardOutput
    Captured stdout, possibly ending with a truncation marker.
  • StandardError
    Captured stderr, possibly ending with a truncation marker.
  • StandardOutputTruncated
    Whether stdout exceeded its capture limit or observation ended before EOF.
  • StandardErrorTruncated
    Whether stderr exceeded its capture limit or observation ended before EOF.
Type

BoundedCaptureStream

Source

Retains at most the requested number of bytes from a CliWrap output pipe and discards later bytes without closing the pipe. A successful command may therefore have truncated diagnostic output; callers must never treat a truncated stream as complete structured evidence.

Method

MarkIncompleteAfterProcessExit

void MarkIncompleteAfterProcessExit()

Marks a pipe whose direct child exited before its inherited writers reached EOF.

Remarks

Call only after the stream's copy operation has settled. Retained bytes remain bounded; this flag prevents an incomplete capture from being accepted as complete structured evidence.

Method

GetText

string GetText()

Returns retained UTF-8 text with an explicit truncation marker when needed.

Property

Truncated

bool Truncated { get; set; } Source

Whether bytes exceeded the capture cap or output observation ended before EOF.

Type

PackageArtifactManifestWriter

Source

Writes the machine-readable package artifact manifest consumed by protected publish jobs.

Method

WriteAsync

Task WriteAsync(PackageArtifactValidationReport report, string artifactsDirectory, string manifestPath, CancellationToken cancellationToken)

Writes a manifest that binds validated package ids to artifact file names and SHA-512 hashes.

Parameters

  • report
    Package artifact validation report.
  • artifactsDirectory
    Directory containing the validated package artifacts.
  • manifestPath
    Destination manifest path.
  • cancellationToken
    Cancellation token.
Type

PackageArtifactManifestReader

Source

Reads and validates the artifact manifest written by the package artifact verifier.

Method

ReadAsync

Task<PackageArtifactManifest> ReadAsync(string manifestPath, CancellationToken cancellationToken)

Reads a package artifact manifest from disk.

Parameters

  • manifestPath
    Manifest path.
  • cancellationToken
    Cancellation token.

Returns

Validated artifact manifest.

Type

PackagePublishWorkflow

Source

Publishes a validated package artifact set to NuGet in manifest order.

Method

RunAsync

Task<PackagePublishLedger> RunAsync(PackagePublishRequest request, CancellationToken cancellationToken)

Publishes each artifact selected by the checked-in manifest and writes a markdown ledger.

Parameters

  • request
    Publish request.
  • cancellationToken
    Cancellation token.

Returns

Publish ledger.

Type

PackageSmokeInstallWorkflow

Source

Restores every publish and support_publish package and verifies published .NET tools from a clean NuGet configuration after publish completes. Explicit support references cover packages unreachable from public roots.

Method

RunAsync

Task<PackageSmokeInstallReport> RunAsync(PackageSmokeInstallRequest request, CancellationToken cancellationToken)

Restores library entries in one aggregate smoke project, verifies tools in isolated workspaces, and replays a promoted Durable template against all installed package archives.

Parameters

  • request
    Smoke install request containing the repository root, package index manifest path, artifact manifest path, smoke work directory, report output path, and package source URL.
  • cancellationToken
    Cancellation token.

Returns

Smoke install report. Non-tool package entries share the aggregate restore result; tool entries report independent install and command-help results.

Remarks

Use this workflow for post-publish verification against a clean NuGet configuration. Non-tool packages share one generated Smoke.csproj restore to reduce total smoke time; tools are installed and run individually to keep command-shim verification isolated per package.

Restore, tool install, and tool help commands each use 180,000 ms timeouts. Aggregate restores and tool installs retry after 15s, 30s, 60s, and 120s delays. The package-restore directory and each per-tool directory under request . WorkDirectory are deleted and recreated on each run.

Pitfall: a failed aggregate package restore marks every non-tool package entry failed, but tool smoke still runs and is reported independently. Failed library or tool smoke withholds promoted template replay and published runtime-preflight proof. The report records completed library/tool results before either proof, and adds a template success only after replay and owned cleanup pass. Request validation and manifest or package-plan mismatches throw before a report is written; command failures without a required proof remain in the returned report unless the supplied cancellationToken cancels the workflow.

Method

StageInstalledToolArchive

void StageInstalledToolArchive(string toolPath, PackageArtifactManifestEntry entry, string packageVersion, string sharedPackagesPath)

Copies the freshly installed tool's raw NuGet archive from its isolated SDK store to the public proof cache.

Remarks

dotnet tool install --tool-path stores its package below tools/.store/id/version/id/version , independently of NUGET_PACKAGES . Call only after installation, help and exact-version checks pass. Preserve the public archive bytes, including its signature, and replace any stale cache copy; the published carrier must still compare every payload entry against the approved candidate before running the shared proof. A missing or linked archive closes the gate, even when another cache already contains this package identity.

Method

RequireRegularToolArchiveDirectory

string RequireRegularToolArchiveDirectory(string root, IReadOnlyList<string> components, bool create, string packageId)

Checks each owned store or cache directory before reading, creating or copying below it.

Method

ResolveToolShimPath

string ResolveToolShimPath(string toolPath, string commandName)

Resolves the installed tool shim path after proving the shim name cannot escape the tool directory.

Parameters

  • toolPath
    Directory passed to dotnet tool install --tool-path .
  • commandName
    Validated command token from tool_command_name .

Returns

Full path to the command shim that should be executed.

Exceptions

  • ArgumentException
    Thrown when the command token cannot safely be treated as one file name under toolPath .
Type

PackagePublishLedgerRenderer

Source

Renders protected publish outcomes for workflow artifacts.

Type

PackageSmokeInstallReportRenderer

Source

Renders package smoke install outcomes for workflow artifacts.

Type

PackagePublishRequest

Source

Request for a protected NuGet package publish workflow.

Parameters

  • RepositoryRoot
    Repository root used for plan resolution.
  • ManifestPath
    Checked-in package manifest path.
  • ArtifactsInputPath
    Directory containing validated .nupkg files.
  • ArtifactManifestPath
    Machine-readable artifact manifest path.
  • PublishLogPath
    Markdown publish ledger path.
  • Source
    NuGet source URL.
  • ApiKeyEnvironmentVariable
    Environment variable that supplies the NuGet API key.
  • DurableTemplateEvidenceDirectory
    Trusted exact-ID OS receipt download required for template publication.
  • DurableTemplateSourceCommit
    Expected full source revision supplied independently by the protected workflow.
  • TailwindEvidence
    Original candidate and native evidence required when the resolved plan contains Tailwind; omitted for non-Tailwind plans.
Type

TailwindPublicationRequest

Source

Trusted workflow identity and paths needed to validate a Tailwind publication. Values are supplied from protected job outputs and the exact ID-based downloads, never inferred from evidence JSON. The uploaded start receipt is separately identified because a locally written receipt cannot authorize a push.

Parameters

  • RepositoryRoot
    Exact checked-out source root.
  • ArtifactsInputPath
    Exact producer bundle download directory.
  • ArtifactManifestPath
    Manifest inside the producer bundle.
  • ProducerSubjectPath
    Subject inside the producer bundle.
  • ProducerArtifactId
    Immutable producer upload ID from the protected workflow.
  • ExpectedSubjectSha256
    SHA-256 of serialized producer subject from the protected output.
  • RepositoryId
    Numeric repository identity.
  • ProducerRunId
    Original workflow run ID that packed the candidate.
  • SourceCommit
    Full source commit expected in the checkout and verifier stamp.
  • AggregateInputPath
    Exact aggregate artifact download directory.
  • AggregateArtifactId
    Immutable aggregate upload ID.
  • ExpectedAggregateSha256
    SHA-256 of the serialized aggregate JSON.
  • PublicationDirectory
    Prepared, disjoint package archive directory.
  • PublicationStartReceiptPath
    Start receipt from its completed immutable upload.
  • PublicationStartArtifactId
    ID returned by that successful upload or exact recovery.
  • ReportDirectory
    Fresh diagnostics directory disjoint from inputs.
Type

IReleaseCredentialProvider

Source

Reads a NuGet credential only after publication evidence has passed validation.

Method

Read

string? Read(string environmentVariable)

Returns the named credential or null when it is unavailable.

Type

EnvironmentReleaseCredentialProvider

Source

Production credential reader for protected NuGet jobs.

Type

ITailwindPublicationEvidenceValidator

Source

Validates original Tailwind evidence and returns the confined prepared files to push.

Method

ValidateAsync

Task<IReadOnlyList<PlannedPackageArtifact>> ValidateAsync(TailwindPublicationRequest request, PackageArtifactManifest manifest, IReadOnlyList<PlannedPackageArtifact> originalEntries, CancellationToken cancellationToken)

Validates the producer, complete native evidence, uploaded start receipt, and prepared file inventory before credential acquisition. Every returned path must be a regular file inside the publication directory.

Type

TailwindPublicationEvidenceValidator

Source

Default Tailwind publisher validator, delegated to the shared evidence workflow.

Type

PackageSmokeInstallRequest

Source

Request for the post-publish smoke install and tool verification workflow.

Parameters

  • RepositoryRoot
    Repository root used for path display and validation.
  • ManifestPath
    Checked-in package manifest path used to revalidate the artifact manifest.
  • ArtifactManifestPath
    Machine-readable artifact manifest path.
  • WorkDirectory
    Isolated smoke install work directory.
  • ReportPath
    Markdown smoke install report path.
  • Source
    NuGet source URL.
  • PreflightProof
    Exact-bundle proof request required for the production public-feed carrier.
  • CandidatePreflightReceiptPath
    Validated candidate receipt retained with the producer artifact.
  • PublishedPreflightReceiptPath
    Destination for the public-feed shared proof and transport receipt.
Type

PackageArtifactManifest

Source

Machine-readable artifact manifest that binds validated package artifacts to immutable hashes.

Parameters

  • SchemaVersion
    Manifest schema version.
  • PackageVersion
    Exact stable or prerelease package version.
  • GeneratedAtUtc
    UTC timestamp when the manifest was generated.
  • Entries
    Manifest entries in package publish order.
Type

PackageArtifactManifestEntry

Source

One package artifact selected from the checked-in package manifest.

Parameters

  • PackageId
    NuGet package id.
  • ProjectPath
    Repository-relative project path.
  • Decision
    Publish decision string from the package plan.
  • ArtifactFileName
    Package artifact file name without directory segments.
  • Sha512
    Lowercase hexadecimal SHA-512 hash of the package artifact.
  • IsTool
    Whether the artifact is a .NET tool package.
  • ToolCommandName
    Validated command shim token carried from the package index for tool smoke verification. The value must be empty when IsTool is false . When IsTool is true , it is required and must be the same single file-name-safe command token declared in the package index tool_command_name field.
Type

PackagePublishLedger

Source

Publish result for a coordinated package version.

Parameters

  • PackageVersion
    Exact stable or prerelease package version.
  • Source
    NuGet source URL.
  • Entries
    Per-package publish outcomes.
  • TailwindIdentity
    Original protected candidate identity for Tailwind publication, including partial outcomes.
Type

TailwindPublicationIdentity

Source

Original immutable producer, aggregate, and uploaded start-receipt identifiers carried by a Tailwind publish ledger. The IDs explain which candidate a partial or retried publication attempted; a duplicate response alone does not prove the remote package has matching bytes.

Type

PackagePublishLedgerEntry

Source

Publish outcome for one package artifact.

Parameters

  • PackageId
    NuGet package id.
  • ProjectPath
    Repository-relative project path.
  • ArtifactFileName
    Package artifact file name.
  • Status
    Publish status.
  • ExitCode
    Exit code from dotnet nuget push , or zero for skipped packages.
  • Output
    Captured publish output with secrets excluded.
Type

PackageSmokeInstallReport

Source

Smoke install result for packages restored and tools verified after package publishing.

Parameters

  • PackageVersion
    Exact stable or prerelease package version.
  • Source
    NuGet source URL.
  • Entries
    Per-package smoke install outcomes.
Type

PackageSmokeInstallReportEntry

Source

Smoke install outcome for one public package or tool.

Parameters

  • PackageId
    NuGet package id.
  • ProjectPath
    Repository-relative project path.
  • IsTool
    Whether the package was installed as a .NET tool.
  • Status
    Smoke install status.
  • ExitCode
    Exit code from the final restore or tool command attempt.
  • Output
    Captured restore, install, or command output.
Type

PackageHash

Source

Computes package artifact hashes for manifest generation and publish verification.

Type

PackageArtifactJson

Source

JSON serializer options shared by artifact manifest readers and writers.

Type

ReleaseEnvironment

Source

Environment variables that make release automation quieter and deterministic.

Type

PackagePublishDecisionFormatter

Source

Formats package publish decisions for machine-readable release artifacts.

Type

PackageArtifactManifestPlanValidator

Source

Verifies that an artifact manifest still matches the checked-in package plan and validated artifacts.

Type

PlannedPackageArtifact

Source

Package artifact that has been matched to both the checked-in plan and artifact manifest.

Parameters

  • ManifestEntry
    Manifest entry for the artifact.
  • ArtifactPath
    Resolved artifact path on disk.
Type

DurableTemplateConsumerProofRequest

Source

Inputs to the isolated installed-template proof; no input contains a credential.

Parameters

  • RepositoryRoot
    Source checkout used only for authored-source and source-revision evidence.
  • ArtifactsDirectory
    Exact first-party candidate archives; remote first-party fallback is prohibited.
  • PackageVersion
    Exact coordinated candidate version.
  • ReceiptPath
    Safe JSON report destination outside the temporary workspace.
  • ThirdPartySource
    Acquisition-only third-party feed; never used by final consumer restore.
  • SourceCommit
    Full revision bound by the producer; omitted only for local diagnostic runs.
  • RunFirstWork
    Whether to run the real pinned-container certificate, required on Linux.
  • RunNativeSmoke
    Whether to run the separately owned native PostgreSQL ordinary-startup smoke.
  • Mode
    Candidate correctness or independently labeled public-feed replay; public receipts never authorize candidate publication.
Type

DurableTemplateProofArtifact

Source

Safe artifact identity; contains no consumer credentials, Work identity or arbitrary command output.

Type

DurableTemplateProofPhase

Source

A bounded phase observation; command arguments and captured output are never retained in receipts.

Parameters

  • Id
    Fixed proof command identifier.
  • ElapsedSeconds
    Monotonic elapsed command duration.
  • ExitCode
    Observed command exit code, including a negative launch or timeout result.
  • Truncated
    Whether either bounded child stream exceeded its capture limit.
  • TestRun
    Optional diagnostic-only TRX counters and failed-method hashes for test phases; omitted on other commands.
Type

DurableTemplateProofReceipt

Source

The version-one local receipt, emitted successfully only after assertions and owned cleanup finish.

Remarks

Local receipts reuse trusted workflow provenance; this format asserts no portable authenticity. RunnerImage contains the hosted runner's ImageOS/ImageVersion identity, or is empty for a local diagnostic without those observations. An empty identity cannot authorize publication. Failed native proofs use a fixed native stage identifier in FailurePhase. NativeAcquisition independently records validated tools before setup, without certifying a running server; absent validation leaves it unset. Raw exception messages and child output are never projected.

Type

DurableTemplateConsumerProof

Source

Verifies the installed artifact in fresh CLI/cache/output roots and emits bounded safe evidence.

Remarks

A first generated acquisition copy stages the third-party closure into a local feed. Final authored/archive/feed consumers then restore only from that feed with empty independent caches. The acquisition copy cannot satisfy either install proof. This workflow owns its temporary roots and never deletes parent/user cache directories.

Method

ReadRunnerImage

string ReadRunnerImage(string? imageOs, string? imageVersion)

Projects bounded hosted-runner OS/image revision labels. Missing or unsafe observations produce an empty diagnostic identity rather than an invented runner revision.

Method

RunAsync

Task<DurableTemplateProofReceipt> RunAsync(DurableTemplateConsumerProofRequest request, IReadOnlyList<PackageArtifactValidationReportEntry> artifacts, Func<string, IReadOnlyDictionary<string, string?>, CancellationToken, Task>? nativeSmoke = null, CancellationToken cancellationToken = default, Func<NativePostgreSqlToolIdentity?>? nativeToolIdentity = null, Func<NativePostgreSqlToolIdentity?>? nativeAcquisitionIdentity = null)

Runs acquisition, independent authored/installed proofs and cleanup; failed evidence never certifies publication.

Parameters

  • request
    Exact candidate and safe receipt destination.
  • artifacts
    Validated candidate rows, whose archive identity is checked again.
  • nativeSmoke
    Optional separately owned native smoke callback; required when requested.
  • cancellationToken
    Cancels work; independent bounded cleanup is still attempted.
  • nativeToolIdentity
    Optional safe native tool observation, collected only after native smoke finishes.
  • nativeAcquisitionIdentity
    Optional validated acquisition observation, collected after a native attempt even when setup fails; server identity may be absent.

Returns

Successful or failed safe receipt. Callers must require Succeeded before advancing release.

Method

RequireResult

void RequireResult(ExternalCommandResult result)

Rejects nonzero, launch/timeout and truncated results before interpreting structured evidence.

Method

RequireArtifact

PackageArtifactValidationReportEntry RequireArtifact(IReadOnlyList<PackageArtifactValidationReportEntry> rows, string id, string version)

Requires one exact candidate archive, without reading secrets from its content.

Method

VerifyRestoredGraph

void VerifyRestoredGraph(string root, string cache, string feed, string version)

Checks every restored first-party archive against the exact local candidate and forbids project substitution.

Method

RequireSqlIdentity

void RequireSqlIdentity(string providerArchive, string generatedRoot)

Requires canonical provider SQL bytes in each generated test output, never a template-owned recipe.

Method

WriteReceipt

void WriteReceipt(string path, DurableTemplateProofReceipt receipt)

Writes only the safe receipt model, capped at 64KiB, after proof cleanup.

Method

HashGeneratedContent

string HashGeneratedContent(string root)

Hashes the reviewed generated inventory in deterministic path/byte order, excluding build output.

Method

EnvironmentFor

Dictionary<string, string?> EnvironmentFor(string root, string label)

Creates owned CLI/cache roots and removes inherited credentials from a consumer child.

Parameters

  • root
    Unique proof-owned root, already validated before mutation.
  • label
    Fixed workflow phase label; callers never use arbitrary user input here.

Returns

Per-child overrides; the parent process environment is never changed.

Type

CloudTasksNeutralPackageContract

Source

Reads the packed nuspec contract for the neutral Durable packages being compared to the baseline.

Type

DurableTemplatePublicReplay

Source

Replays the template from the public feed after promotion, preserving the candidate/public identity distinction.

Method

RunAsync

Task RunAsync(PackageSmokeInstallRequest request, PackageArtifactManifest manifest, string publicCache, IExternalCommandRunner runner, CancellationToken cancellationToken)

Installs the public template through dotnet new and proves its payload against the frozen producer before execution.

Parameters

  • request
    Existing published smoke request with exact candidate preflight bindings.
  • manifest
    Frozen candidate manifest; raw public archive hashes may differ after signing.
  • publicCache
    Private cache restored by the existing public-feed smoke.
  • runner
    Bounded child runner.
  • cancellationToken
    Cancels work; owned template/roots are still cleaned.
Method

RequirePayloadIdentity

void RequirePayloadIdentity(string candidate, string published)

Compares every uncompressed package payload, ignoring only the NuGet signing envelope.

Type

ReleaseGuidanceRenderer

Source

Renders the finite package README release-guidance variants declared by the package manifest.

Remarks

The renderer owns only the explicit marker region in a package README. It deliberately does not normalize or infer package-specific documentation outside that region, so operational and adoption guidance stays authored by the package owner. See tools/ForgeTrust.AppSurface.PackageIndex/README.md#release-guidance for the maintainer workflow and recovery commands.

Method

CreateUpdatesAsync

Task<IReadOnlyList<ReleaseGuidanceUpdate>> CreateUpdatesAsync(string repositoryRoot, IReadOnlyList<ResolvedPackageEntry> entries, CancellationToken cancellationToken = default)

Builds the complete, validated set of package README replacements without writing any files.

Parameters

  • repositoryRoot
    Repository root that contains the manifest-selected package README files.
  • entries
    Resolved manifest entries whose documentation targets have already passed path validation.
  • cancellationToken
    Cancellation token used while reading the template and README files.

Returns

All managed README updates, including no-op updates used by verification.

Exceptions

  • PackageIndexException
    Thrown when the finite variant, template, marker, or README contract is invalid.
Method

ApplyUpdatesAsync

Task<int> ApplyUpdatesAsync(IReadOnlyList<ReleaseGuidanceUpdate> updates, CancellationToken cancellationToken = default)

Replaces validated generated documents and managed README regions using sibling staging files and ordinary-failure rollback.

Parameters

  • updates
    Fully rendered generated-file and README updates created before the first target write.
  • cancellationToken
    Cancellation token used while staging replacement content.

Returns

The number of target files changed.

Remarks

Staging makes malformed input fail before target replacement begins. A rollback journal restores targets if a normal replacement fails. Before each replacement, the target is re-read and must match the initial snapshot. A process or machine crash cannot be made globally atomic; verify detects resulting drift and reports the repository command that repairs it.

Method

VerifyUpdates

void VerifyUpdates(IReadOnlyList<ReleaseGuidanceUpdate> updates)

Verifies every managed README is already identical to the current rendered release-guidance variant.

Parameters

  • updates
    Fully rendered README updates created without writing files.

Exceptions

  • PackageIndexException
    Thrown when any managed README is stale.
Method

ExtractManagedRegionBody

string ExtractManagedRegionBody(string content, string displayPath)

Extracts the body owned by the release-guidance marker pair without rewriting the README.

Parameters

  • content
    Complete README content.
  • displayPath
    Repository-relative README path used in actionable failures.

Returns

The exact bytes between the ordered marker lines, including their line endings.

Exceptions

  • PackageIndexException
    Thrown when the README does not contain exactly one ordered marker pair.

Remarks

Release-preparation provenance verification uses this method to bind a changed README only to the generated region. It intentionally preserves line endings and does not trim whitespace: a hash of this value must prove the exact generated body that will be committed.

Type

ReleaseGuidanceUpdate

Source

Describes one rendered package README policy region without changing the checked-in file.

Type

TailwindSourceIdentity

Source

Checks that release evidence is produced by the exact, clean source and stamped verifier build.

Type

CloudTasksNeutralSourceProof

Source

Verifies that a pinned baseline and candidate contain identical authored inputs for the neutral Durable packages.

Method

Verify

IReadOnlyDictionary<string, string> Verify(string baselineRoot, string candidateRoot)

Compares source files and shared build inputs, allowing only the two exact Cloud Tasks central package pins.

Parameters

  • baselineRoot
    Root of the source archive pinned for the neutral package baseline.
  • candidateRoot
    Root of the candidate repository source.

Returns

Sorted baseline and candidate SHA-256 evidence keyed by repository-relative file path.

Exceptions

  • PackageIndexException
    A source file, shared input, or unapproved central pin differs.
Type

TailwindPreparedPackage

Source

One package file prepared for the final push boundary.

Type

PreparedTailwindPublication

Source

Validated identity and exact package file inventory for a release publish.

Type

TailwindEvidenceWorkflow

Source

Typed verifier for native Tailwind release evidence and publication inputs.

Method

PreparePublicationAsync

Task<PreparedTailwindPublication> PreparePublicationAsync(TailwindPublicationRequest request, PackageArtifactManifest manifest, IReadOnlyList<PlannedPackageArtifact> originalEntries, CancellationToken cancellationToken)

Validates the aggregate and producer bundle, copies immutable push inputs, and writes an upload-ready start receipt.

Method

ValidatePublicationAsync

Task<IReadOnlyList<PlannedPackageArtifact>> ValidatePublicationAsync(TailwindPublicationRequest request, PackageArtifactManifest manifest, IReadOnlyList<PlannedPackageArtifact> originalEntries, CancellationToken cancellationToken)

Revalidates producer, aggregate and uploaded start receipt, returning only prepared push paths.

Method

ReadExpectedBinary

(string Name, string Sha256) ReadExpectedBinary(string archivePath, string rid)

Reads the expected host binary identity from the producer Tailwind archive's release manifest.

Parameters

  • archivePath
    Path to the producer Tailwind NuGet archive.
  • rid
    Host RID, which must identify exactly one asset in the manifest.

Returns

The selected binary filename and SHA-256.

Exceptions

  • PackageIndexException
    The archive has no usable manifest or selected binary identity.
Method

RequireDirectChild

void RequireDirectChild(string directory, string file)

Requires a bound evidence or publication file to live directly in its trusted directory.

Parameters

  • directory
    Expected parent directory.
  • file
    Path to check without following a different parent path.

Exceptions

  • PackageIndexException
    The file's normalized parent is not directory .
Method

ResolveChildDirectory

string ResolveChildDirectory(string root, string relative)

Resolves an existing host artifact directory beneath the evidence root without traversal or links.

Parameters

  • root
    Downloaded evidence root.
  • relative
    Single safe directory name supplied by the validated host map.

Returns

The absolute child directory path.

Exceptions

  • PackageIndexException
    The child is unsafe, missing, outside the root, or a link.
Type

DurableTemplateTestObservation

Source

Diagnostic-only test counters and method hashes; never retains result text or authorizes success.

Parameters

  • Status
    Closed diagnostic status: observed, missing or invalid.
  • Total
    Reported test count, at most 10,000; zero without an observation.
  • Executed
    Reported executed count, no greater than Total.
  • Passed
    Reported passed count; Passed plus Failed cannot exceed Executed.
  • Failed
    Reported failed count; does not determine the command's success.
  • FailedMethodSha256
    At most 16 distinct, sorted method-identity digests; incomplete metadata may leave this empty.

Remarks

Status is observed, missing or invalid. Counts are zero when no complete bounded TRX observation exists. FailedMethodSha256 contains at most 16 distinct hashes of UTF-8 className, a newline and method name, sorted ordinally. It excludes display names, theory arguments, messages, stacks and child output. Raw TRX files stay in the owned proof workspace and are deleted during its existing cleanup.

Method

Read

DurableTemplateTestObservation Read(string path)

Reads at most one MiB of regular TRX XML; missing or invalid diagnostics cannot override a child exit.

Parameters

  • path
    TRX path inside the proof's canonical owned results directory.

Returns

Safe counters and hashes, or a closed missing/invalid observation without raw exception details.

Property

FirstWorkFailures

IReadOnlyList<DurableTemplateFirstWorkDiagnostic>? FirstWorkFailures { get; init; } Source

Gets at most 16 distinct closed failure markers from identity-matched failed first-work tests.

Remarks

Null means no valid marker was available. These diagnostics never authorize a successful proof.

Type

ReleasePreparationWitnessBuilder

Source

Produces a deterministic, read-only description of generated package documentation for release-preparation review.

Remarks

The witness is deliberately a statement of repository truth at one merge base and HEAD. It never calls generate and never changes package documentation; the Release tool validates this JSON before accepting a generated package surface in an otherwise narrowly-scoped release preparation pull request.

Method

CreateAsync

Task<ReleasePreparationWitness> CreateAsync(PackageIndexRequest request, string baseRef, CancellationToken cancellationToken = default)

Calculates a JSON witness for package documentation that is generated at HEAD.

Parameters

  • request
    Resolved package-index request rooted at the checked-out repository.
  • baseRef
    Fetched base ref or immutable base commit used to derive the merge base.
  • cancellationToken
    Cancellation token for file, renderer, and Git work.

Returns

A strictly ordered witness with identity, semantic source inputs, and expected generated output hashes.

Method

WriteAsync

Task WriteAsync(ReleasePreparationWitness witness, string path, CancellationToken cancellationToken = default)

Writes a witness as UTF-8 JSON without modifying any repository-owned package surface.

Parameters

  • witness
    Witness to serialize.
  • path
    Explicit destination, normally a CI temporary path.
  • cancellationToken
    Cancellation token for the write.
Type

ReleasePreparationWitness

Source

Immutable JSON contract emitted by ReleasePreparationWitnessBuilder .

Type

ReleasePreparationWitnessInput

Source

One changed semantic source that authorizes specific generated package surfaces.

Type

ReleasePreparationWitnessSurface

Source

One generated package surface and the SHA-256 digest the canonical renderer expects at HEAD.

Type

DurableTemplateCommand

Source

Exact installed-artifact proof command; arguments choose proof inputs, never template content or SQL policy.

Method

RunAsync

Task<DurableTemplateProofReceipt> RunAsync(string[] arguments, string currentDirectory, IExternalCommandRunner runner, CancellationToken cancellationToken)

Runs a source-bound correctness proof from the immutable local producer bundle.

Parameters

  • arguments
    Explicit option/value pairs; unknown, duplicate and incomplete options are rejected.
  • currentDirectory
    Base for user-supplied relative paths.
  • runner
    Bounded command runner, optionally deterministic in command-dispatch tests.
  • cancellationToken
    Cancels work; independently bounded proof cleanup still runs.

Returns

Safe schema-v1 receipt; command callers use its Succeeded flag as the exit signal.

Method

RunNativeSmokeAsync

Task RunNativeSmokeAsync(string bin, string root, IReadOnlyDictionary<string, string?> environment, IExternalCommandRunner runner, Action<NativePostgreSqlToolIdentity> identitySink, CancellationToken cancellationToken, Func<string, IExternalCommandRunner, CancellationToken, Task<DurableTemplateNativePostgreSql>>? startClusterAsync = null, Func<DurableTemplateNativePostgreSql, int, ValueTask>? disposeClusterAsync = null, Action<NativePostgreSqlToolIdentity>? acquisitionIdentitySink = null)

Runs the generated ordinary-startup smoke against one privately owned native PostgreSQL cluster. Linux uses /tmp and macOS uses /private/tmp for the cluster root; Windows and other platforms use the system temporary directory. The short Unix paths keep PostgreSQL's socket path within its fixed limit.

Parameters

  • bin
    Absolute PostgreSQL tool directory selected for the smoke runner.
  • root
    Generated test project to run.
  • environment
    Environment shared with the generated proof, copied before adding cluster credentials.
  • runner
    Bounded runner used for both cluster operations and the generated test command.
  • identitySink
    Receives the validated tool and server identity for the proof receipt.
  • cancellationToken
    Cancels setup and smoke execution; bounded cluster cleanup still runs.
  • startClusterAsync
    Optional test seam that returns an owned cluster. Production uses DurableTemplateNativePostgreSql with the fixed resolver for bin .
  • disposeClusterAsync
    Optional test seam observing the owned cluster's exact shared cleanup allowance. Production disposes the cluster using that allowance; the callback must also dispose its cluster.
  • acquisitionIdentitySink
    Optional observation of validated tools before cluster setup; this does not certify a running server.

Exceptions

  • PackageIndexException
    Thrown when the generated smoke or its required output markers fail validation.

Remarks

The smoke still enforces the 103-byte Unix-domain socket path limit in DurableTemplateNativePostgreSql . Linux and macOS ignore user-selected temporary-directory environment paths for this owned cluster because they can exceed that limit.

Method

ReadCleanupRemaining

int ReadCleanupRemaining(string output)

Requires the generated child's bounded cleanup observation before sharing the remaining cluster allowance.

Type

DurableTemplateCommandOptions

Source

Resolved immutable inputs to verify-durable-template; parsing performs no IO or tool launch.

Method

Parse

DurableTemplateCommandOptions Parse(string[] args, string currentDirectory)

Requires exact version/source/archive/receipt inputs and confines no mutable authority to the generated app.

Type

TailwindPayloadProjection

Source

Deterministic v1 projection of package build/runtime assets and files selected by the fixed assets graph.

Method

ReadArchiveProjectionHashes

IReadOnlyDictionary<string, string> ReadArchiveProjectionHashes(string archivePath, JsonElement targetNode, CancellationToken cancellationToken)

Hashes the projection-v1 package entries protected by roots and selected by an assets target node.

Parameters

  • archivePath
    Path to the producer package archive.
  • targetNode
    The first-party package node from the inventoried consumer assets graph.
  • cancellationToken
    Token used to stop archive enumeration and hashing.

Returns

Case-insensitive archive-relative paths mapped to lowercase SHA-256 digests.

Type

TailwindProofSubject

Source

Immutable producer identity written beside the package artifact manifest.

Type

TailwindSubjectPackage

Source

One producer package in the fixed first-party consumer closure.

Type

TailwindProofSubjectService

Source

Strict producer subject creation and trusted bundle validation.

Type

PackageIndexGenerator

Source

Generates and verifies the manifest-backed package chooser markdown for the repository.

Remarks

This generator is intentionally repository-aware. It expects the manifest, chooser sidecar, package README links, and release-surface links to resolve to files under the supplied repository root. Callers should validate repository layout drift through VerifyAsync in CI whenever package or docs paths change.

Method

GenerateToFileAsync

Task<PackageIndexGenerationReport> GenerateToFileAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)

Generates package chooser and readiness dashboard markdown, then reconciles the managed release-guidance region in every qualifying package README.

Parameters

  • request
    Generation request describing the repository root, manifest path, chooser output, and readiness output.
  • cancellationToken
    Cancellation token used for manifest loading, metadata evaluation, and file writes.

Returns

A report describing the generated package-index documents and managed README reconciliation.

Exceptions

  • PackageIndexException
    Thrown when the repository layout is invalid, required docs are missing, or the manifest cannot be rendered safely.

Remarks

This method stages the generated markdown payloads and all managed README replacements before replacing any target. An ordinary replacement failure rolls back every prior replacement, and a target that changed after its initial read is rejected rather than overwritten. It creates output directories when they do not already exist.

Method

GenerateAsync

Task<string> GenerateAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)

Generates chooser markdown from the manifest and evaluated project metadata without writing it to disk.

Parameters

  • request
    Generation request describing the repository root, manifest path, and output path context.
  • cancellationToken
    Cancellation token used while loading the manifest and project metadata.

Returns

The fully rendered chooser markdown.

Exceptions

  • PackageIndexException
    Thrown when repository layout, manifest content, or linked docs targets do not satisfy the chooser contract.
Method

GenerateDocumentsAsync

Task<PackageIndexDocuments> GenerateDocumentsAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)

Generates the package chooser and package-index evidence dashboard without writing either file to disk.

Parameters

  • request
    Generation request describing repository inputs and output path contexts.
  • cancellationToken
    Cancellation token used while loading the manifest and project metadata.

Returns

Generated chooser and readiness markdown payloads.

Method

GenerateDocuments

PackageIndexDocuments GenerateDocuments(PackageIndexRequest request, IReadOnlyList<ResolvedPackageEntry> entries)

Renders the package chooser and readiness documents from entries already resolved for the same request.

Parameters

  • request
    Generation request that supplies output and repository context.
  • entries
    Canonical entries resolved by ResolveGenerationEntriesAsync .

Returns

In-memory document content without reading or writing repository files.

Method

VerifyAsync

Task VerifyAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)

Verifies that the checked-in chooser and readiness dashboard files match the current repository truth.

Parameters

  • request
    Verification request describing the repository root, manifest path, and generated files.
  • cancellationToken
    Cancellation token used while regenerating and reading the existing generated files.

Returns

A task that completes when verification succeeds.

Exceptions

  • PackageIndexException
    Thrown when either generated file is missing or differs from freshly generated markdown.
Method

RunPackageGateAsync

Task<PackageGateReport> RunPackageGateAsync(PackageIndexRequest request, CancellationToken cancellationToken = default)

Runs release-readiness checks that protect the package manifest from drifting away from publishable packages.

Parameters

  • request
    Gate request describing the repository root, manifest path, and generated chooser file.
  • cancellationToken
    Cancellation token used while evaluating package metadata and scanning files.

Returns

A report summarizing the package and source-file surfaces covered by the gate.

Exceptions

  • PackageIndexException
    Thrown when release metadata is missing, package class rules are violated, or stale brand strings remain.
Method

ResolveGenerationEntriesAsync

Task<IReadOnlyList<ResolvedPackageEntry>> ResolveGenerationEntriesAsync(PackageIndexRequest request, CancellationToken cancellationToken)

Resolves the validated package entries used by every canonical package-index rendering path.

Remarks

This is exposed internally so read-only provenance consumers can reuse the exact renderer inputs instead of reconstructing manifest or project metadata rules.

Method

ValidateWebPackageQuickstartTarget

void ValidateWebPackageQuickstartTarget(string repositoryRoot)

Validates that the package-first chooser link resolves to the quickstart file and section anchor.

Parameters

  • repositoryRoot
    Repository root that contains the Start Here quickstart.

Exceptions

  • PackageIndexException
    Thrown when the quickstart file is missing or no heading or explicit anchor produces the expected fragment target.

Remarks

The generated chooser deep links into this document. Checking the file alone is not enough, because a heading rename would otherwise ship a dead #package-first-path link while package verification still passes.

Method

ValidateToolCommandName

void ValidateToolCommandName(PackageManifestEntry entry, PackageProjectMetadata metadata)

Validates the manifest command-name contract against project metadata for one package row.

Parameters

  • entry
    Manifest row that may declare tool_command_name and a publish decision.
  • metadata
    Evaluated project metadata that reports whether the project packs as a .NET tool.

Exceptions

  • PackageIndexException
    Thrown when a tool selected for PackagePublishDecision.Publish or PackagePublishDecision.SupportPublish omits or mis-shapes tool_command_name , or when a non-tool project declares a command name despite not setting PackAsTool=true .
Method

ValidateToolCommandNameValue

void ValidateToolCommandNameValue(string projectPath, string commandName)

Validates the manifest-declared tool command token for one project.

Parameters

  • projectPath
    Repository-relative project path used in actionable error messages.
  • commandName
    Command token read from tool_command_name .

Exceptions

  • PackageIndexException
    Thrown when the command token is missing or uses a value that cannot safely resolve to one command shim file.

Remarks

The value must be a single file-name-safe token. It must not be blank, . , .. , a Windows reserved device name or dotted alias such as con.txt , end with a period, or contain whitespace, path separators, control characters, or portable file-name-invalid characters.

Method

GetSharedPublicReleaseNotePath

string? GetSharedPublicReleaseNotePath(PackageIndexRequest request, IReadOnlyList<ResolvedPackageEntry> publicEntries)

Finds the release note all publishable public package rows currently share.

Parameters

  • request
    Generation request that supplies the chooser output context used to validate release-note links.
  • publicEntries
    Public chooser rows resolved from the package manifest.

Returns

The shared release-note path, or null when rows point at mixed or missing release notes.

Method

GetRelativeRepositoryPath

string GetRelativeRepositoryPath(PackageIndexRequest request, string repositoryRelativePath, string? outputPath = null)

Gets a safe relative repository link for generated maintainer guidance that may not be copied into minimal test fixtures.

Remarks

Unlike the existing GetRelativeDocPath helpers, this helper does not require the target to exist. The checked-in generated output still names a repository-owned guide, while isolated callers can generate a package dashboard without recreating every guide. Package manifest entries continue to use the GetRelativeDocPath helpers and therefore require existing targets.

Method

GetCanonicalRepositoryUrl

string GetCanonicalRepositoryUrl(string repositoryRelativePath)

Builds a canonical GitHub URL for repository-owned maintainer documentation that is not served by AppSurface Docs.

Parameters

  • repositoryRelativePath
    A non-empty, slash-separated GitHub repository path whose segments do not contain direct or percent-encoded dot traversal or path separators.

Returns

The canonical main -branch GitHub URL with each documentation-path segment URI-escaped.

Remarks

Generated package documents are also harvested by AppSurface Docs. Repository-relative paths that escape the generated document's directory can be interpreted as Docs routes and produce a reader-facing 404. This helper validates GitHub URI path semantics independently of the build host and escapes URI-significant characters so a path segment cannot alter the target URL. Use it for maintainer guides that intentionally remain repository-owned rather than Docs-hosted.

Method

RepositoryFileExists

bool RepositoryFileExists(string repositoryRoot, string repositoryRelativePath)

Checks whether a known repository-relative chooser support file exists under the repository root.

Parameters

  • repositoryRoot
    Repository root used as the path-resolution base; relative roots are normalized with Path.GetFullPath(string) .
  • repositoryRelativePath
    Repository-relative file path, conventionally using / separators.

Returns

true when the normalized file exists; otherwise, false .

Remarks

Use this only for trusted, optional chooser links. It normalizes separators and resolves .. segments before checking existence, but missing files are not errors. Manifest-supplied or required documentation targets should use ResolveRepositoryFilePath so rooted, escaping, or missing paths fail loudly.

Method

MarkdownDefinesFragmentTarget

bool MarkdownDefinesFragmentTarget(string markdown, string fragment)

Checks whether markdown defines an explicit anchor or slugified heading for a fragment.

Parameters

  • markdown
    Markdown content to inspect.
  • fragment
    Fragment id without a leading # .

Returns

true when the content defines the fragment; otherwise, false .

Remarks

The check intentionally covers the forms authors are likely to use in hand-written docs: GitHub-style generated heading ids, explicit {#id} heading anchors, and HTML anchor elements.

Method

TryGetMarkdownHeadingText

string? TryGetMarkdownHeadingText(string line)

Extracts the text from an ATX markdown heading line when the line uses one to six leading hash marks.

Parameters

  • line
    Single markdown line to inspect.

Returns

The heading text without closing hash marks or explicit anchor syntax, or null when not a heading.

Method

SlugifyMarkdownHeading

string SlugifyMarkdownHeading(string heading)

Produces the GitHub-style heading slug used by repository markdown anchors for simple heading text.

Parameters

  • heading
    Heading text to slugify.

Returns

A lowercase fragment id using hyphens for spaces and hyphens in the source text.

Method

ResolveRepositoryFilePath

string ResolveRepositoryFilePath(string repositoryRoot, string repositoryRelativePath, string description)

Resolves a required repository-relative documentation target and validates that it exists under the repository root.

Parameters

  • repositoryRoot
    Repository root used as the resolution boundary; relative roots are normalized with Path.GetFullPath(string) .
  • repositoryRelativePath
    Repository-relative file path supplied by chooser metadata, conventionally using / separators.
  • description
    Human-readable label included in validation errors.

Returns

The normalized absolute path to the validated file.

Exceptions

  • PackageIndexException
    Thrown when repositoryRelativePath is blank, rooted, escapes the repository root after normalization, or points at missing documentation.

Remarks

The resolver replaces / with Path.DirectorySeparatorChar and normalizes .. segments. Callers should keep inputs repository-relative and avoid leading separators, because absolute-looking paths are rejected before they can bypass the repository boundary.

Property

RepositoryPathComparison

StringComparison RepositoryPathComparison { get; } Source

Gets the path-comparison rule used when enforcing repository-boundary checks for chooser links.

Remarks

Windows paths are treated case-insensitively. Other platforms stay ordinal so chooser validation does not assume a case-insensitive filesystem on Linux or macOS.

Type

PackageIndexRequest

Source

Describes one package chooser and readiness dashboard generation or verification request.

Parameters

  • RepositoryRoot
    Absolute repository root that contains the manifest, docs, and project files.
  • ManifestPath
    Absolute path to the chooser manifest file.
  • ChooserOutputPath
    Absolute path to the generated chooser markdown file.
  • ReadinessOutputPath
    Absolute path to the generated package readiness dashboard markdown file.
Property

OutputPath

string OutputPath { get; } Source

Gets the chooser output path retained for compatibility with existing tests and callers.

Type

PackageIndexDocuments

Source

Generated markdown documents produced from one package index resolution pass.

Parameters

  • ChooserMarkdown
    Generated adopter-facing package chooser markdown.
  • ReadinessMarkdown
    Generated maintainer-facing package readiness evidence markdown.
Type

PackageIndexGenerationReport

Source

Summarizes the managed package README work performed by PackageIndexGenerator.GenerateToFileAsync .

Parameters

  • ManagedReleaseGuidanceCount
    Number of package READMEs that declare a managed release-guidance region.
  • ChangedReleaseGuidanceCount
    Number of managed package READMEs whose region was rewritten.
Type

ResolvedPackageEntry

Source

Couples one manifest row with the evaluated package metadata used to render the chooser.

Parameters

  • Manifest
    The manifest row that provides classification, prose, and docs pointers.
  • Metadata
    The evaluated project metadata that provides package identity and install details.
Type

PackageReadinessEvaluator

Source

Computes package-index readiness evidence for the maintainer dashboard without treating the dashboard as live publish proof.

Method

Evaluate

IReadOnlyList<PackageReadinessEvidence> Evaluate(string repositoryRoot, IReadOnlyList<ResolvedPackageEntry> entries)

Evaluates package-index evidence for resolved package rows.

Parameters

  • repositoryRoot
    Absolute repository root used to validate release-note paths.
  • entries
    Resolved package rows.

Returns

Per-package readiness evidence with blocking reasons and fix hints.

Type

PackageReadinessEvidence

Source

Per-package readiness evidence rendered in the generated maintainer dashboard.

Parameters

  • ProjectPath
    Repository-relative project path from the package manifest.
  • PackageId
    Evaluated package id.
  • Status
    Computed package-index evidence status.
  • Evidence
    Non-blocking evidence that passed.
  • BlockingReasons
    Reasons the package-index evidence is blocked.
  • FixHints
    Maintainer-facing fix hints for blocking reasons.
Type

PackageGateReport

Source

Summarizes the package gate coverage used by CI and local release checks.

Parameters

  • PackageCount
    Number of manifest entries validated by package class and release metadata rules.
  • ScannedFileCount
    Number of source files scanned for stale brand strings.
Type

PackageGateValidator

Source

Validates package release metadata, package-class invariants, and stale brand drift before packages are published.

Method

Validate

PackageGateReport Validate(string repositoryRoot, IReadOnlyList<ResolvedPackageEntry> entries)

Validates all gate rules against resolved package entries and repository files.

Parameters

  • repositoryRoot
    Absolute repository root to scan.
  • entries
    Resolved package entries from the chooser manifest.

Returns

A compact report describing gate coverage.

Type

PackageIndexException

Source

Represents a package chooser generation or verification failure.

Remarks

These exceptions are written directly to CLI stderr, so messages should stay actionable and user-facing.

Type

IProjectMetadataProvider

Source

Contract for evaluating one discovered project into package metadata suitable for chooser rendering, including its package type so the chooser can distinguish templates from ordinary NuGet packages and .NET tools.

Method

GetMetadataAsync

Task<PackageProjectMetadata> GetMetadataAsync(string repositoryRoot, string projectPath, CancellationToken cancellationToken)

Evaluates one project file and returns the package metadata used by the chooser.

Parameters

  • repositoryRoot
    Absolute repository root used as the evaluation working directory.
  • projectPath
    Repository-relative project path for the project being evaluated.
  • cancellationToken
    Cancellation token that should abort the evaluation when possible.

Returns

The evaluated project metadata for the supplied project.

Type

PackageProjectMetadata

Source

Evaluated package metadata used by the chooser renderer, including NuGet package type information for selecting the correct adopter install command.

Parameters

  • ProjectPath
    Repository-relative path to the project that produced this metadata.
  • PackageId
    NuGet package identifier emitted by the project.
  • TargetFramework
    Resolved target framework summary used in chooser copy.
  • IsPackable
    Whether the project reports itself as packable.
  • IsTool
    Whether the project reports itself as a .NET tool package.
  • OutputType
    Resolved output type, such as Library or Exe .
  • ProjectReferences
    Evaluated project reference paths that contribute package dependency assets.
  • PackageType
    The evaluated NuGet package type list. An empty value represents the default package type.
Property

IsTemplate

bool IsTemplate { get; } Source

Gets whether the evaluated NuGet package type list contains Template , compared case-insensitively. Package types are semicolon-delimited, matching the evaluated MSBuild property.

Property

InstallCommand

string InstallCommand { get; } Source

Gets the primary install command shown in the chooser for this package, tool, or template. Template commands include an <version> placeholder that consumers replace with an explicit released version; tools retain their global prerelease install command, and libraries use the .NET package-add command.

Type

PackageProjectScanner

Source

Discovers candidate projects that should be classified by the package chooser manifest.

Remarks

The scanner intentionally excludes tests, examples, executable tooling, generated directories, and hidden local cache directories so the manifest only needs to classify packages that are meaningful to external adopters or package-surface maintainers. ForgeTrust.AppSurface.ReleaseContracts is the one transitive support package stored below tools ; it remains discoverable because published Docs consumers restore it as a dependency.

Method

DiscoverProjects

IReadOnlyList<string> DiscoverProjects(string repositoryRoot)

Enumerates candidate project files under the repository root.

Parameters

  • repositoryRoot
    Absolute repository root to scan.

Returns

Repository-relative project paths ordered for stable manifest validation.

Method

IsCandidateProject

bool IsCandidateProject(string relativePath)

Determines whether a repository-relative project path belongs in the chooser manifest.

Parameters

  • relativePath
    Repository-relative project path to evaluate.

Returns

true when the path should be classified by the chooser manifest; otherwise, false .

Type

DotNetProjectMetadataProvider

Source

Evaluates project metadata by invoking dotnet msbuild and reading JSON property output, including the evaluated PackageType used to identify template packs.

Remarks

This provider depends on a functioning local .NET SDK and assumes the project can be evaluated from the repository root. Timeouts and malformed output are surfaced as PackageIndexException so CLI callers can fail fast in CI.

Method

ParseMetadataJson

PackageProjectMetadata ParseMetadataJson(string projectPath, string standardOutput)

Parses one dotnet msbuild JSON payload into package metadata.

Parameters

  • projectPath
    Repository-relative project path used for error reporting.
  • standardOutput
    Raw JSON payload captured from dotnet msbuild .

Returns

The normalized package metadata derived from the JSON payload.

Exceptions

  • PackageIndexException
    Thrown when the JSON payload is malformed, missing required properties, or reports incomplete metadata.

Remarks

This parsing seam is intentionally internal so tests can verify malformed and incomplete metadata handling without depending on a real SDK invocation or using reflection against private helpers.

Type

PackageManifestLoader

Source

Loads the chooser manifest from YAML into strongly typed manifest models.

Method

LoadAsync

Task<PackageManifest> LoadAsync(string manifestPath, CancellationToken cancellationToken)

Reads and parses the chooser manifest file.

Parameters

  • manifestPath
    Absolute path to the chooser manifest file.
  • cancellationToken
    Cancellation token used while reading the manifest from disk.

Returns

The parsed chooser manifest.

Exceptions

  • PackageIndexException
    Thrown when the manifest cannot be parsed or does not define any package rows.
Type

PackageManifest

Source

Root manifest model for the chooser YAML file.

Property

Packages

List<PackageManifestEntry> Packages { get; init; } Source

Gets the ordered manifest rows that describe each package, support surface, or excluded package entry.

Type

PackageManifestEntry

Source

One manifest row describing how a project should appear in the chooser.

Remarks

Public rows must define install guidance and docs pointers. Non-public rows must define Note because their rendered bullets rely on that prose to explain why they are visible but not recommended as first installs.

Property

Project

string Project { get; init; } Source

Gets the repository-relative project path classified by this manifest entry.

Property

Classification

PackageClassification Classification { get; init; } Source

Gets the chooser classification that controls which section renders the package.

Property

PublishDecision

PackagePublishDecision? PublishDecision { get; init; } Source

Gets the publish decision consumed by the package artifact workflow.

Property

ProductFamily

string? ProductFamily { get; init; } Source

Gets the product family that owns this package row for maintainer readiness review.

Property

PublishReason

string? PublishReason { get; init; } Source

Gets the required maintainer-facing reason for entries that are intentionally not published.

Property

ReadinessBlocker

string? ReadinessBlocker { get; init; } Source

Gets the optional same-repository issue or pull request that blocks package-index evidence completion.

Property

ReadinessNote

string? ReadinessNote { get; init; } Source

Gets optional escaped plain-text maintainer context for package readiness evidence.

Property

Order

int Order { get; init; } Source

Gets the stable display order within the chooser section.

Property

UseWhen

string? UseWhen { get; init; } Source

Gets the adopter-focused “use when” guidance for public package rows.

Property

Includes

string? Includes { get; init; } Source

Gets the concise statement describing what the package includes for public rows.

Property

DoesNotInclude

string? DoesNotInclude { get; init; } Source

Gets the concise statement describing what the package intentionally does not include for public rows.

Property

StartHerePath

string? StartHerePath { get; init; } Source

Gets the repository-relative documentation file linked from this chooser row.

Property

StartHereLabel

string? StartHereLabel { get; init; } Source

Gets the optional chooser label used for the linked documentation target.

Property

RecipeSummary

string? RecipeSummary { get; init; } Source

Gets the optional recipe summary shown in the “Also building...” section.

Property

ToolCommandName

string? ToolCommandName { get; init; } Source

Gets the command shim expected from a .NET tool package.

Remarks

This field is only valid for projects that set PackAsTool=true . Public tool packages must provide a value so package validation, publish planning, and post-publish smoke tests can execute the command users type; non-tool packages must leave it unset. The value must be one file-name-safe command token rather than a path: no whitespace, path separators, reserved . / .. segments, trailing periods, Windows reserved device names or dotted aliases, control characters, or Windows-invalid file-name characters.

Property

Note

string? Note { get; init; } Source

Gets the explanatory note rendered for non-public package rows.

Property

DependsOn

List<string> DependsOn { get; init; } Source

Gets the optional package ids that this row depends on for install guidance.

Property

ExpectedDependencyPackageIds

List<string> ExpectedDependencyPackageIds { get; init; } Source

Gets the exact package ids expected from project-reference dependencies in the produced package.

Property

ReleaseStatus

PackageReleaseStatus ReleaseStatus { get; init; } Source

Gets the release status expected by package-gate for this package classification.

Property

CommercialStatus

PackageCommercialStatus CommercialStatus { get; init; } Source

Gets whether this package row is part of the commercial-ready public surface.

Property

ReleaseTrack

string? ReleaseTrack { get; init; } Source

Gets the release-link policy. coordinated resolves to the frozen tree-local releases/current.md pointer; explicit uses ReleaseNotesPath .

Property

ReleaseNotesPath

string? ReleaseNotesPath { get; init; } Source

Gets the repository-relative release notes file for explicit links. Legacy rows without ReleaseTrack also retain this explicit-path meaning.

Property

ReleaseGuidanceVariant

string? ReleaseGuidanceVariant { get; init; } Source

Gets the finite generated release-guidance variant for a package README that contains a managed release-policy region.

Remarks

Valid values are default , apphost , and experimental . This field is intentionally absent for manifest entries whose documentation target has no managed release-guidance region.

Type

Program

Source

CLI entry point for generating or verifying the package chooser and maintainer readiness dashboard.

Method

Main

Task<int> Main(string[] args)

Launches the package chooser CLI with the current process IO streams and working directory.

Parameters

  • args
    Command-line arguments supplied to the process.

Returns

Process exit code where 0 indicates success.

Method

RunAsync

Task<int> RunAsync(string[] args, TextWriter standardOut, TextWriter standardError, string currentDirectory, CancellationToken cancellationToken = default, Func<PackageArtifactRequest, CancellationToken, Task<PackageArtifactValidationReport>>? verifyPackagesAsync = null, Func<PackagePublishRequest, CancellationToken, Task<PackagePublishLedger>>? publishPrereleaseAsync = null, Func<PackagePublishRequest, CancellationToken, Task<PackagePublishLedger>>? publishStableAsync = null, Func<PackageSmokeInstallRequest, CancellationToken, Task<PackageSmokeInstallReport>>? smokeInstallAsync = null, Func<PythonParserCandidateProofRequest, CancellationToken, Task<PythonParserCandidateProofReport>>? inspectPythonParserCandidateAsync = null, IExternalCommandRunner? preflightCommandRunner = null)

Runs the package chooser CLI against the supplied IO streams and working directory.

Parameters

  • args
    Command-line arguments, including the command and optional path overrides. If any help argument is present, this method returns usage output before command or option parsing so help remains available from any working directory.
  • standardOut
    Writer that receives success messages and help/usage output.
  • standardError
    Writer that receives invalid invocation usage and failure messages.
  • currentDirectory
    Working directory used to resolve default repository-relative paths after help handling.
  • cancellationToken
    Cancellation token propagated to generator operations.
  • verifyPackagesAsync
    Optional package artifact workflow override used by tests.
  • publishPrereleaseAsync
    Optional prerelease publish workflow override used by tests.
  • publishStableAsync
    Optional stable publish workflow override used by tests.
  • smokeInstallAsync
    Optional smoke install workflow override used by tests.
  • inspectPythonParserCandidateAsync
    Optional Python parser candidate-proof override used by tests.
  • preflightCommandRunner
    Optional external-command runner used by the exact-bundle runtime-preflight carrier. When omitted, the carrier launches its production consumer command through CliWrapCommandRunner .

Returns

0 when the command succeeds; otherwise a non-zero exit code.

Type

CommandLineOptions

Source

Parsed CLI options for a package-index command that may read and write package chooser and readiness dashboard outputs.

Parameters

  • Request
    Resolved package chooser manifest, chooser output, and readiness dashboard output request derived from command-line options.
  • ArtifactsOutputPath
    Resolved package artifact output directory.
  • ReportPath
    Resolved package artifact validation report path.
  • PackageVersion
    Optional package version supplied for package artifact verification.
  • ArtifactsInputPath
    Resolved package artifact input directory for protected publish jobs.
  • ArtifactManifestPath
    Resolved machine-readable package artifact manifest path.
  • CoverageProofWorkDirectory
    Resolved packaged coverage CLI consumer proof work directory.
  • CoverageProofReportPath
    Resolved packaged coverage CLI consumer proof report path.
  • DocsProofWorkDirectory
    Resolved packed Docs consumer proof work directory.
  • DocsProofReportPath
    Resolved packed Docs consumer proof report path.
  • PublishLogPath
    Resolved protected publish ledger path.
  • Source
    NuGet source URL used for publish and smoke install.
  • ApiKeyEnvironmentVariable
    Environment variable name that supplies the NuGet API key.
  • SmokeWorkDirectory
    Resolved isolated smoke install work directory.
  • SmokeReportPath
    Resolved smoke install report path.
  • BaseRef
    Optional fetched base ref or commit used only by the release-preparation witness command.
  • WitnessPath
    Optional explicit JSON witness destination used only by the release-preparation witness command.
  • PythonParserCandidatePackagePath
    Optional local candidate package supplied only to the parser-candidate inspection command.
  • PythonParserProofReportPath
    Machine-readable candidate-proof report path.
  • PreflightSourceCommit
    Source commit bound to candidate and published preflight receipts.
  • PreflightRunId
    Producer run identifier bound to candidate and published preflight receipts.
  • PreflightArtifactId
    Immutable producer artifact identifier bound to candidate and published preflight receipts.
  • DurableTemplateEvidenceDirectory
    Trusted exact-ID OS receipt directory required for template publication.
  • NativePgBin
    Optional resolved native PostgreSQL tool directory for installed-template smoke.
  • PreflightCandidateReceiptPath
    Retained candidate proof receipt required by production smoke-install.
  • CloudTasksBaselineRef
    Optional fetched target ref for historical Cloud Tasks acceptance; omitted uses the candidate source commit.
Method

Parse

CommandLineOptions Parse(string[] args, string currentDirectory)

Parses path-related CLI options into a resolved chooser request.

Parameters

  • args
    Arguments after the command verb.
  • currentDirectory
    Working directory used to resolve relative overrides.

Returns

The parsed command-line options.

Exceptions

  • PackageIndexException
    Thrown when an option is unknown or missing its required value.
Method

CreatePackageArtifactRequest

PackageArtifactRequest CreatePackageArtifactRequest(TailwindCommandOptions? tailwind = null)

Converts parsed CLI options into a package artifact request.

Returns

The package artifact request.

Exceptions

  • PackageIndexException
    Thrown when the required package version is missing.
Method

CreatePackagePublishRequest

PackagePublishRequest CreatePackagePublishRequest(TailwindCommandOptions? tailwind = null)

Converts parsed CLI options into a protected package publish request.

Returns

The package publish request.

Method

CreatePackageSmokeInstallRequest

PackageSmokeInstallRequest CreatePackageSmokeInstallRequest(bool requirePreflightProof = true)

Converts parsed CLI options into a package smoke install request.

Returns

The package smoke install request.

Method

CreateReleasePreparationWitnessRequest

ReleasePreparationWitnessRequest CreateReleasePreparationWitnessRequest()

Validates the dedicated read-only release-preparation witness options.

Returns

Resolved witness inputs.

Exceptions

  • PackageIndexException
    Thrown when either required witness option is absent.
Method

CreatePythonParserCandidateProofRequest

PythonParserCandidateProofRequest CreatePythonParserCandidateProofRequest()

Validates and converts the parser-candidate inspection options.

Returns

Resolved candidate archive and JSON report inputs.

Exceptions

  • PackageIndexException
    Thrown when the required local candidate archive option is absent.
Type

ReleasePreparationWitnessRequest

Source

Resolved inputs for the read-only package release-preparation witness command.

Parameters

  • Request
    Package-index generation request rooted at the checked-out repository.
  • BaseRef
    Fetched base ref or immutable base commit used to calculate the merge base.
  • WitnessPath
    Explicit JSON output path, normally outside the repository.
Type

DurableTemplateNativePostgreSql

Source

Owns one private native PostgreSQL cluster for the generated Durable template's ordinary local-run smoke.

Remarks

The caller must provide an absent, unique root under a private runner temporary directory. The returned connection string contains a generated bootstrap secret and is intended only for the local provisioning test. Disposal stops the owned server and removes its root only after the postmaster and selected port are verified stopped. Raw child output and PostgreSQL logs are never included in diagnostics.

Method

StartAsync

Task<DurableTemplateNativePostgreSql> StartAsync(string ownedRoot, IExternalCommandRunner commandRunner, CancellationToken cancellationToken = default, INativePostgreSqlToolDirectoryResolver? toolDirectoryResolver = null, INativePostgreSqlBootstrapRunner? bootstrapRunner = null, INativePostgreSqlRuntime? runtime = null, NativePostgreSqlBudgets? budgets = null, Action<NativePostgreSqlToolIdentity>? toolIdentityObserved = null)

Acquires the installed native toolchain, creates and starts a private SCRAM-authenticated cluster, and verifies that the generated bootstrap credential reaches the expected server.

Parameters

  • ownedRoot
    Absent unique cluster root beneath a caller-owned private temporary directory.
  • commandRunner
    Existing PackageIndex runner used for bounded tool/version and pg_ctl/psql calls.
  • cancellationToken
    Cancellation token. Owned resources are cleaned before cancellation returns.
  • toolDirectoryResolver
    Optional deterministic tool-directory seam for tests.
  • bootstrapRunner
    Optional redirected-stdin initdb seam for tests.
  • runtime
    Optional operating-system/process seam for tests.
  • budgets
    Optional lower setup and cleanup limits for deterministic tests; production ceilings cannot be raised.
  • toolIdentityObserved
    Optional observer called once after tool paths, versions, and hashes are validated and before the private cluster root is created. The identity contains acquired-tool evidence only; server-version fields remain null until server verification succeeds. Observer exceptions are not suppressed.

Returns

An owned running cluster. The caller must dispose it.

Exceptions

  • PackageIndexException
    Thrown when tools are missing/mixed/old, setup fails, or cleanup is uncertain.
Method

TryAuthenticateAsync

Task<bool> TryAuthenticateAsync(string password, CancellationToken cancellationToken = default)

Attempts a password-only psql probe without returning or retaining child diagnostics.

Parameters

  • password
    Password to test; it is projected only into this psql child's environment.
  • cancellationToken
    Cancellation token.

Returns

True only when PostgreSQL accepts the password and returns the expected probe value.

Remarks

Standalone probes have a five-second limit; setup additionally caps its probe by the shared deadline.

Method

DisposeWithBudgetAsync

ValueTask DisposeWithBudgetAsync(int cleanupBudgetRemainingMilliseconds)

Stops and removes this cluster using one caller-shared allowance that includes waiting for another disposal and is capped by the fixture's 20-second maximum. Callers coordinating generated-host and cluster teardown should pass the time remaining from their single cleanup clock.

Parameters

  • cleanupBudgetRemainingMilliseconds
    Remaining milliseconds for both disposal-lock acquisition and cleanup in the caller's shared budget.

Returns

A task that completes after verified stop and owned-root removal.

Exceptions

  • PackageIndexException
    The shared allowance expired before the disposal lock became available or before cleanup completed. The already-disposed case remains a no-op.
Property

ConnectionString

string ConnectionString { get; } Source

Gets the secret-bearing bootstrap connection string while this owned cluster is running.

Property

PsqlPath

string PsqlPath { get; } Source

Gets the absolute path to the validated psql binary.

Property

BinDirectory

string BinDirectory { get; } Source

Gets the resolved binary directory for the generated smoke child's native tool configuration.

Property

AdminConnectionString

string AdminConnectionString { get; } Source

Gets the bootstrap administrator connection string while the owned cluster is running.

Property

SetupBudgetRemainingMilliseconds

int SetupBudgetRemainingMilliseconds { get; } Source

Gets the remaining portion of the shared native setup budget, which defaults to 90 seconds.

Property

ToolIdentity

NativePostgreSqlToolIdentity ToolIdentity { get; set; } Source

Gets safe tool and server identity evidence with no credentials.

Property

OwnedRoot

string OwnedRoot { get; } Source

Gets the private owned root, for safe failure reports and ownership assertions.

Type

NativePostgreSqlToolIdentity

Source

Secret-free evidence for one same-directory native PostgreSQL toolchain and its running server.

Type

NativePostgreSqlBudgets

Source

Injectable setup and cleanup limits, always bounded by the approved production ceilings.

Remarks

Setup uses one elapsed clock across initdb, pg_ctl startup, ownership checks, authentication and server-version verification. Lower test limits apply to every setup request; a later phase receives only the remaining time, never a fresh phase budget. Tool acquisition remains fixed at five minutes and is outside this setup budget.

Method

Validate

void Validate()

Rejects non-positive test budgets and values above the production limits.

Property

Default

NativePostgreSqlBudgets Default { get; } Source

The production native smoke budgets: ninety seconds for setup and twenty for cleanup.

Type

INativePostgreSqlToolDirectoryResolver

Source

Resolves the native tool directory from the three supported smoke runners.

Method

ResolveAsync

Task<string> ResolveAsync(IExternalCommandRunner commandRunner, int timeoutMilliseconds, CancellationToken cancellationToken)

Resolves one installed PostgreSQL binary directory before the shared acquisition deadline.

Type

NativePostgreSqlToolDirectoryResolver

Source

Default Linux16, Windows PGBIN, and resolved Homebrew PostgreSQL16 directory resolver.

Type

FixedNativePostgreSqlToolDirectoryResolver

Source

Uses a workflow-resolved PostgreSQL bin directory without performing a second acquisition step.

Type

NativePostgreSqlBootstrapRequest

Source

Data needed to execute initdb with its bootstrap password supplied only through redirected stdin.

Type

NativePostgreSqlBootstrapResult

Source

Exit result for redirected-input initdb; raw process output is deliberately omitted.

Parameters

  • ExitCode
    The child process exit code, or -1 when it exceeded its time limit.
  • TimedOut
    Whether the child process exceeded its requested time limit.
  • ProcessTerminationVerified
    Whether initdb and its redirected output streams were confirmed stopped.
Type

INativePostgreSqlBootstrapRunner

Source

Runs initdb with no TTY, no console window, and bounded-memory output draining.

Method

RunAsync

Task<NativePostgreSqlBootstrapResult> RunAsync(NativePostgreSqlBootstrapRequest request, CancellationToken cancellationToken)

Runs initdb using exactly the request's redirected standard input and timeout.

Type

NativePostgreSqlBootstrapRunner

Source
Method

CreateStartInfo

ProcessStartInfo CreateStartInfo(NativePostgreSqlBootstrapRequest request, bool windowsPrompt)

Creates an isolated redirected-input launch, including PostgreSQL's Windows prompt fallback.

Parameters

  • request
    Owned executable, arguments and working directory; secret input is never an argument.
  • windowsPrompt
    Whether the target uses PostgreSQL's Windows console prompt implementation.

Returns

Child-only settings with inherited PostgreSQL variables removed and no console window.

Remarks

PostgreSQL opens CONIN$/CONOUT$ before consulting stdin on Windows. Its OSTYPE=msys fallback selects redirected streams without changing authentication, restricted-token behavior or parent environment. The explicit platform parameter is an internal launch-contract test seam, not a user setting.

Type

NativePostgreSqlProcessIdentity

Source

Observed identity parsed from the private cluster's PostgreSQL-owned postmaster.pid.

Type

INativePostgreSqlRuntime

Source

Injectable OS boundary for root/TTY checks, ephemeral ports, and postmaster ownership verification.

Method

ReserveLoopbackPort

int ReserveLoopbackPort()

Reserves an unused loopback TCP port and releases it before PostgreSQL startup.

Method

IsLoopbackPortListening

bool IsLoopbackPortListening(int port)

Gets whether a TCP listener currently accepts connections on the selected IPv4 loopback port.

Method

FindOwnedPostmaster

NativePostgreSqlProcessIdentity? FindOwnedPostmaster(string dataDirectory, string postgresPath, int port)

Finds and validates the live owned postmaster, or returns null when its PID file/process is absent.

Method

IsSameProcessAlive

bool IsSameProcessAlive(NativePostgreSqlProcessIdentity identity, string postgresPath)

Checks whether a previously observed process identity is still the same live PostgreSQL process.

Property

IsRunningAsRoot

bool IsRunningAsRoot { get; } Source

Whether the current Unix effective user is root.

Property

HasControllingTerminal

bool HasControllingTerminal { get; } Source

Whether this Unix process has a controlling terminal.

Type

NativePostgreSqlFailure

Source

Attaches and projects closed native stages without inspecting or retaining exception diagnostics.

Remarks

The private key prevents unrelated exception metadata from entering the receipt. The first annotation survives outer setup wrappers; only the fixed projection enters the existing version-one FailurePhase field. Exception types, messages, cancellation and cleanup behavior are unchanged.

Method

Annotate

void Annotate(Exception exception, NativePostgreSqlFailureStage stage)

Records a native boundary on an existing exception without replacing a more specific annotation.

Parameters

  • exception
    Original exception; its type and diagnostics remain owned by the caller.
  • stage
    Closed observation category; undefined values cannot produce receipt text.
Method

CopyAnnotation

void CopyAnnotation(Exception source, Exception target)

Copies only a supported private stage annotation to a sanitized setup wrapper.

Parameters

  • source
    Original failure; its message and other metadata are never read.
  • target
    Sanitized wrapper; an existing annotation is preserved.
Method

ReadReceiptPhase

string? ReadReceiptPhase(Exception exception)

Returns a fixed receipt identifier, or null when no supported native annotation exists.

Parameters

  • exception
    Failure to inspect without reading its message or other metadata.

Returns

A bounded native stage identifier, or null for an unannotated or unsupported category.

Remarks

Undefined enum values and arbitrary metadata never become receipt text.

Type

DurableTemplateReleaseEvidence

Source

Validates local receipts supplied by the existing trusted release workflow before credentials are read.

Remarks

These records are assertions within the immutable producer/workflow download boundary, not portable signatures. The caller supplies the expected full source revision independently; the receipt cannot select its own source. Every package hash must match the producer manifest and current archive, so evidence for a different candidate fails.

Method

Require

void Require(string? directory, string? sourceCommit, PackageArtifactManifest manifest, string artifactDirectory)

Requires three distinct successful native OS proofs and the Linux first-Work certificate.

Parameters

  • directory
    Exact trusted workflow evidence download directory.
  • sourceCommit
    Full source revision from the protected workflow context.
  • manifest
    Validated immutable producer package manifest.
  • artifactDirectory
    Exact producer archives; hashes are rechecked before publication.
Method

ReadTiming

DurableTemplateTimingProofReceipt ReadTiming(string path)

Reads a bounded timing receipt; duplicate, unknown and malformed fields fail closed.

Method

ValidateTiming

void ValidateTiming(DurableTemplateTimingProofReceipt receipt, string source, PackageArtifactManifest manifest, DurableTemplateTimingMode mode)

Reevaluates every sample against the independently expected producer and unchanged timing policy.

Method

Read

DurableTemplateProofReceipt Read(string path)

Reads at most 64KiB of schema-v1 evidence with depth16 and rejects duplicate or unknown fields.

Method

Validate

void Validate(DurableTemplateProofReceipt receipt, string source, PackageArtifactManifest manifest, string artifacts, string rid, bool firstWork)

Checks successful assertions, exact source/platform/content identity and every candidate archive.

Type

PackageArtifactWorkflow

Source

Coordinates package artifact packing and validation without publishing to NuGet.

Method

RunAsync

Task<PackageArtifactValidationReport> RunAsync(PackageArtifactRequest request, CancellationToken cancellationToken = default)

Packs and validates package artifacts.

Parameters

  • request
    Artifact workflow request.
  • cancellationToken
    Cancellation token propagated to external commands and file writes.

Returns

Successful validation report.

Method

TryDeleteProofWorkspace

void TryDeleteProofWorkspace(string proofWorkDirectory, Func<string, bool> directoryExists, Action<string> deleteDirectory)

Deletes a temporary proof workspace and tolerates cleanup failures after proof evidence has been published.

Parameters

  • proofWorkDirectory
    Temporary workspace to delete.
  • directoryExists
    Directory existence probe.
  • deleteDirectory
    Recursive directory deletion operation.
Method

WriteCoverageProofEvidenceAsync

Task WriteCoverageProofEvidenceAsync(string evidencePath, string contents, string trustedRootDirectory, CancellationToken cancellationToken, Action<string>? temporaryFileCreated = null)

Atomically publishes scrubbed coverage proof evidence without following an existing symbolic-link destination.

Parameters

  • evidencePath
    Final evidence path below the trusted artifact output directory.
  • contents
    Already-scrubbed JSON payload.
  • trustedRootDirectory
    Regular artifact output directory that bounds every evidence directory component.
  • cancellationToken
    Cancellation token for temporary-file creation.
  • temporaryFileCreated
    Optional narrow test seam invoked after the temporary file is closed and before the destination is replaced.

Returns

A task that completes after the temporary file has replaced a regular destination.

Type

PackageArtifactRequest

Source

Request for package artifact packing and validation.

Parameters

  • RepositoryRoot
    Absolute repository root.
  • ManifestPath
    Absolute package manifest path.
  • ArtifactsOutputPath
    Directory that receives produced .nupkg artifacts.
  • ReportPath
    Markdown validation report path.
  • PackageVersion
    Exact stable or prerelease package version to pack and validate. SemVer build metadata such as 1.2.3+sha is rejected because NuGet strips it from package identity.
  • ArtifactManifestPath
    Machine-readable validation manifest path for the publish workflow.
  • CoverageProofWorkDirectory
    Isolated work directory for the packaged coverage CLI consumer proof.
  • CoverageProofReportPath
    Standalone markdown report path for the packaged coverage CLI consumer proof.
  • DocsProofWorkDirectory
    Isolated work directory for the packed Docs consumer proof.
  • DocsProofReportPath
    Standalone markdown report path for the packed Docs consumer proof.
  • Source
    NuGet source used for third-party dependencies while first-party packages map to local artifacts.
  • RepositoryId
    Optional trusted numeric repository identity used to create release producer evidence.
  • ProducerRunId
    Optional trusted workflow run ID used to create release producer evidence.
  • ProducerAttempt
    Optional trusted producer attempt used to create release producer evidence.
  • SourceCommit
    Optional full source commit bound to the release producer evidence.
  • CloudTasksBaselineRef
    Optional historical acceptance target ref; the unique merge-base with the candidate is required. Omitted uses the candidate source snapshot.
Type

DurableTemplateTimingArtifact

Source

Immutable package identity bound to one timing series.

Parameters

  • PackageId
    First-party package ID.
  • Version
    Exact coordinated version.
  • Sha512
    Lowercase hexadecimal SHA-512 digest of the exact package archive (128 characters).
Type

DurableTemplateTimingProofRequest

Source

Expected source, package, cache, feed, and runner identity for one five-sample series.

Parameters

  • SeriesId
    Safe identifier unique to this complete series; corrected reruns use a new value.
  • Mode
    Primed or cold cache protocol.
  • FeedKind
    Candidate-local or promoted-public feed.
  • FeedIdentity
    Opaque safe feed identifier; never a URL containing credentials.
  • SourceCommit
    Full source revision bound by the workflow.
  • PackageVersion
    Exact coordinated template and package version.
  • RuntimeIdentifier
    Runner runtime identifier.
  • RunnerImage
    Workflow runner image identity.
  • SdkVersion
    Observed .NET 10 SDK version.
  • PostgreSqlImage
    Exact pinned PostgreSQL image reference.
  • PinnedPackageCacheClosureSha256
    Required primed package-cache inventory hash; null for cold.
  • StopwatchFrequency
    Monotonic timestamp frequency used for all sample timestamps.
  • Artifacts
    Complete first-party candidate/promoted artifact identities, without file paths.
Type

DurableTemplateTimingCommand

Source

One exact dotnet command observation, retaining only the argument-vector hash.

Parameters

  • Phase
    Fixed command phase; arbitrary phase text is not accepted.
  • ArgumentsSha256
    SHA-256 over the normalized executable and exact argument vector.
  • ElapsedSeconds
    Monotonic command duration.
  • ExitCode
    Observed child exit code.
  • OutputTruncated
    Whether either bounded output stream was truncated.
Type

DurableTemplateTimingCheckpoints

Source

Checkpoint assertions emitted only after the real generated first-Work test proves each condition.

Parameters

  • AuthorizedActivation
    Authorized empty activation was accepted.
  • TerminalWork
    Persisted Work reached terminal completion.
  • ReadinessTransition
    Readiness changed from NotStarted to Healthy.
  • ExportedActivity
    The activation activity was exported by the SDK.
Type

DurableTemplateTimingSample

Source

Safe, source-bound observation from one serial install/create/test sample.

Parameters

  • Ordinal
    One-based position in the five-sample serial run.
  • SampleId
    Unique safe sample identity.
  • SeriesId
    Series identity matching the request.
  • Mode
    Cache mode matching the request.
  • FeedKind
    Feed kind matching the request.
  • FeedIdentity
    Opaque feed identity matching the request.
  • SourceCommit
    Full source revision observed for this sample.
  • PackageVersion
    Exact coordinated package version observed for this sample.
  • ArtifactSetSha256
    Stable hash of the complete package ID/version/SHA-512 set.
  • RuntimeIdentifier
    Runner runtime identifier observed for this sample.
  • RunnerImage
    Runner image identity observed for this sample.
  • SdkVersion
    .NET SDK version observed for this sample.
  • DockerDaemonIdentity
    SHA-256 identity of the Docker daemon used by this sample.
  • DockerImagePresentAtStart
    Whether the pinned image existed before the sample clock started.
  • ImageDigestAtStart
    Observed pinned image digest before the clock, empty when absent.
  • ImageDigestAfter
    Observed pinned image digest after the proof.
  • PackageCacheRootIdentity
    Opaque SHA-256 identity of this sample's private package cache root.
  • PackageCacheClosureSha256
    Hash of the package-cache inventory before the sample clock.
  • PackageCacheEmptyAtStart
    Whether the private global-packages cache was empty at start.
  • HttpCacheEmptyAtStart
    Whether the private NuGet HTTP cache was empty at start.
  • SharedCachePurged
    Must remain false; shared caches are never purged by timing evidence.
  • ProjectIdentity
    Opaque SHA-256 identity of the generated project root.
  • DatabaseIdentity
    Opaque SHA-256 identity of the disposable database.
  • StartTimestamp
    Monotonic sample start timestamp.
  • EndTimestamp
    Monotonic sample end timestamp, after owned cleanup.
  • PackageSetupRestoreBuildSeconds
    Measured install/create/restore/build group duration.
  • Commands
    The three documented command observations in exact order.
  • Checkpoints
    Four first-Work assertions from the final test command.
  • CleanupComplete
    Whether every sample-owned resource was cleaned up.
  • Succeeded
    Whether the workload and proof assertions completed successfully.
  • FailureCode
    Empty on success; otherwise a short safe code without diagnostics or secrets.
Type

DurableTemplateTimingSampleResult

Source

One retained attempt and its fixed safe validation codes.

Parameters

  • Sample
    Original bounded observation, including failed attempts.
  • ElapsedSeconds
    Elapsed monotonic wall time, or null for invalid timestamps.
  • ValidationFailures
    Stable failure codes; never raw command output or exception text.
Type

DurableTemplateTimingProofReceipt

Source

Safe evaluation of a complete five-sample timing series.

Parameters

  • SchemaVersion
    Receipt schema version.
  • SeriesId
    Unique series identity.
  • Mode
    Cache mode used.
  • FeedKind
    Candidate-local or promoted-public feed.
  • FeedIdentity
    Opaque feed identity, without credentials or raw URL.
  • SourceCommit
    Full source revision bound by every sample.
  • PackageVersion
    Exact coordinated package version.
  • ArtifactSetSha256
    Stable hash of all artifact identities.
  • RuntimeIdentifier
    Runner runtime identifier.
  • RunnerImage
    Workflow runner image identity.
  • SdkVersion
    Observed .NET 10 SDK version.
  • PostgreSqlImage
    Pinned PostgreSQL image reference.
  • Artifacts
    Exact artifact IDs, versions, and SHA-512 hashes.
  • Samples
    Every supplied attempt, including failed and malformed observations.
  • MedianSeconds
    Third sorted elapsed time when five valid durations exist.
  • NearestRankP95Seconds
    Fifth sorted elapsed time when five valid durations exist.
  • PerformanceGatePassed
    Primed numerical gate result; null for cold diagnostic series.
  • Succeeded
    True only for five valid samples and all applicable proof gates.
  • FailureCode
    Stable summary code; never raw diagnostics.
  • StopwatchFrequency
    Monotonic clock frequency used to re-evaluate sample timestamps.
Type

DurableTemplateTimingProof

Source

Validates the five serial timing observations collected by the release workflow. It never launches a command, provisions a daemon, purges a cache, or writes a receipt; the workflow owns those actions and supplies safe records.

Method

Evaluate

DurableTemplateTimingProofReceipt Evaluate(DurableTemplateTimingProofRequest request, IReadOnlyList<DurableTemplateTimingSample> samples)

Evaluates one series while retaining all supplied attempts. Failed runs remain in the receipt and are never removed or retried into the same series.

Parameters

  • request
    Expected immutable provenance and clock contract.
  • samples
    Safe observations in execution order; the workflow must run them serially.

Returns

A safe receipt. A failed or incomplete series can never pass the primed gate.

Method

ComputeCommandArgumentsSha256

string ComputeCommandArgumentsSha256(string fileName, IReadOnlyList<string> arguments)

Hashes a command identity and exact argument vector without retaining the original tokens.

Parameters

  • fileName
    Executable path or name.
  • arguments
    Exact child argument tokens; only their SHA-256 is returned.

Returns

Lowercase SHA-256 of a stable JSON array containing normalized executable and arguments.

Method

ComputeArtifactSetSha256

string ComputeArtifactSetSha256(IReadOnlyList<DurableTemplateTimingArtifact> artifacts)

Computes stable SHA-256 identity for the complete exact archive set.

Parameters

  • artifacts
    Artifacts sorted by package ID before hashing.

Returns

Lowercase SHA-256 of package ID, version, and SHA-512 rows.

Type

DurablePreflightArtifactProof

Source

Consumes the exact candidate NuGet bundle with the PostgreSQL runtime-preflight controller and checks every public-feed package payload against that bundle before repeating the proof.

Method

RunCandidateAsync

Task<DurablePreflightArtifactProofResult> RunCandidateAsync(DurablePreflightArtifactProofRequest request, CancellationToken cancellationToken)

Runs the shared proof over a downloaded immutable candidate bundle. The manifest is promoted only after the controller exits successfully and its combined receipt binds the expected run, artifact, and bytes.

Method

ValidateAndPromoteCandidateManifestAsync

Task ValidateAndPromoteCandidateManifestAsync(DurablePreflightArtifactProofRequest request, string candidateReceiptPath, string repositoryRoot, CancellationToken cancellationToken)

Revalidates a retained candidate receipt and promotes its approved manifest beside the immutable downloaded package bundle. Used by protected release jobs before they consume the bundle.

Method

RunPublishedAsync

Task<DurablePreflightArtifactProofResult> RunPublishedAsync(DurablePreflightArtifactProofRequest request, string candidateReceiptPath, string restoredPackagesPath, string publicFeedReceiptPath, CancellationToken cancellationToken)

Compares every clean public-feed ZIP entry with the approved candidate, excluding only the root NuGet signature envelope. ZIP packaging metadata may differ. The shared proof consumes exact candidate archives so its manifest hashes remain authoritative; the carrier records both candidate and public archive hashes. Signature trust is the NuGet restore's responsibility, not a claim made by this payload comparison.

Method

CompareRestoredPackageBytesAsync

Task<IReadOnlyDictionary<string, string>> CompareRestoredPackageBytesAsync(string candidateDirectory, string artifactManifestPath, string restoredPackagesPath, string publicArtifactsDirectory, CancellationToken cancellationToken)

Requires each manifest package's exact ZIP entry names and uncompressed contents, except one optional root .signature.p7s entry. Rejects duplicate entries, malformed archives and changes to any other entry. Independently compares the extracted provider recipe, stages candidate archives plus the original manifest, and returns raw public archive SHA-256 values. Callers must validate the staged candidate manifest binding.

Method

ValidateGuardLossNegativeProof

void ValidateGuardLossNegativeProof(JsonElement root, DurablePreflightExpectedFixture fixture)

Requires independently observed failed lane and activation windows. A successful scenario receipt cannot replace backend termination, cancellation, drained children/host, closed admission, released sessions, and the withheld receipts from the controller's real guard-loss probes.

Method

PackagePayloadsMatchAsync

Task<bool> PackagePayloadsMatchAsync(string left, string right, CancellationToken cancellationToken)

Compares signed or unsigned archive contents without treating a signature envelope as payload.

Method

UniquePayloadEntries

Dictionary<string, ZipArchiveEntry> UniquePayloadEntries(ZipArchive archive)

Rejects ambiguous duplicate names, including signatures, before excluding the sole signature entry.

Method

StreamsAreByteIdenticalAsync

Task<bool> StreamsAreByteIdenticalAsync(Stream leftStream, Stream rightStream, CancellationToken cancellationToken)

Compares entry streams in bounded buffers, allowing different underlying short-read boundaries.

Type

DurablePreflightArtifactProofRequest

Source

One exact candidate/public feed proof invocation.

Type

DurablePreflightBundleIdentity

Source

Validated package and manifest hashes observed before invoking the combined proof.

Type

DurablePreflightExpectedFixture

Source

Expected immutable fixture identities used by the controller and strict receipt validator.

Type

ValidatedDurablePreflightReceipt

Source

Validated final combined receipt summary returned by the exact-package controller.

Type

DurablePreflightArtifactProofResult

Source

Carrier result for receipt rendering and workflow summaries.

Type

DurablePreflightPublicFeedReceipt

Source

Version-2 public-feed evidence of package payload identity excluding only NuGet's signature envelope. Candidate and public maps contain every manifest package's raw archive SHA-256; the shared proof and original manifest retain candidate byte identity. This receipt does not independently attest signature authenticity.

Type

DurablePreflightArtifactProofCommandOptions

Source

Strict command-line request for candidate or published-feed preflight artifact consumption.

Type

DurableTemplateArtifactContract

Source

Checks the durable-worker template package and generated project against its reviewed content contract.

Remarks

This validator is deliberately separate from staging: staging creates a private candidate copy, while this type verifies the exact packed artifact and a native template-engine output. The artifact boundary is bounded before parsing or inflation, and the generated boundary ignores only ordinary build/test output directories.

Method

ValidateArchive

void ValidateArchive(string nupkgPath, string exactVersion, bool allowSigningEnvelope = false)

Validates the exact NuGet archive, template manifest, and authored project graph.

Parameters

  • nupkgPath
    Path to the candidate .nupkg ; it is opened read-only and never extracted.
  • exactVersion
    The coordinated candidate version required in package metadata and AppSurface references.
  • allowSigningEnvelope
    Allows one bounded root .signature.p7s entry for public replay only; it does not verify authenticity.

Exceptions

  • PackageIndexException
    The file is unsafe, malformed, outside a bound, or differs from the reviewed shape.

Remarks

The archive is read-only and never extracted. Defaults are 32 MiB compressed, 256 entries, 16 MiB total actual inflation, 2 MiB per entry, 1,024 UTF-8 bytes per path, and 1 MiB/depth 16 for JSON. The exact allowlist is the generated content shape plus the native manifest and required NuGet metadata; the manifest is archive-only because dotnet new consumes it instead of copying it to generated output. Paths compare case-insensitively, and optional directory records must be ancestors of an allowlisted file. Exactly one core-properties record is required: the case-sensitive path package/services/metadata/core-properties/nuget.psmdcp , or the same directory with a legacy hexadecimal/hyphen basename and lowercase .psmdcp suffix. Other names remain invalid.

Method

ComputeGeneratedContentSha256

string ComputeGeneratedContentSha256(string templateArchive, string projectName, bool allowSigningEnvelope = false)

Computes the native generated-content receipt hash from one validated archive snapshot.

Parameters

  • templateArchive
    Candidate template .nupkg ; archive bytes are read within the contract bounds.
  • projectName
    The simple C# identifier passed to dotnet new -n .
  • allowSigningEnvelope
    Allows one bounded root signing envelope for replay; does not verify authenticity.

Returns

The lowercase SHA-256 used by the consumer proof over generated relative paths and bytes.

Exceptions

  • PackageIndexException
    The archive, requested name, or reviewed generated content is invalid.

Remarks

The nuspec version supplies the graph's exact AppSurface pin for this API because its signature intentionally has no separate version argument. The bounded archive reader validates the manifest and full content contract before hashing. Hash order mirrors the consumer's sorted depth-first relative-path enumeration; only GeneratedPaths is included, so the manifest and package metadata never affect generated identity. UTF-8 source text is decoded strictly and re-encoded without newline normalization, preserving authored BOM and CR/LF bytes while applying the same source-name replacement to file paths and content. When allowSigningEnvelope is true, the envelope is ignored for generated-content hashing; callers must bind the complete archive digest separately, and this method makes no authenticity claim.

Method

ValidateGenerated

void ValidateGenerated(string root, string projectName, string exactVersion)

Validates a generated project after native template expansion and any ordinary build/test run.

Parameters

  • root
    Generated solution root; reads only paths within this root.
  • projectName
    The simple C# identifier supplied to dotnet new -n .
  • exactVersion
    The exact AppSurface package version expected in the generated graph.

Exceptions

  • PackageIndexException
    The generated inventory, paths, secrets, or project graph violate the contract.

Remarks

The exact generated allowlist excludes the native manifest. Only bin , obj , and TestResults directories are ignored, and only after checking them for reparse points. This permits a built consumer without hiding authored local settings, repository references, or packaging debris. Per-file and total authored bytes use the same 2 MiB and 16 MiB limits as archive inflation.

Method

ValidateProjectVersions

void ValidateProjectVersions(string projectRoot, string exactVersion)

Validates coordinated and third-party package pins and confines project references to the supplied root.

Parameters

  • projectRoot
    Authored, staged, or generated content root.
  • exactVersion
    Exact candidate version required for each direct AppSurface package reference.

Exceptions

  • PackageIndexException
    A reference is unpinned, mismatched, malformed, or escapes the root.

Remarks

The graph must enable Central Package Management in its root Directory.Packages.props ; project-level Version and VersionOverride values are rejected, including when they match a central pin. All package versions are fixed semantic versions, and every AppSurface central pin equals exactVersion . Project references resolve only to files in the supplied content root. This method validates the graph only; the release stager owns the allowlisted central-pin substitutions.

Method

NormalizeArchivePath

string NormalizeArchivePath(string path)

Normalizes one untrusted slash-separated archive path and rejects portable filesystem aliases.

Parameters

  • path
    ZIP entry path without a trailing directory slash.

Returns

The validated path in slash-separated form.

Exceptions

  • PackageIndexException
    The path is rooted, aliased, too long, or invalid on a supported OS.

Remarks

Backslashes, empty/dot segments, parent traversal, colon, trailing dot/space, control characters, and device names are rejected.

Type

DurableTemplateFirstWorkDiagnostic

Source

A diagnostic-only projection of a failed generated first-work test's known phase and error category.

Parameters

  • Phase
    A closed phase from the reviewed first-work fixture.
  • Code
    A known exception category, or Other; never an arbitrary exception type name.
  • Cleanup
    Known cleanup observations, or unknown when the marker cannot establish one.

Remarks

This projection never establishes success or changes test, command, timing or coverage requirements. Raw messages, stack locations, arguments and process output remain in owned scratch and are not retained.

Method

Read

DurableTemplateFirstWorkDiagnostic? Read(string? output)

Reads at most one known marker from bounded test output, withholding ambiguous or invalid markers.

Parameters

  • output
    Output from a failed, identity-matched first-work test inside the bounded TRX document.

Returns

A closed diagnostic value, or null; absence never changes the failed test outcome.

Property

SetupOperation

string? SetupOperation { get; init; } Source

Gets an optional closed setup-operation label derived from reviewed fixture method names.

Remarks

Only PostgreSQL fixture setup can carry this label. No reviewed frame or conflicting specific operations omit it. Owned setup includes container startup and provisioning; this observation cannot establish the underlying cause. No method names, stack frames or arbitrary location text are retained, and the label never authorizes success.

Type

IDocsPackageConsumerProofWorkflow

Source

Runs the pre-publish restore proof for the packed AppSurface Docs package.

Method

RunAsync

Task<DocsPackageConsumerProofReport> RunAsync(DocsPackageConsumerProofRequest request, PackageArtifactValidationReport validationReport, CancellationToken cancellationToken)

Restores the validated Docs package from local artifacts in a clean consumer project and verifies its resolved graph.

Parameters

  • request
    Proof paths, package version, and third-party package source.
  • validationReport
    Validated artifacts produced by the package artifact workflow.
  • cancellationToken
    Cancellation token.

Returns

A structured report containing command and graph-verification evidence.

Type

DocsPackageConsumerProofWorkflow

Source

Proves that a clean package consumer resolves the packed Docs artifact and the reviewed stable parser and sanitizer graph.

Remarks

The generated consumer is intentionally independent of the repository Docs consumer fixture, which uses project references. It has its own package lock file and configuration with a local-only mapping for first-party packages. The public source is restricted to the exact non-first-party package ids represented by the committed locks for the validated Docs first-party closure, so a newly published or unintended first-party package cannot satisfy the restore. Empty local Directory.Build.props and Directory.Build.targets files also prevent repository-wide build policy from affecting the generated consumer.

The proof does not build an application: restoring and inspecting project.assets.json is the relevant package contract. It confirms that Docs, AngleSharp, AngleSharp.Css, and HtmlSanitizer resolve as packages at their exact expected versions.

Method

SelectDocsPackage

DocsPackageConsumerProofSelectedArtifact SelectDocsPackage(PackageArtifactValidationReport report, string packageVersion)

Selects the validated Docs artifact that the consumer proof restores.

Parameters

  • report
    Validation report produced from the just-packed artifact directory.
  • packageVersion
    Exact package version expected in the selected artifact file name.

Returns

The selected artifact and its SHA-512 hash.

Exceptions

  • PackageIndexException
    Thrown when the report does not contain exactly one existing Docs package artifact matching packageVersion .
Method

RenderConsumerDirectoryPackagesProps

string RenderConsumerDirectoryPackagesProps()

Renders the isolated consumer's central package-management boundary.

Returns

Props that disable inherited central package management and enable the consumer lock file.

Method

RenderConsumerProject

string RenderConsumerProject(string packageVersion)

Renders the clean package consumer project.

Parameters

  • packageVersion
    Exact Docs package version to restore.

Returns

Consumer project XML.

Method

RenderMappedNuGetConfig

string RenderMappedNuGetConfig(string localSource, string nugetOrgSource, IEnumerable<string> thirdPartyPackageIds)

Renders source mapping that permits first-party packages only from local artifacts and enumerates allowed public packages.

Parameters

  • localSource
    Directory containing freshly packed first-party artifacts.
  • nugetOrgSource
    Source used for reviewed third-party package identities.
  • thirdPartyPackageIds
    Exact third-party package ids allowed from the public source.

Returns

NuGet configuration XML with package-source mapping.

Exceptions

  • ArgumentException
    Thrown when no third-party package ids are supplied or an id is a package-source mapping pattern.
Method

ReadPackedDocsThirdPartyPackageIds

IReadOnlyList<string> ReadPackedDocsThirdPartyPackageIds(string repositoryRoot, PackageArtifactValidationReport validationReport)

Reads the public package identities for the validated, packed Docs first-party closure.

Parameters

  • repositoryRoot
    Repository root that contains the committed lock files for packed first-party projects.
  • validationReport
    Validated package report that establishes the first-party package closure.

Returns

Sorted, deduplicated third-party package ids.

Exceptions

  • PackageIndexException
    Thrown when the report does not contain the complete Docs closure, or a required committed lock file is absent or malformed.

Remarks

The traversal follows the validator-confirmed first-party dependency graph from Docs and scans each participating project's lock file for package entries. This captures public dependencies introduced by packed first-party packages (for example Microsoft.Extensions.* ) that do not appear in the Docs project's source-only lock graph.

Method

ReadThirdPartyPackageIdsFromLockFile

IReadOnlyList<string> ReadThirdPartyPackageIdsFromLockFile(string lockFilePath)

Reads package (not project) identities from one committed project lock file.

Parameters

  • lockFilePath
    Committed lock file path.

Returns

Third-party package identities represented by lock entries.

Exceptions

  • PackageIndexException
    Thrown when the lock file is absent or malformed.
Method

VerifyConsumerGraph

DocsPackageConsumerGraphVerification VerifyConsumerGraph(string assetsFilePath, string lockFilePath, string packageVersion)

Inspects a generated consumer's assets and lock files for the packed Docs package and stable dependency graph.

Parameters

  • assetsFilePath
    Generated project.assets.json path.
  • lockFilePath
    Generated consumer lock file path.
  • packageVersion
    Expected Docs package version.

Returns

Verified resolved package identities and paths.

Exceptions

  • PackageIndexException
    Thrown when either generated input is absent, malformed, or resolves a wrong package identity.
Type

DocsPackageConsumerProofRequest

Source

Request for an isolated packed Docs consumer restore proof.

Parameters

  • RepositoryRoot
    Repository root used for safety checks and lock-graph discovery.
  • ArtifactsDirectory
    Directory containing freshly validated local package artifacts.
  • PackageVersion
    Exact Docs package version under proof.
  • WorkDirectory
    Isolated work directory that can be deleted and recreated.
  • Source
    Public source used only for reviewed third-party package ids.
Type

DocsPackageConsumerProofSelectedArtifact

Source

Identity and hash of the validated Docs artifact selected for consumer restore.

Parameters

  • PackageId
    Docs package id.
  • ProjectPath
    Project that produced the selected artifact.
  • ArtifactPath
    Validated local package artifact path.
  • Sha512
    Base64 SHA-512 hash of the selected artifact.
Type

DocsPackageConsumerProofResolvedPackage

Source

One resolved package identity verified in the generated consumer's assets graph.

Parameters

  • Id
    Package id.
  • Version
    Exact resolved package version.
Type

DocsPackageConsumerGraphVerification

Source

Structural proof that the generated consumer resolved all required package identities.

Parameters

  • AssetsFilePath
    Generated NuGet assets file inspected by the proof.
  • LockFilePath
    Generated consumer lock file verified in locked mode.
  • ResolvedPackages
    Docs and parser/sanitizer package identities verified as packages.
Type

DocsPackageConsumerProofCommandResult

Source

One command in the packed Docs consumer proof ledger.

Parameters

  • OperationName
    Human-readable operation name.
  • FileName
    Executable name.
  • Arguments
    Command arguments.
  • WorkingDirectory
    Command working directory.
  • ExitCode
    Observed exit code.
  • Succeeded
    Whether the command exited successfully.
  • FailureReason
    Failure details when the command did not succeed.
  • Duration
    Measured command duration.
  • StandardOutputPath
    Captured stdout log path.
  • StandardErrorPath
    Captured stderr log path.
  • StandardOutput
    Captured stdout.
  • StandardError
    Captured stderr.
Type

DocsPackageConsumerProofReport

Source

Structured evidence emitted by the packed Docs consumer proof.

Parameters

  • PackageVersion
    Exact Docs package version under proof.
  • WorkDirectory
    Isolated proof workspace.
  • Source
    Public package source.
  • SelectedArtifact
    Validated Docs package selected for restore.
  • NuGetConfigPath
    Generated source-mapping configuration.
  • ConsumerProjectPath
    Generated consumer project.
  • ConsumerLockFilePath
    Generated consumer lock file.
  • AssetsFilePath
    Generated consumer assets file.
  • ThirdPartyPackageIds
    Exact third-party package ids permitted from the public source.
  • LogsDirectory
    Command stdout and stderr log directory.
  • Commands
    Command ledger.
  • GraphVerification
    Resolved graph evidence, when restore and inspection succeeded.
  • FirstFailure
    First failure, or empty when proof succeeded.
  • ReproduceCommand
    Command that reruns the package verifier with the same proof directory.
Method

Failed

DocsPackageConsumerProofReport Failed(string packageVersion, string workDirectory, string source, string firstFailure, DocsPackageConsumerProofSelectedArtifact? selectedArtifact = null)

Builds a report for failures that occur before the proof workspace is fully initialized.

Parameters

  • packageVersion
    Package version under proof.
  • workDirectory
    Requested proof directory.
  • source
    Requested public source.
  • firstFailure
    Failure message.
  • selectedArtifact
    Selected artifact, if selection already succeeded.

Returns

Failed proof report.

Property

Succeeded

bool Succeeded { get; } Source

Gets whether every command and graph verification succeeded.

Type

DocsPackageConsumerProofReportRenderer

Source

Renders packed Docs consumer proof evidence for standalone and aggregate package reports.

Method

RenderMarkdown

string RenderMarkdown(DocsPackageConsumerProofReport report)

Renders a standalone markdown report.

Parameters

  • report
    Proof report.

Returns

Markdown content.

Method

RenderSection

void RenderSection(StringBuilder builder, DocsPackageConsumerProofReport report)

Appends proof evidence to an aggregate package report.

Parameters

  • builder
    Destination markdown builder.
  • report
    Proof report.
Type

DocsPackageConsumerProofContext

Source

Runtime paths and inputs shared by the packed Docs consumer proof.

Type

PackageProofWorkDirectory

Source

Safely recreates isolated package-consumer proof workspaces.

Method

RequireDisjoint

void RequireDisjoint(string firstDirectory, string secondDirectory)

Requires two package-consumer proof workspaces to be disjoint before either is recreated.

Parameters

  • firstDirectory
    First proof workspace.
  • secondDirectory
    Second proof workspace.

Exceptions

  • PackageIndexException
    Thrown when either workspace is the other workspace or one contains the other.
Method

Prepare

void Prepare(string workDirectory, string repositoryRoot, string artifactsDirectory)

Deletes and recreates an isolated package-consumer proof workspace after rejecting unsafe deletion targets.

Parameters

  • workDirectory
    Workspace that may be recursively deleted and recreated.
  • repositoryRoot
    Repository root that must not be deleted or contained by the work directory.
  • artifactsDirectory
    Package artifact directory that must not be deleted or contained by the work directory.

Exceptions

  • PackageIndexException
    Thrown when workDirectory is a filesystem root, the repository root, the artifact directory, the user's home directory, a non-artifact directory inside the repository, or a parent of the repository or artifact directory.

Remarks

All compared paths are normalized and trailing directory separators are trimmed before comparison. This prevents bypasses such as passing the repository root with a trailing slash before the recursive delete runs. A repository-local proof workspace is allowed only beneath the configured artifact directory, which preserves the default proof layout without allowing cleanup to remove source or Git metadata.

Type

CoverageCliConsumerProofSemanticValidator

Source

Validates the bounded Cobertura contract used by the packaged default-collector consumer proof.

Remarks

This validator deliberately does not reuse the CLI's private project-slug allocator. The CLI emits one adjacent coverage-project.json manifest for every selected project; this reader binds the known consumer project to its sibling raw report, preserves that exact report into the merge input, and verifies retained semantic facts in the fan-in result. It is not a general Cobertura parser or an assertion about the MSBuild compatibility driver.

Method

ValidateRaw

CoverageCliConsumerProofSemanticProof ValidateRaw(string coverageRunDirectory)

Selects and validates the raw artifact belonging to the known default-collector fixture project.

Parameters

  • coverageRunDirectory
    The default collector's coverage-run output directory.

Returns

Raw selection, parsed semantic facts, and deterministic failures.

Method

ValidateMerged

CoverageCliConsumerProofSemanticProof ValidateMerged(CoverageCliConsumerProofSemanticProof rawProof, string copiedShardPath, string mergedCoveragePath)

Verifies the byte-preserved selected shard and independently validates the merged fan-in report.

Parameters

  • rawProof
    The result returned from ValidateRaw .
  • copiedShardPath
    The shard copied from the selected raw report into fan-in input.
  • mergedCoveragePath
    The merged Cobertura report produced by coverage merge.

Returns

Raw and merged semantic proof with raw-first deterministic failure ordering.

Type

CoverageCliConsumerProofRawArtifact

Source

Manifest-bound raw report selected for the packaged default-collector proof.

Type

CoverageCliConsumerProofSemanticOutcome

Source

Public-safe outcome of one semantic coverage artifact validation stage.

Type

CoverageCliConsumerProofCoverageFacts

Source

Bounded semantic facts retained by the package proof. These are intentionally not raw XML.

Type

CoverageCliConsumerProofFailure

Source

One coded package coverage proof failure.

Type

CoverageCliConsumerProofSemanticProof

Source

Complete semantic default-collector proof state, including a selected raw artifact when selection succeeded.

Type

PythonParserCandidateProofWorkflow

Source

Performs a bounded, static inspection of an explicitly evaluated Python parser package candidate.

Remarks

This workflow deliberately never restores, builds, loads, or executes candidate package content. A local feed and a child process are not a security boundary for untrusted NuGet build assets, managed assemblies, analyzers, or native libraries. A future candidate that passes this static gate needs a separately approved, sandboxed execution design before runtime initialization can become acceptance evidence.

Method

RunAsync

Task<PythonParserCandidateProofReport> RunAsync(PythonParserCandidateProofRequest request, CancellationToken cancellationToken)

Inspects the supplied archive and writes deterministic static-gate evidence.

Parameters

  • request
    Repository, candidate archive, and report inputs.
  • cancellationToken
    Cancellation token propagated to file operations.

Returns

A machine-readable record of archive, native-asset, and provenance evidence.

Exceptions

  • PackageIndexException
    Thrown when the request has unsafe or incomplete paths.
Method

ExceedsUncompressedArchiveByteLimit

bool ExceedsUncompressedArchiveByteLimit(long currentTotal, long nextEntryLength)

Determines whether adding one declared archive-entry length would exceed the static inspection limit.

Parameters

  • currentTotal
    Already accepted declared uncompressed bytes.
  • nextEntryLength
    Declared uncompressed bytes for the next archive entry.

Returns

true when the next entry must not be accepted.

Type

PythonParserCandidateProofRequest

Source

Inputs for the static Python parser candidate proof.

Type

PythonParserCandidateProofReport

Source

Archive and provenance evidence for one parser candidate.

Property

IsEligibleForFurtherReview

bool IsEligibleForFurtherReview { get; } Source

Gets whether the automated static checks have no rejection reason. A true value only permits further review; it is not legal or runtime-execution approval.

Type

PythonParserCandidateArchiveEvidence

Source

Immutable static inspection result for the supplied candidate archive.

Property

HasCompleteProvenanceMetadata

bool HasCompleteProvenanceMetadata { get; } Source

Gets whether the archive declares the minimum license and source provenance fields for later human review.

Type

PythonParserCandidateNuspecMetadata

Source

NuGet metadata retained as provenance evidence without treating it as legal approval.

Type

PythonParserCandidateProvenanceReviewEvidence

Source

Explicit boundary between machine-recorded provenance facts and human redistribution approval.

Type

PythonParserNativeRuntimeEvidence

Source

Full native asset inventory declared for one runtime identifier.

Property

NativeFileCount

int NativeFileCount { get; } Source

Gets the number of enumerated native asset paths.

Type

PackagePayloadInventoryLoader

Source

Loads the redistributed package payload inventory used by verify-packages .

Method

LoadAsync

Task<PackagePayloadInventory> LoadAsync(string repositoryRoot, CancellationToken cancellationToken = default)

Reads the repository-owned payload inventory from its default location.

Parameters

  • repositoryRoot
    Absolute repository root used to resolve the inventory path.
  • cancellationToken
    Cancellation token used while reading the file.

Returns

The parsed redistributed payload inventory.

Method

Parse

PackagePayloadInventory Parse(string content, string displayPath = DefaultRelativePath)

Parses payload inventory YAML content.

Parameters

  • content
    YAML inventory content.
  • displayPath
    Path shown in validation errors.

Returns

The parsed inventory.

Method

ResolveInventoryPath

string ResolveInventoryPath(string repositoryRoot, string relativePath)

Resolves the repository-relative payload inventory path under the repository root.

Parameters

  • repositoryRoot
    Absolute repository root used to resolve the inventory path.
  • relativePath
    Repository-relative inventory path.

Returns

The absolute inventory path.

Type

PackagePayloadInventory

Source

Repository-owned contract for redistributed package payload notice, audit, and generated evidence.

Method

Validate

void Validate(string displayPath)

Validates the parsed inventory shape before package-specific evidence checks run.

Parameters

  • displayPath
    Path shown in validation errors.
Property

SchemaVersion

int SchemaVersion { get; init; } Source

Gets the inventory schema version. Version 1 is the only supported v1 contract.

Property

Notices

List<PackagePayloadNoticeRecord> Notices { get; init; } Source

Gets third-party payload declarations that require package notices and provenance evidence.

Property

Audits

List<PackagePayloadAuditRecord> Audits { get; init; } Source

Gets narrow audit records for generated-first-party or otherwise non-notice payload evidence.

Type

PackagePayloadNoticeRecord

Source

Third-party redistributed payload evidence that requires package notice coverage.

Property

Id

string Id { get; init; } Source

Gets the stable inventory record id.

Property

PackageId

string PackageId { get; init; } Source

Gets the package id that must contain the declared payload.

Property

Component

string Component { get; init; } Source

Gets the redistributed component name shown in package reports.

Property

Version

string Version { get; init; } Source

Gets the redistributed component version.

Property

License

string License { get; init; } Source

Gets the redistributed component license expression or short name.

Property

SourceUrl

string SourceUrl { get; init; } Source

Gets the upstream source or project URL for maintainer review.

Property

PayloadPatterns

List<string> PayloadPatterns { get; init; } Source

Gets package entry glob patterns that identify the redistributed payload.

Property

NoticePaths

List<string> NoticePaths { get; init; } Source

Gets package entry paths that must contain the third-party notice text.

Property

Markers

List<string> Markers { get; init; } Source

Gets marker strings that must appear in at least one notice file.

Property

SourcePaths

List<string> SourcePaths { get; init; } Source

Gets optional source files that must exist in the repository for this evidence.

Property

VersionSourcePath

string? VersionSourcePath { get; init; } Source

Gets an optional repository file whose content must contain VersionSourceContains .

Property

VersionSourceContains

string? VersionSourceContains { get; init; } Source

Gets text that must appear in VersionSourcePath when the source is deterministic.

Type

PackagePayloadAuditRecord

Source

Audit evidence for package payloads that are generated-first-party or otherwise not third-party notice records.

Property

Id

string Id { get; init; } Source

Gets the stable inventory record id.

Property

PackageId

string PackageId { get; init; } Source

Gets the package id covered by this audit record.

Property

AppliesTo

List<string> AppliesTo { get; init; } Source

Gets package entry glob patterns or evidence labels covered by this audit.

Property

MatchedRule

string? MatchedRule { get; init; } Source

Gets the suspicious classifier rule or evidence class that caused this audit.

Property

EvidenceKind

string EvidenceKind { get; init; } Source

Gets the audit evidence type, such as generated_first_party.

Property

SourcePaths

List<string> SourcePaths { get; init; } Source

Gets repository source paths that must exist for this audit to stay valid.

Property

GeneratedPaths

List<string> GeneratedPaths { get; init; } Source

Gets generated repository paths that must exist for generated-first-party evidence.

Property

Reason

string Reason { get; init; } Source

Gets the human-readable reason this record is not a third-party notice declaration.

Property

ReviewedOn

string ReviewedOn { get; init; } Source

Gets the date or versioned source used for the audit review.

Property

Source

string Source { get; init; } Source

Gets the reviewer, source document, or script that established this audit.

Property

RevalidateWhen

string RevalidateWhen { get; init; } Source

Gets the event that must force revalidation of the audit.

Type

DurableTemplateTimingWorkflow

Source

Executes five serial exact install/create/test workloads with positively owned NuGet roots.

Remarks

Candidate preparation is outside primed clocks. Cold jobs supply five independently created private Docker daemons; their fresh identity and absent pinned image are verified before each sample. This runner never purges shared caches or images. A failed attempt stays in its series, and corrected runs require a new series identity.

Method

RunAsync

Task<DurableTemplateTimingProofReceipt> RunAsync(DurableTemplateCommandOptions input, DurableTemplateTimingMode mode, IReadOnlyList<string> coldDockerHosts, CancellationToken cancellationToken)

Measures one complete series and writes only bounded safe observations after owned cleanup.

Parameters

  • input
    Exact producer/archive/source inputs; the report is the timing receipt destination.
  • mode
    Primed performance gate or cold diagnostic protocol.
  • coldDockerHosts
    Five private workflow-owned daemon endpoints, one per cold sample; empty for primed.
  • cancellationToken
    Stops workload commands; independently bounded cleanup is still attempted.

Returns

All five attempts and their validated series result.

Method

TryReadChildCleanupMilliseconds

bool TryReadChildCleanupMilliseconds(ExternalCommandResult result, out int elapsedMilliseconds)

Reads one complete, unambiguous child cleanup observation within the original 20-second ceiling.

Parameters

  • result
    Completed FirstWork result; either truncated stream invalidates the observation.
  • elapsedMilliseconds
    Observed nonnegative elapsed cleanup time when the observation is valid.

Returns

Whether one exact marker supplies a non-exhausted allowance; invalid evidence permits only a minimal attempt.

Remarks

The detailed test console logger may indent output-helper lines with horizontal whitespace.

Method

HashCache

string HashCache(string cache)

Hashes every relative tree path and exact regular-file byte in a bounded NuGet cache closure.

Method

CopyTree

void CopyTree(string source, string destination)

Copies a validated bounded regular tree while preserving every relative directory and file path.

Method

WriteReceipt

void WriteReceipt(string path, DurableTemplateTimingProofReceipt receipt)

Writes a bounded safe timing receipt; raw outputs and credential-bearing arguments are excluded.

Type

CoverageCliConsumerProofEvidenceRenderer

Source

Renders the public-safe, versioned evidence companion for the packaged coverage proof.

Remarks

The Markdown proof remains a private maintainer diagnostic with paths, command details, and bounded logs. This renderer intentionally emits only retained semantic outcomes and relative artifact references, so it is safe to publish beside package validation artifacts without exposing NuGet configuration, command arguments, credentials, raw XML, or host filesystem paths.

Method

RenderJson

string RenderJson(CoverageCliConsumerProofReport report)

Renders one public-safe evidence document.

Parameters

  • report
    Complete private proof report from which safe semantic facts are selected.

Returns

Indented JSON with a terminating newline.

Type

TailwindNativeConsumerWorkflow

Source

Produces release-bound native consumer evidence from the actual NuGet cache restore.

Method

RunAsync

Task<TailwindEvidenceCommandResult> RunAsync(string repositoryRoot, string artifactsInputPath, string artifactManifestPath, TailwindCommandOptions options, ICommandRunner runner, CancellationToken cancellationToken, TailwindNativeProducerArtifactValidator? producerArtifactValidator = null, string? consumerLockTemplatePath = null)

Runs the native proof with an injectable runner and producer validator for focused tests. Production uses the source-stamped TailwindConsumerLock.RelativeTemplatePath ; a test may supply a fixture template for its deliberately smaller producer closure.

Method

ValidateProducerArtifactsAsync

Task ValidateProducerArtifactsAsync(string repositoryRoot, string artifactsInputPath, PackageArtifactManifest manifest, IReadOnlyList<TailwindSubjectPackage> producerClosure, CancellationToken cancellationToken)

Applies the complete checked-in package plan and package payload validation used in production.

Method

ValidatePlannedProducerClosure

void ValidatePlannedProducerClosure(IReadOnlyList<PlannedPackageArtifact> planned, IReadOnlyList<TailwindSubjectPackage> producerClosure)

Checks that each bound producer package has the same filename and SHA-512 as the validated package plan.

Parameters

  • planned
    Manifest entries already validated against the checked-in package plan.
  • producerClosure
    The subset of first-party packages bound by the producer subject.

Exceptions

  • PackageIndexException
    A closure package is missing from the plan or has different bytes or identity.
Method

ReadRidAsset

(string Name, string Sha256, string Version) ReadRidAsset(string packageArchive, string rid)

Reads the selected host binary identity from a restored Tailwind archive's release manifest.

Parameters

  • packageArchive
    Path to the restored Tailwind NuGet archive.
  • rid
    Expected host RID, which must identify exactly one manifest asset.

Returns

The binary filename, SHA-256, and Tailwind version recorded by the package.

Exceptions

  • PackageIndexException
    The archive lacks a usable internal release manifest or selected asset.
Method

RequireSameClosure

void RequireSameClosure(IReadOnlyList<TailwindSubjectPackage> expected, IReadOnlyList<TailwindSubjectPackage> actual)

Requires the restored first-party closure to have exactly the producer's packages and package hashes.

Parameters

  • expected
    Packages from the bound producer subject.
  • actual
    Packages resolved by the native consumer's NuGet assets graph.

Exceptions

  • PackageIndexException
    The closure count or any package identity differs.
Type

TailwindBoundedCommandRunner

Source

Adapts non-throwing external command results to the native proof runner contract while enforcing bounded capture. Internal visibility provides a focused test seam for verifying that proof commands retain the release capture policy and that unsuccessful child processes are rejected before their output is treated as successful evidence.

Type

PackagePublishPlanResolver

Source

Resolves the checked-in package manifest into the exact package set that should be packed.

Method

ResolveAsync

Task<PackagePublishPlan> ResolveAsync(string repositoryRoot, string manifestPath, CancellationToken cancellationToken, bool includeReadinessBlockedForVerification = false)

Resolves and validates the package publish plan.

Parameters

  • repositoryRoot
    Absolute repository root.
  • manifestPath
    Absolute path to the package manifest.
  • cancellationToken
    Cancellation token used while loading metadata.
  • includeReadinessBlockedForVerification
    Includes blocked manifest entries in package proof without changing publication filtering.

Returns

The ordered package publish plan.

Type

PackagePublishPlan

Source

Ordered package set selected for artifact packing and validation.

Parameters

  • Entries
    Packages that should be packed, in deterministic manifest order.
Type

PackagePublishPlanEntry

Source

One package selected for pack artifact production.

Parameters

  • ProjectPath
    Repository-relative project path to pack.
  • PackageId
    Expected NuGet package id.
  • Decision
    Publish decision from the manifest.
  • ExpectedDependencyPackageIds
    Expected same-version package dependencies.
  • IsTool
    Whether the package is a .NET tool package.
  • ToolCommandName
    Validated command shim token from tool_command_name . It is empty for non-tool packages and required for tool packages so the pack/publish workflow can carry the exact command name into artifact validation and smoke tests.
  • ReadinessBlocker
    Maintainer blocker that prevents publishing the coordinated artifact set while still allowing artifacts to be packed and validated.
  • ReleaseGuidanceVariant
    Finite package README release-guidance variant whose canonical absolute links must survive package packing. It is empty for package entries without a managed release-guidance region.
Type

ICoverageCliConsumerProofWorkflow

Source

Runs the pre-publish consumer proof for the packaged AppSurface CLI.

Method

RunAsync

Task<CoverageCliConsumerProofReport> RunAsync(CoverageCliConsumerProofRequest request, PackageArtifactValidationReport validationReport, CancellationToken cancellationToken)

Installs the validated CLI artifact into an isolated fixture and exercises public release-note, coverage, and canary-poll commands.

Parameters

  • request
    Proof request with repository, artifact, work-directory, and package-source settings.
  • validationReport
    Validated package artifact report that selects the CLI tool artifact.
  • cancellationToken
    Cancellation token.

Returns

Structured proof report. Command and artifact failures are represented in the report.

Type

CoverageCliConsumerProofWorkflow

Source

Verifies that the packed ForgeTrust.AppSurface.Cli works from a clean package-consumer project.

Remarks

The proof runs before package publication. It selects the already validated CLI .nupkg , installs it with a local-first NuGet configuration, creates a clean xUnit fixture plus an excluded failing sentinel, composes one consumer-owned release note, and executes coverage run , coverage merge , a passing coverage gate , a patch-target gate plus nonpatch stale-target cleanup, an intentionally failing coverage gate , and canary poll --help , then runs the packed command against a local protected fixture for one pass and one stale result to prove its environment-only credential and operator-result paths are packed.

Pitfall: the failing gate is considered successful only when the command exits non-zero and still writes coverage-gate.json and coverage-gate.md . The patch-target gate separately proves the target JSON and Markdown contract. This preserves the CLI contract that failures are visible in local diagnostics rather than only in the process exit code.

Method

SelectCliToolPackage

CoverageCliConsumerProofSelectedArtifact SelectCliToolPackage(PackageArtifactValidationReport report, string packageVersion)

Selects the validated ForgeTrust.AppSurface.Cli tool package that the consumer proof installs.

Parameters

  • report
    Package artifact validation report produced from the just-packed local artifacts.
  • packageVersion
    Exact package version that must be represented by the selected .nupkg .

Returns

Selected CLI package metadata plus a SHA-512 hash for diagnostics.

Exceptions

  • PackageIndexException
    Thrown when the validated report is missing the CLI package, contains more than one CLI row, marks it as a non-tool package, uses the wrong command name, points at a missing artifact, or points at a different version.

Remarks

The proof intentionally selects from the validation report instead of globbing the artifact directory so package publication cannot silently test an unvalidated file.

Method

RenderMappedNuGetConfig

string RenderMappedNuGetConfig(string localSource, string nugetOrgSource)

Renders the NuGet config used for local tool installation.

Parameters

  • localSource
    Directory containing locally packed AppSurface and RazorWire package artifacts.
  • nugetOrgSource
    NuGet source used for third-party dependency resolution.

Returns

NuGet configuration XML with package-source mapping.

Remarks

AppSurface and RazorWire package ids are mapped to the local artifact source with more-specific package patterns; the * mapping on the public source remains available for third-party dependencies such as xUnit and Coverlet. Keep this config separate from the fixture config so the consumer fixture itself does not restore first-party packages from local artifacts accidentally.

Method

RenderNuGetOrgOnlyConfig

string RenderNuGetOrgOnlyConfig(string nugetOrgSource)

Renders the NuGet config used by the generated consumer fixture for test-only dependencies.

Parameters

  • nugetOrgSource
    NuGet source used by dotnet new xunit and the Coverlet collector/MSBuild fixture packages.

Returns

NuGet configuration XML containing only the supplied third-party source.

Remarks

This config deliberately excludes the local package artifact directory so the fixture exercises the packed CLI only through the local tool manifest installation path.

Type

CanaryProofFixture

Source

Provides a protected named-canary fixture through a loopback HTTP server.

Method

Start

CanaryProofFixture Start()

Starts and returns a newly initialized loopback canary fixture.

Method

DisposeAsync

ValueTask DisposeAsync()

Stops the loopback server and releases the fixture's resources.

Property

BaseUrl

string BaseUrl { get; } Source

Gets the loopback HTTP server URL used by the packaged CLI proof.

Property

ValidRequestCount

int ValidRequestCount { get; } Source

Gets the number of fully valid requests accepted by the loopback server.

Type

CoverageCliConsumerProofRequest

Source

Request for the packaged coverage CLI consumer proof.

Parameters

  • RepositoryRoot
    Repository root used for safety checks and reproduction instructions.
  • ArtifactsDirectory
    Directory containing locally packed package artifacts.
  • PackageVersion
    Exact stable or prerelease package version under proof.
  • WorkDirectory
    Isolated proof workspace that can be deleted and recreated.
  • Source
    NuGet source for third-party dependencies.
Type

CoverageCliConsumerProofSelectedArtifact

Source

Selected CLI artifact metadata captured before running the consumer proof.

Parameters

  • PackageId
    Selected package id.
  • ProjectPath
    Project that produced the artifact.
  • ArtifactPath
    Validated local .nupkg path.
  • ToolCommandName
    Command shim expected after tool installation.
  • Sha512
    SHA-512 hash of the selected artifact.
Type

CoverageCliConsumerProofReport

Source

Structured packaged coverage CLI proof report.

Parameters

  • PackageVersion
    Exact package version under proof.
  • WorkDirectory
    Proof workspace path.
  • Source
    NuGet source used for third-party dependencies.
  • SelectedArtifact
    Selected CLI artifact, if package selection succeeded.
  • ToolNuGetConfigPath
    NuGet config used for tool installation.
  • FixtureNuGetConfigPath
    NuGet config used for fixture dependencies.
  • LogsDirectory
    Directory containing per-command stdout/stderr logs.
  • Commands
    Executed command ledger.
  • Artifacts
    Produced and missing artifact checks.
  • FirstFailure
    First failure summary, or empty when the proof passed.
  • ReproduceCommand
    Command that reruns the package verifier with the same proof workspace.
  • SemanticProof
    Manifest-bound default-collector raw-to-merged semantic proof.
Property

Succeeded

bool Succeeded { get; } Source

Gets whether every command and artifact check matched the expected consumer contract.

Type

CoverageCliConsumerProofCommandResult

Source

One external command in the packaged coverage CLI proof ledger.

Parameters

  • OperationName
    Human-readable operation name.
  • FileName
    Executable path or command name.
  • Arguments
    Command arguments.
  • WorkingDirectory
    Command working directory.
  • ExitCode
    Process exit code.
  • ExpectedNonZeroExitCode
    Whether a non-zero exit code was the expected outcome.
  • Succeeded
    Whether the command matched the expected exit-code contract.
  • FailureReason
    Failure details when the command did not match the expected contract.
  • Duration
    Measured command duration.
  • StandardOutputPath
    Path where stdout was written.
  • StandardErrorPath
    Path where stderr was written.
  • StandardOutput
    Captured stdout excerpt source.
  • StandardError
    Captured stderr excerpt source.
Type

CoverageCliConsumerProofArtifactCheck

Source

One artifact expected from the packaged coverage CLI consumer proof.

Parameters

  • Description
    Artifact role.
  • Path
    Expected or produced artifact path.
  • Exists
    Whether the artifact exists.
Type

CoverageCliConsumerProofContext

Source

Runtime paths shared across the packaged coverage CLI consumer proof.

Parameters

  • Request
    Original proof request and caller-supplied paths.
  • SelectedArtifact
    Validated CLI package artifact selected for local tool installation.
  • FixtureDirectory
    Clean consumer repository where solution, test projects, and local tool manifest are created.
  • LogsDirectory
    Directory for per-command stdout and stderr logs.
  • ToolNuGetConfigPath
    NuGet configuration used only for installing the AppSurface local tool package.
  • FixtureNuGetConfigPath
    NuGet configuration used by the consumer fixture for third-party test dependencies.
  • SharedPackagesPath
    Isolated global packages cache for all proof commands.
  • DotNetHomePath
    Isolated .NET CLI home used to avoid host-machine state.
Type

CoverageCliConsumerProofReportRenderer

Source

Renders packaged coverage CLI consumer proof reports for package validation artifacts.

Method

RenderMarkdown

string RenderMarkdown(CoverageCliConsumerProofReport report)

Renders a standalone markdown report.

Parameters

  • report
    Proof report.

Returns

Markdown report.

Method

RenderSection

void RenderSection(StringBuilder builder, CoverageCliConsumerProofReport report)

Appends the proof section to a larger package validation report.

Parameters

  • builder
    Destination markdown builder.
  • report
    Proof report.
Enum

PackageVersionPolicy

Source

Package version policies used by release-classified package workflows.

Enum

PackagePublishStatus

Source

Publish status values written to the protected publish ledger.

Enum

PackageSmokeInstallStatus

Source

Smoke install status values written to the smoke report.

Enum

PackageReadinessStatus

Source

Package-index evidence status rendered in the maintainer readiness dashboard.

Enum

PackageClassification

Source

Chooser section classifications for manifest entries.

Enum

PackagePublishDecision

Source

Publish decisions for package artifact verification and later package publishing.

Enum

PackageReleaseStatus

Source

Release status values package-gate expects for each chooser classification.

Enum

PackageCommercialStatus

Source

Commercial readiness status values used by package-gate.

Enum

NativePostgreSqlFailureStage

Source

Closed native failure categories; these identify an observation boundary, not a root cause.

Enum

DurableTemplateTimingMode

Source

Identifies the required cache state for a timing series.

Enum

DurableTemplateTimingFeedKind

Source

Identifies the package source used by the exact install/new/test workload.

Enum

DurableTemplateTimingCommandPhase

Source

One phase in the fixed three-command timing workload.