truf-server/openspec/changes/add-adaptive-docker-payload-scanning/specs/docker-layer-content-scanning/spec.md

MODIFIED Requirements

Requirement: Immutable image content plans are bound after claim

The system SHALL resolve a claimed Docker image's exact platform manifest into a canonical bounded plan containing its configuration and ordered layer descriptors, and SHALL bind that plan to the active result reservation before content execution. Adaptive plans SHALL use an exactly validated version-two schema that binds versioned selector and execution-policy identities plus one bounded payload class per descriptor while retaining exact validation of durable version-one plans.

Scenario: Valid immutable manifest

• WHEN the claimed repository@sha256:<digest> resolves to a valid requested-platform manifest
• THEN the bound plan identifies the same manifest digest and contains only bounded valid SHA-256 content descriptors, sizes, media types, order, policy hashes, classes, and selection reasons

Scenario: Changed replay

• WHEN the same reservation attempts to bind a different content plan
• THEN the system rejects the replay as a fenced conflict and executes neither plan

Scenario: Invalid or oversized manifest

• WHEN the Registry manifest is malformed, exceeds descriptor bounds, or disagrees with the immutable target
• THEN the system fails closed without claiming complete content coverage

Scenario: Valid aligned configuration history

• WHEN a bounded digest-verified configuration has non-empty history entries aligned base-to-top with every manifest layer
• THEN the selector classifies each layer through the versioned bounded classifier and persists only its class enum

Scenario: Untrusted or misaligned configuration history

• WHEN configuration history is absent, malformed, oversized, or inconsistent with layer or rootfs counts
• THEN every affected layer is deterministically classified unknown and no raw history command is persisted or logged

Scenario: Durable version-one replay

• WHEN recovery loads a previously bound valid version-one plan
• THEN the system validates and executes it under its original exact schema without rewriting it as version two

Requirement: Content selection is bounded and application-first

The system SHALL select bounded image configuration and SHALL deterministically select supported unique layers under configured per-layer, aggregate compressed-byte, and unique-layer-count limits. It SHALL select every eligible unique descriptor when the complete set fits, and for larger images SHALL prioritize versioned payload classes before manifest position and stable tie-breaks.

Scenario: Complete bounded image fits

• WHEN configuration and every supported unique layer fit all configured descriptor, aggregate-byte, and unique-layer-count bounds
• THEN the system selects every descriptor regardless of history class

Scenario: Large image requires prioritization

• WHEN all new unique layers cannot fit the configured aggregate bounds
• THEN the system greedily considers copy_add, app_config_run, package_run, unknown, other_run, and bulk_data in that order, then highest position, smallest compressed size, and lexical digest

Scenario: Giant base or model layer

• WHEN a layer exceeds the configured per-layer limit
• THEN the layer is not downloaded by the normal layer scanner and coverage records layer_too_large

Scenario: Image byte budget is exhausted

• WHEN another unscanned layer would exceed the remaining per-image budget
• THEN the layer remains unselected and coverage records image_budget_exhausted

Scenario: Unique layer count is exhausted

• WHEN another unscanned unique layer would exceed the configured selected-layer count
• THEN the layer remains unselected and coverage records layer_limit_exhausted

Scenario: Shared layer is already covered

• WHEN a layer digest has successful coverage under the matching execution policy
• THEN the image reuses that coverage without consuming its transfer-byte or new-execution-count budget

Scenario: Duplicate positions share one digest

• WHEN multiple positions in one manifest reference the same eligible immutable digest
• THEN the system selects all matching positions but budgets and executes that digest at most once

Scenario: Selector input changes

• WHEN a classifier rule, class order, supported-media rule, or selection bound changes
• THEN the system derives a different versioned selection_policy_sha256

Requirement: Layer coverage is globally deduplicated and fenced

The system SHALL maintain one authoritative content-scan state per immutable digest and scan-execution policy and SHALL change successful coverage only through matching reservation, lease, plan, and ingestion fences. Selection budgets, classifier weights, retries, lease timing, and checkpoint scheduling MUST NOT partition otherwise identical successful execution evidence.

Scenario: Concurrent images share a layer

• WHEN two image plans reference the same unscanned digest under the same execution policy concurrently
• THEN at most one reservation owns its active scan and the other image records shared pending work without duplicate execution

