truf-server/openspec/changes/rescan-updated-core-targets/specs/updated-target-rescan/spec.md

ADDED Requirements

Requirement: Discovery preserves remote content recency

The system SHALL preserve a normalized remote content-update timestamp for GitHub, GitLab, and HuggingFace discovery records and SHALL keep DockerHub digest-based identity behavior unchanged.

Scenario: Source-specific remote timestamp is retained

• WHEN GitHub supplies pushed_at, GitLab supplies last_activity_at, or HuggingFace supplies lastModified
• THEN the queue observation stores the valid UTC timestamp with the target identity

Scenario: Missing or malformed remote timestamp

• WHEN a discovery result has no valid remote content-update timestamp
• THEN the target remains eligible for normal new-target admission but MUST NOT trigger an updated-target rescan

Scenario: DockerHub discovery

• WHEN DockerHub resolves an image tag
• THEN the existing digest identity and refresh behavior remain authoritative without updated-target promotion

Requirement: Only changed completed targets are promoted

The system SHALL promote a known target only when it is completed, its observed remote timestamp is strictly newer than the remote timestamp covered by its latest scan, and its configured cooldown has elapsed.

Scenario: Completed target changed after its covered revision

• WHEN discovery observes a newer valid remote timestamp for a completed target after cooldown
• THEN the target becomes pending for one normal fenced scan

Scenario: Unchanged target is rediscovered

• WHEN discovery observes the same or an older remote timestamp
• THEN the completed target remains unchanged and unclaimable

Scenario: Legacy completed target is first observed

• WHEN a completed target has no claimed remote timestamp
• THEN it is promoted only if the observed remote timestamp is strictly newer than its last completion time

Scenario: Non-completed target is rediscovered

• WHEN the target is failed, pending, deferred, in progress, unresolved, leased, claimed, or reserved
• THEN updated-target discovery MUST NOT alter its lifecycle or authority fields

Scenario: Update arrives during a scan

• WHEN discovery records a newer remote timestamp after the active claim captured its scan timestamp
• THEN completion preserves the newer observation and permits one bounded follow-up scan after cooldown

Requirement: Updated-target admission is bounded

The system SHALL enforce a source-configured hard maximum of updated-target promotions per discovery cycle and a per-target cooldown.

Scenario: Eligible changes exceed the cycle budget

• WHEN more completed changed targets are eligible than the configured maximum
• THEN at most the configured maximum are promoted and the remainder stay eligible for later cycles

Scenario: Cooldown has not elapsed

• WHEN a changed completed target was scanned within the configured cooldown
• THEN it remains completed until a later eligible cycle

Scenario: Concurrent discovery cycles

• WHEN multiple workers observe the same changed target concurrently
• THEN transactional row fencing permits at most one promotion for the covered revision

Requirement: Updated discovery remains capable of seeing changed known targets

The system SHALL NOT use identity-only known-page stopping for a source while updated-target rescans are enabled and SHALL keep discovery bounded by explicit page and result limits.

Scenario: Known identities appear on an early page

• WHEN an early discovery page contains only known target identities
• THEN discovery continues within its configured hard page limit so later changed targets can be observed

Scenario: HuggingFace Space was created long ago and recently updated

• WHEN a known Space has a recent lastModified value
• THEN update-sorted HuggingFace discovery can observe it independently of creation time

Requirement: Claims record the covered remote revision

The system SHALL atomically snapshot the newest observed remote timestamp when a target is claimed.

Scenario: Revision-aware target is claimed

• WHEN a pending target receives a valid lease and reservation
• THEN its scan-covered timestamp equals the newest remote timestamp observed before that claim

Scenario: Claim fails before authority is committed

• WHEN capacity or fencing prevents the claim
• THEN the scan-covered timestamp MUST NOT advance

Requirement: Updated-target activity is separately observable

The system SHALL report updated-target promotions separately from newly discovered target admissions in durable cycle metrics, source logs, and dashboard summaries.

Scenario: Cycle admits new and updated targets

• WHEN a discovery cycle inserts new identities and promotes changed completed identities
• THEN queued_new_count and queued_updated_count record the respective counts without overlap

Scenario: No changed targets are promoted

• WHEN a cycle observes only unchanged or ineligible known targets
• THEN queued_updated_count is zero