Neutral OCI digest-reference contract

Verified against commit 983bf260239390f640b7fee3bcc2114e94bc6a39 on 2026-10-06. Source and in-process suites passed 346 cases with zero failures or skips; exact re-verification commands appear below.

OciDistributionReference.TryParseDigestReference belongs to the domain-neutral StellaOps.Oci.Core foundation. It admits an explicit OCI distribution reference registry/repository[:tag]@sha256:<64-hex>. Success establishes reference syntax. Content type, authorization, credentials and reachability remain consumer responsibilities. A generic SBOM artifact reference is not an OCI reference merely because it ends with a digest.

Accepted syntax and identity

The registry is explicit: ASCII host labels, IPv4-shaped names or bracketed IPv6, with an optional decimal port. Single-label registries are accepted; no default registry or repository prefix is inferred.
Bracketed IPv6 must parse as IPv6. Unbracketed IPv6, zone identifiers and dotted IPv4-mapped literals are rejected.
Repository components contain lowercase ASCII letters and digits, separated by a period, one or two underscores, or one or more hyphens. Slashes separate nonempty components.
An optional tag begins with an ASCII letter, digit or underscore and contains at most 128 letters, digits, underscores, periods or hyphens. Tag-only references are rejected. A tag accompanying a digest is validated, then omitted from the returned repository.
The existing OciDigest.IsSha256Digest contract validates the digest. Returned registry, repository and digest text retain their input case; hexadecimal digest case is preserved. The digest remains the identity used for manifest and capability requests.
Null, blank, PURL, transport URL, whitespace, query, fragment, escaping and malformed-name inputs return false, with registry, repository and digest all empty.

Port parsing checks decimal syntax. Endpoint usability and transport policy are separate checks; parsing performs no DNS lookup or network request. Parser success does not classify referenced content as an image: plugin artifacts use the same reference syntax.

Immediate consumers

Consumer	Rejection and content boundary
`DefaultGeneralOciImageFetcher`	Invalid references throw `ArgumentException` before HTTP; manifest and blob digest checks remain active.
`OrchestratorImageFetcher`	Invalid references throw before capability lookup or content calls; valid references retain the deployment/tenant capability and pinned digest.
`DefaultPluginBundleOciFetcher`	Invalid references return `invalid_reference` before HTTP; manifest digest mismatch returns `manifest_fetch_failed` before blob retrieval. Artifact and layer checks follow admission.
`DeployPluginPullExecutionPlugin`	Invalid payload references return `invalid_payload` before fetching or installing a bundle.

The library retains zero project references, as classified in the ownership manifest. Findings owns its separate image-projection admission; this contract changes no Findings migration or projection.

Re-verification

Run from the repository root, through the machine-wide test-slot gate:

pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/__Tests/__Libraries/StellaOps.Oci.Core.Tests/StellaOps.Oci.Core.Tests.csproj -All -Restore -BuildProjectReferences
pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/ReleaseOrchestrator/__Tests/StellaOps.Agent.Core.Tests/StellaOps.Agent.Core.Tests.csproj -All -Restore -BuildProjectReferences
pwsh ./tools/scripts/test-targeted-xunit.ps1 -Project src/ReleaseOrchestrator/__Tests/StellaOps.Agent.DeployNative.Tests/StellaOps.Agent.DeployNative.Tests.csproj -All -Restore -BuildProjectReferences
pwsh ./tools/scripts/build-boundary/generate-build-boundary-report.ps1 -Check

These checks establish source and in-process consumer behavior. They do not establish a deployed-estate result.