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