Scenario: Selector policy changes only

• WHEN an immutable digest was covered successfully and a later plan changes only selector or scheduling policy
• THEN the later plan reuses the existing execution-policy coverage without launching another scan

Scenario: Execution semantics change

• WHEN the scanner fingerprint, content validator, or scan-affecting archive semantics differ
• THEN the system uses a distinct execution-policy namespace and does not reuse incompatible successful coverage

Scenario: Compatible legacy coverage exists

• WHEN an exact valid version-one plan proves a linked digest is durably covered with execution semantics identical to the requested version-two policy
• THEN the binding transaction may create a covered version-two alias that retains the original successful reservation, plan, byte count, and completion provenance

Scenario: Legacy evidence is incomplete or ambiguous

• WHEN legacy evidence is pending, leased, submitted, failed, orphaned, malformed, or not exactly execution-compatible
• THEN the system does not alias it and requires normal fenced execution under the new policy

Scenario: Successful matching ingestion

• WHEN a result bundle contains a successful execution for a blob leased by its exact bound plan
• THEN ingestion marks that digest globally covered for the matching execution policy in the same durable transaction

Scenario: Stale completion

• WHEN a bundle or worker presents an expired, refunded, or mismatched blob lease
• THEN it cannot mark the digest covered or advance image coverage

Scenario: Reservation is refunded

• WHEN an image reservation is durably refunded before handoff
• THEN only blob leases owned by that reservation are released for bounded reclamation

Requirement: Image coverage is explicit and honest

The system SHALL persist and expose selected, covered, shared-pending, failed, and intentionally skipped content for each immutable image plan, including bounded payload class, exact reason, and execution and selector policy identities. Configuration history classification SHALL influence priority only and SHALL NOT establish content identity or successful coverage.

Scenario: Every descriptor is covered

• WHEN configuration and all image layer positions have successful compatible execution-policy coverage
• THEN the image records complete content coverage

Scenario: Bounds skip content

• WHEN one or more descriptors are excluded by configured size, budget, count, or format bounds
• THEN the image may finish as bounded partial coverage but SHALL NOT report complete content coverage

Scenario: Adaptive priority skips content

• WHEN a large-image descriptor loses deterministic selection to a higher-priority candidate
• THEN its class, declared bytes, omission reason, and partial image scope remain durable without persisting raw history

Scenario: Selected content remains retryable

• WHEN at least one selected blob failed retryably or is actively covered by another reservation
• THEN the image remains deferred without claiming complete coverage

Scenario: Selected content exhausts retries

• WHEN required selected content reaches its terminal attempt limit
• THEN the image receives terminal incomplete disposition with durable coverage detail

Scenario: Covered duplicate appears at multiple positions

• WHEN one successfully covered digest backs multiple positions in an image
• THEN every matching position records compatible covered scope without duplicate execution

Requirement: Layer work resumes without repeating completed content

The system SHALL resume an incomplete image from its earliest complete descriptor-position selection map for the same manifest and selector policy, SHALL NOT expand or contract that selection because mutable coverage changed, and SHALL NOT relaunch content with compatible successful execution-policy coverage. It MAY lease a bounded deterministic batch while retaining independent per-blob fences.

Scenario: Parent image retries

• WHEN an image retry follows partial layer completion
• THEN the new plan reuses the exact frozen selection, reuses compatible covered digests, and leases only remaining eligible content

Scenario: Covered content changes the available budget

• WHEN a selected digest becomes globally covered after the first plan was bound
• THEN a descriptor skipped by the original byte or count budget remains skipped on every later checkpoint under that selector policy

Scenario: Execution policy changes

• WHEN the same frozen selector baseline runs under a new incompatible execution policy
• THEN its selected positions remain unchanged while only content lacking compatible coverage becomes executable

Scenario: Bounded multi-blob checkpoint

• WHEN multiple remaining selected digests fit the configured checkpoint count and byte targets
• THEN one reservation may lease that deterministic batch while each digest retains an independent lease token, attempt, execution record, and ingestion transition

Scenario: Process crashes after one layer

• WHEN one layer was durably ingested before a later checkpoint or parent process failed
• THEN recovery preserves the completed layer and reclaims only unfinished leased content

Scenario: Batch fails before durable handoff

