truf-server/openspec/changes/improve-core-scan-coverage/specs/docker-layer-graph-selection/spec.md

ADDED Requirements

Requirement: Platform-specific layer graphs are resolved

The system SHALL resolve each bounded Docker tag candidate to the requested platform child manifest and SHALL represent its image contents as the ordered sequence of valid layer digests.

Scenario: Multi-platform tag contains the requested platform

• WHEN a tag exposes a matching linux/amd64 child manifest
• THEN the system uses that child manifest digest and its ordered layers rather than the top-level index digest

Scenario: Candidate manifest is malformed

• WHEN a registry response is oversized, malformed, or contains invalid layer identities
• THEN the candidate is not represented as a resolved layer graph

Requirement: Docker selection covers distinct graphs

The system SHALL emit no more than the configured one-to-three image targets per repository and SHALL NOT emit two candidates with identical ordered layer digest sequences.

Scenario: Tags alias one graph

• WHEN multiple tags resolve to the same ordered layer sequence
• THEN only the newest alias remains eligible for selection

Scenario: Three or more graphs are available

• WHEN at least three distinct graphs resolve successfully
• THEN the system selects the newest graph, the remaining graph adding the most not-yet-selected layers, and the oldest remaining distinct graph

Scenario: Fewer graphs are available

• WHEN fewer distinct graphs resolve successfully than the configured maximum
• THEN the system emits only the distinct graphs that exist

Scenario: Layer order differs

• WHEN two manifests contain the same layer identities in a different order
• THEN the system treats them as distinct graphs

Requirement: Selected Docker targets remain immutable

The system SHALL emit each selected target as the canonical requested-platform manifest digest identity repository@sha256:<digest>.

Scenario: Selected tag moves later

• WHEN a tag is republished after discovery
• THEN the queued target continues to identify the originally selected platform manifest digest

Requirement: Docker graph resolution is bounded and honest

The system SHALL retain hard tag-candidate, selected-graph, response-size, retry, and timeout bounds and SHALL NOT cache partial graph resolution as complete.

Scenario: Some manifest requests fail

• WHEN at least one candidate graph resolves and another candidate fails transiently
• THEN the system may emit the resolved targets for the cycle but records partial resolution and does not write a complete positive cache entry

Scenario: Every manifest request fails transiently

• WHEN no candidate graph can be resolved because registry metadata is unavailable
• THEN the repository remains retryable through the existing deferred-resolution lifecycle