truf-server/openspec/changes/add-layer-aware-docker-scanning/tasks.md

1. Restore Bounded Timeout Semantics

• 1.1 Make Docker timeout disposition terminal at the configured target-attempt maximum in production-v2 and legacy paths without resetting attempts
• 1.2 Add regression tests proving partial findings survive and timeout attempts stop at the configured limit
• 1.3 Add a stopped-runtime guarded repair for unfenced historical Docker targets whose durable timeout attempts were reset

2. Validate Layer Scanning

• 2.1 Prove the installed TruffleHog filesystem source safely scans bounded Docker gzip and supported OCI layer archives with preserved findings
• 2.2 Run an aggregate-only spike across timeout-heavy and completed-control images and select conservative config, layer, image, archive, and deadline bounds
• 2.3 Record spike acceptance evidence and rejected formats/approaches in the design

3. Add Durable Layer State

• 3.1 Add reservation plan columns plus Docker content-blob and image-coverage tables, indexes, migration marker, and exact runtime validation
• 3.2 Implement bounded canonical Docker layer-plan validation, hashing, idempotent fenced binding, and deterministic canary selection
• 3.3 Implement content lease claim, expiry, refund, retry, terminal failure, and globally successful coverage transitions
• 3.4 Wire matching blob execution and image coverage updates into the authoritative fenced result-ingestion transaction

4. Implement Bounded Registry Content Access

• 4.1 Extend exact platform manifest resolution with bounded configuration and ordered layer size/media descriptors
• 4.2 Implement authenticated Registry blob streaming with safe redirects, byte/disk/deadline bounds, private artifacts, and SHA-256 verification
• 4.3 Implement contained configuration and layer archive scans with immutable image/blob provenance and deterministic cleanup

5. Integrate Layer-Aware Execution

• 5.1 Select configuration and highest-first layers under per-layer and per-image byte budgets while reusing globally covered digests
• 5.2 Resolve and bind the Docker layer plan after the fenced parent claim using a dedicated database connection
• 5.3 Execute only leased blobs, preserve partial findings, and emit exact plan/execution/coverage metadata through result bundles
• 5.4 Resume deferred images without rerunning covered blobs and defer shared active content without charging duplicate attempts

6. Add Controlled Rollout and Observability

• 6.1 Add bounded full, deterministic canary, and layer configuration with full-image rollback
• 6.2 Expose aggregate selected/covered/skipped/shared/failed bytes, blob reuse, transfer duration, timeout, and image coverage metrics without secret material
• 6.3 Keep existing scan-slot, Windows Job, output, keycheck, and credential-isolation invariants unchanged

7. Verify and Deploy

• 7.1 Add unit tests for plan bounds, selection order, downloader security, digest verification, provenance, timeout policy, and canary stability
• 7.2 Add PostgreSQL integration tests for concurrent global deduplication, stale fences, refund/reclaim, partial ingestion, resume, and image coverage
• 7.3 Run related regression suites, strict OpenSpec validation, and aggregate control comparison; document evidence
• 7.4 Apply the additive migration offline, repair historical attempts, restart in full mode, and verify no behavior regression
• 7.5 Enable a bounded deterministic canary, monitor throughput/coverage/keycheck/quarantine gates, and expand only if acceptance criteria pass