• WHEN a process scans one or more leased blobs but crashes before their result bundle is durably accepted
• THEN none of those un-ingested blobs becomes covered and exact lease recovery remains required

Requirement: Full-image compatibility and deterministic canary are retained

The system SHALL retain the existing full-image scanner, timeout-only canary, and legacy layer path behind configuration. It SHALL additionally provide deterministic adaptive-canary and adaptive version-two modes, fail closed to full execution without a matching passed rollout gate, and preserve full-image rollback without deleting durable layer state.

Scenario: Full mode

• WHEN Docker layer mode is disabled or set to full
• THEN the existing immutable full-image execution path remains authoritative

Scenario: Legacy canary retry

• WHEN an image with a durable previous full-image timeout is retried under the existing canary
• THEN its immutable manifest digest selects the same legacy scanner mode as its previous attempt

Scenario: Non-timeout image during legacy canary rollout

• WHEN an image has no durable previous full-image command timeout
• THEN existing canary configuration keeps that image on the full-image execution path

Scenario: Adaptive canary assignment

• WHEN a matching passed shadow gate permits adaptive-canary
• THEN a versioned stable hash of every immutable manifest identity selects the same configured adaptive cohort across retries while non-members remain full-image controls

Scenario: Adaptive gate is absent or stale

• WHEN adaptive configuration lacks a completed passing report for its exact scan, execution, and selector policy hashes
• THEN no adaptive plan is bound and the claim uses full-image execution

Scenario: Broad adaptive mode

• WHEN matching shadow evidence passes and the low-percentage production canary remains within safety gates for at least one repository-refresh interval
• THEN operators may explicitly configure adaptive for all eligible immutable Docker claims

Scenario: Layer mode rollback

• WHEN operators return configuration from layer, canary, adaptive-canary, or adaptive to full
• THEN new claims use full-image execution without deleting durable layer plans, coverage, or rollout evidence

Requirement: Controlled evidence gates production rollout

The system SHALL compare adaptive scanning with completed full-image controls through a bounded non-authoritative evaluator and SHALL keep adaptive production modes fail-closed until a policy-exact aggregate report passes security, coverage, completion, and throughput gates. Shadow execution MUST NOT mutate authoritative queue, reservation, coverage, finding, candidate, keycheck, projection, or source-counter state.

Scenario: Controlled adaptive shadow cohort

• WHEN the evaluator runs against 50-100 exact immutable images with completed full-image controls under one scan fingerprint
• THEN it executes the candidate adaptive policy under the same bounded scanner semantics and records only aggregate policy hashes, counts, slot milliseconds, failures, thresholds, and timestamps

Scenario: Shadow identity comparison

• WHEN routed and detector recall are calculated
• THEN (service, provider_key_hash) and detector_secret_hash sets exist only in protected memory long enough to calculate aggregate full, adaptive, and intersection counts

Scenario: Shadow privacy

• WHEN a shadow run completes, fails, or logs diagnostics
• THEN no target name, raw config command, finding, secret, provider material, identity set, or Registry bearer is persisted in rollout evidence or ordinary logs

Scenario: Shadow non-authority

• WHEN shadow execution emits candidate material or completes a blob
• THEN it cannot create authoritative findings or candidates, route keychecks, mark global blob coverage, alter image disposition, or change production mode

Scenario: Routed recall or slot-time gate fails

• WHEN paired routed-identity recall is below 85% or aggregate adaptive slot time exceeds 40% of aggregate full slot time
• THEN the report does not authorize adaptive production execution

Scenario: Safety or completion gate fails

• WHEN fewer than 50 paired controls complete, any digest/fence/containment requirement fails, omissions are unaccounted, or resource, quarantine, projection, credential, or source health regresses
• THEN the report does not authorize adaptive production execution

Scenario: Policy changes after a passing report

• WHEN scan, execution, or selector policy identity changes
• THEN the earlier report is stale and adaptive execution remains fail-closed until the new exact policy passes another shadow cohort

Scenario: Acceptance criteria pass

• WHEN 50-100 paired controls retain at least 85% routed identities at no more than 40% slot time with every safety gate satisfied
• THEN operators may start a low deterministic adaptive canary but SHALL NOT enable broad adaptive mode until that canary remains stable for at least one repository-refresh interval