feat(artifacts): add fenced reconciliation recovery

crates/crank-registry/src/error.rs

@@ -156,6 +156,8 @@ pub enum RegistryError {
     SourceUnavailable,
     #[error("artifact source integrity verification failed")]
     SourceIntegrity,
+    #[error("artifact reconciliation is already claimed")]
+    ArtifactClaimInProgress,
     #[error("artifact source metadata is invalid for field {field}")]
     InvalidArtifactSource { field: &'static str },
 }

crates/crank-registry/src/lib.rs

@@ -15,28 +15,32 @@ pub mod records {
     pub use crate::model::{
         AdminBootstrapContractRecord, AgentSummary, AgentVersionRecord, AppendProductEventOutcome,
         AppliedImportOperation, ApprovalRequestRecord, ArtifactBlobLifecycle, ArtifactBlobRecord,
-        ArtifactDigest, ArtifactSourceCursor, ArtifactSourceId, ArtifactSourceLifecycle,
-        ArtifactSourcePage, ArtifactSourceRecord, ArtifactSourceSensitivity, AuthUserRecord,
-        DescriptorKind, DescriptorMetadata, ImportJob, ImportJobApplyResult, ImportJobId,
-        ImportJobKind, ImportJobStatus, InvitationRecord, InvocationHistoryLoss,
-        InvocationHistoryLossCategory, InvocationHistoryWriteOutcome, InvocationLogRecord,
-        InvocationRetentionOutcome, InvocationRetentionPolicy, InvocationRetentionStatus,
-        MasterKeyIdentityRecord, MasterKeyRotationRecord, MasterKeyRotationStatus,
-        MembershipRecord, OnboardingMilestoneResult, OnboardingPresentationMilestone,
-        OperationAgentRef, OperationSampleMetadata, OperationSummary, OperationUsageSummary,
-        OperationVersionRecord, Page, PlatformApiKeyRecord, ProductEventRecord,
-        PublishedAgentCatalog, PublishedAgentTool, RegistryOperation, SampleKind, SecretRecord,
-        SecretVersionRecord, SessionRecord, SkippedImportOperation, UsageAgentBreakdown,
-        UsageBucket, UsageOperationBreakdown, UsageOutcomeBreakdown, UsageOutcomeGroup,
-        UsageRollupRecord, UsageSummary, UsageTimelinePoint, VerifiedArtifactSource,
-        WorkspaceMembershipRecord, WorkspaceRecord, WorkspaceUpstream, WorkspaceUpstreamId,
-        YamlImportJob, YamlImportJobCompletion, YamlImportJobId, YamlImportJobStatus,
+        ArtifactClaimFinalization, ArtifactClaimFinalizeOutcome, ArtifactClaimOutcome,
+        ArtifactClaimRecheckOutcome, ArtifactClaimToken, ArtifactDigest, ArtifactExpiredClaimProbe,
+        ArtifactReconciliationClaim, ArtifactSourceCursor, ArtifactSourceId,
+        ArtifactSourceLifecycle, ArtifactSourcePage, ArtifactSourceRecord,
+        ArtifactSourceSensitivity, AuthUserRecord, DescriptorKind, DescriptorMetadata, ImportJob,
+        ImportJobApplyResult, ImportJobId, ImportJobKind, ImportJobStatus, InvitationRecord,
+        InvocationHistoryLoss, InvocationHistoryLossCategory, InvocationHistoryWriteOutcome,
+        InvocationLogRecord, InvocationRetentionOutcome, InvocationRetentionPolicy,
+        InvocationRetentionStatus, MasterKeyIdentityRecord, MasterKeyRotationRecord,
+        MasterKeyRotationStatus, MembershipRecord, OnboardingMilestoneResult,
+        OnboardingPresentationMilestone, OperationAgentRef, OperationSampleMetadata,
+        OperationSummary, OperationUsageSummary, OperationVersionRecord, Page,
+        PlatformApiKeyRecord, ProductEventRecord, PublishedAgentCatalog, PublishedAgentTool,
+        RegistryOperation, SampleKind, SecretRecord, SecretVersionRecord, SessionRecord,
+        SkippedImportOperation, UsageAgentBreakdown, UsageBucket, UsageOperationBreakdown,
+        UsageOutcomeBreakdown, UsageOutcomeGroup, UsageRollupRecord, UsageSummary,
+        UsageTimelinePoint, VerifiedArtifactSource, WorkspaceMembershipRecord, WorkspaceRecord,
+        WorkspaceUpstream, WorkspaceUpstreamId, YamlImportJob, YamlImportJobCompletion,
+        YamlImportJobId, YamlImportJobStatus,
     };
 }
 
 pub mod requests {
     pub use crate::model::{
         AdminSecurityAuditRequest, AppendProductEventRequest, ApplyImportJobRequest,
+        ClaimArtifactReconciliationRequest, ClaimExpiredArtifactReconciliationRequest,
         ConsumeAdminBootstrapContractRequest, CreateAdminBootstrapContractRequest,
         CreateAgentDraftVersionRequest, CreateAgentRequest, CreateApprovalRequest,
         CreateArtifactSourceRequest, CreateImportJobRequest, CreateInvitationRequest,
@@ -67,9 +71,12 @@ pub use model::{
     AdminBootstrapContractRecord, AdminSecurityAuditRequest, AgentStateExpectation, AgentSummary,
     AgentVersionRecord, AppendProductEventOutcome, AppendProductEventRequest,
     AppliedImportOperation, ApplyImportJobRequest, ApprovalRequestRecord, ArtifactBlobLifecycle,
-    ArtifactBlobRecord, ArtifactDigest, ArtifactSourceCursor, ArtifactSourceId,
+    ArtifactBlobRecord, ArtifactClaimFinalization, ArtifactClaimFinalizeOutcome,
+    ArtifactClaimOutcome, ArtifactClaimRecheckOutcome, ArtifactClaimToken, ArtifactDigest,
+    ArtifactExpiredClaimProbe, ArtifactReconciliationClaim, ArtifactSourceCursor, ArtifactSourceId,
     ArtifactSourceLifecycle, ArtifactSourcePage, ArtifactSourceRecord, ArtifactSourceSensitivity,
-    AuthUserRecord, ConsumeAdminBootstrapContractRequest, CreateAdminBootstrapContractRequest,
+    AuthUserRecord, ClaimArtifactReconciliationRequest, ClaimExpiredArtifactReconciliationRequest,
+    ConsumeAdminBootstrapContractRequest, CreateAdminBootstrapContractRequest,
     CreateAgentDraftVersionRequest, CreateAgentRequest, CreateApprovalRequest,
     CreateArtifactSourceRequest, CreateImportJobRequest, CreateInvitationRequest,
     CreateInvocationLogRequest, CreatePlatformApiKeyRequest, CreateSecretRequest,
@@ -81,12 +88,13 @@ pub use model::{
     InvocationHistoryWriteOutcome, InvocationLogRecord, InvocationRetentionOutcome,
     InvocationRetentionPolicy, InvocationRetentionStatus, ListApprovalRequestsQuery,
     ListArtifactSourcesQuery, ListInvocationLogsQuery, ListProductEventsQuery,
-    MASTER_KEY_CIPHER_CONTRACT, MAX_ARTIFACT_SOURCE_PAGE_SIZE, MasterKeyIdentityCandidate,
-    MasterKeyIdentityRecord, MasterKeyRotationRecord, MasterKeyRotationStatus, MembershipRecord,
-    OnboardingMilestoneResult, OnboardingPresentationMilestone, OperationAgentRef,
-    OperationSampleMetadata, OperationStateExpectation, OperationSummary, OperationUsageSummary,
-    OperationVersionRecord, Page, PlatformApiKeyRecord, ProductEventRecord, PublishAgentRequest,
-    PublishRequest, PublishedAgentCatalog, PublishedAgentTool, RecordOnboardingCompletionRequest,
+    MASTER_KEY_CIPHER_CONTRACT, MAX_ARTIFACT_CLAIM_RECOVERY_BATCH, MAX_ARTIFACT_SOURCE_PAGE_SIZE,
+    MasterKeyIdentityCandidate, MasterKeyIdentityRecord, MasterKeyRotationRecord,
+    MasterKeyRotationStatus, MembershipRecord, OnboardingMilestoneResult,
+    OnboardingPresentationMilestone, OperationAgentRef, OperationSampleMetadata,
+    OperationStateExpectation, OperationSummary, OperationUsageSummary, OperationVersionRecord,
+    Page, PlatformApiKeyRecord, ProductEventRecord, PublishAgentRequest, PublishRequest,
+    PublishedAgentCatalog, PublishedAgentTool, RecordOnboardingCompletionRequest,
     RecordOnboardingMilestoneRequest, RecoverAdminPasswordRequest, RegistryOperation,
     RotateSecretRequest, SampleKind, SaveAgentBindingsRequest, SaveAgentCatalogConfigRequest,
     SaveAuthProfileRequest, SaveDescriptorMetadataRequest, SaveSampleMetadataRequest,

crates/crank-registry/src/model/artifact_source.rs

@@ -1,5 +1,8 @@
+use std::fmt;
+
 use crank_artifacts::{ArtifactRef, RegisteredArtifact};
 use crank_core::WorkspaceId;
+use rand::random;
 use serde::{Deserialize, Serialize};
 use time::OffsetDateTime;
 
@@ -7,6 +10,189 @@ define_registry_id!(ArtifactSourceId);
 define_registry_id!(ArtifactDigest);
 
 pub const MAX_ARTIFACT_SOURCE_PAGE_SIZE: u32 = 100;
+pub const MAX_ARTIFACT_CLAIM_RECOVERY_BATCH: u32 = 32;
+const ARTIFACT_CLAIM_TOKEN_BYTES: usize = 32;
+
+/// An unpredictable, bounded fencing token for one reconciliation attempt.
+///
+/// It is intentionally opaque: callers can retain it in an
+/// [`ArtifactReconciliationClaim`], but cannot format or extract it for logs,
+/// metrics, or another process.
+#[derive(Clone, PartialEq, Eq)]
+pub struct ArtifactClaimToken(String);
+
+impl ArtifactClaimToken {
+    pub fn generate() -> Self {
+        let bytes = random::<[u8; ARTIFACT_CLAIM_TOKEN_BYTES]>();
+        let mut value = String::with_capacity(ARTIFACT_CLAIM_TOKEN_BYTES * 2);
+        for byte in bytes {
+            use std::fmt::Write as _;
+
+            let _ = write!(value, "{byte:02x}");
+        }
+        Self(value)
+    }
+
+    pub(crate) fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Debug for ArtifactClaimToken {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("ArtifactClaimToken(..)")
+    }
+}
+
+/// Opaque transient authority to recheck and finalize a reconciliation item.
+///
+/// It has no `Display` implementation and its `Debug` form is redacted so a
+/// durable claim token cannot cross an observability boundary by accident.
+#[derive(Clone)]
+pub struct ArtifactReconciliationClaim {
+    artifact_ref: ArtifactRef,
+    token: ArtifactClaimToken,
+}
+
+impl ArtifactReconciliationClaim {
+    pub(crate) fn new(artifact_ref: ArtifactRef, token: ArtifactClaimToken) -> Self {
+        Self {
+            artifact_ref,
+            token,
+        }
+    }
+
+    /// Opaque content-addressed identity for a trusted artifact-store probe.
+    ///
+    /// This must not be formatted into telemetry or an external response.
+    pub fn artifact_ref(&self) -> &ArtifactRef {
+        &self.artifact_ref
+    }
+
+    pub(crate) fn token(&self) -> &ArtifactClaimToken {
+        &self.token
+    }
+}
+
+impl fmt::Debug for ArtifactReconciliationClaim {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("ArtifactReconciliationClaim(..)")
+    }
+}
+
+#[derive(Clone)]
+pub struct ClaimArtifactReconciliationRequest<'a> {
+    pub artifact: &'a RegisteredArtifact,
+    pub token: ArtifactClaimToken,
+    pub claimed_at: OffsetDateTime,
+    pub lease_expires_at: OffsetDateTime,
+    pub detached_grace: time::Duration,
+}
+
+impl fmt::Debug for ClaimArtifactReconciliationRequest<'_> {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("ClaimArtifactReconciliationRequest(..)")
+    }
+}
+
+/// Bounded recovery lease acquisition for one expired durable claim.
+///
+/// Recovery needs no `RegisteredArtifact`: it recovers an identity validated
+/// when the previous claim was acquired. The caller must still revalidate
+/// physical presence through the artifact store before finalization.
+#[derive(Clone, Debug)]
+pub struct ClaimExpiredArtifactReconciliationRequest {
+    pub token: ArtifactClaimToken,
+    pub claimed_at: OffsetDateTime,
+    pub lease_expires_at: OffsetDateTime,
+}
+
+/// Opaque compare-and-swap evidence for an expired claim discovered by a
+/// bounded recovery read. It does not acquire a lease by itself.
+#[derive(Clone)]
+pub struct ArtifactExpiredClaimProbe {
+    artifact_ref: ArtifactRef,
+    prior_token: String,
+    claim_expires_at: OffsetDateTime,
+}
+
+impl ArtifactExpiredClaimProbe {
+    pub(crate) fn new(
+        artifact_ref: ArtifactRef,
+        prior_token: String,
+        claim_expires_at: OffsetDateTime,
+    ) -> Self {
+        Self {
+            artifact_ref,
+            prior_token,
+            claim_expires_at,
+        }
+    }
+
+    /// Opaque content-addressed identity for a trusted artifact-store probe.
+    /// This must not be formatted into telemetry or an external response.
+    pub fn artifact_ref(&self) -> &ArtifactRef {
+        &self.artifact_ref
+    }
+
+    pub(crate) fn prior_token(&self) -> &str {
+        &self.prior_token
+    }
+
+    pub(crate) fn claim_expires_at(&self) -> OffsetDateTime {
+        self.claim_expires_at
+    }
+}
+
+impl fmt::Debug for ArtifactExpiredClaimProbe {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str("ArtifactExpiredClaimProbe(..)")
+    }
+}
+
+#[derive(Clone, Debug)]
+pub enum ArtifactClaimOutcome {
+    /// This caller owns the fenced claim and may perform the next recheck.
+    Claimed(ArtifactReconciliationClaim),
+    /// A current token already owns the artifact; retry after its lease.
+    HeldByOther,
+    /// The artifact is still referenced by at least one active source.
+    ActiveReference,
+    /// A detached source remains within the caller's grace window.
+    DetachedReferenceInGrace,
+    /// A row with the same digest does not match store-validated metadata.
+    MetadataConflict,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ArtifactClaimRecheckOutcome {
+    /// The caller still owns the claim and no global reference blocks I/O.
+    Mutate,
+    /// An active relation now protects the artifact.
+    ActiveReference,
+    /// A detached relation is still protected by grace.
+    DetachedReferenceInGrace,
+    /// The token was finalized, replaced, or expired.
+    Stale,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ArtifactClaimFinalization {
+    Deleted,
+    AlreadyAbsent,
+    Quarantined,
+    Retryable,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ArtifactClaimFinalizeOutcome {
+    /// Confirmed absence was durably recorded as V12 `unavailable`.
+    Unavailable,
+    /// An ambiguous/mid-flight mutation remains fenced for recovery.
+    Retained,
+    /// The supplied token no longer owns the row.
+    Stale,
+}
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]

crates/crank-registry/src/postgres/artifact_source.rs

@@ -3,19 +3,373 @@ use crank_core::WorkspaceId;
 use sqlx::{Postgres, Row, Transaction, postgres::PgRow};
 
 use crate::{
-    ArtifactBlobLifecycle, ArtifactBlobRecord, ArtifactDigest, ArtifactSourceCursor,
+    ArtifactBlobLifecycle, ArtifactBlobRecord, ArtifactClaimFinalization,
+    ArtifactClaimFinalizeOutcome, ArtifactClaimOutcome, ArtifactClaimRecheckOutcome,
+    ArtifactDigest, ArtifactExpiredClaimProbe, ArtifactReconciliationClaim, ArtifactSourceCursor,
     ArtifactSourceId, ArtifactSourceLifecycle, ArtifactSourcePage, ArtifactSourceRecord,
-    ArtifactSourceSensitivity, CreateArtifactSourceRequest, DetachArtifactSourceRequest,
-    ListArtifactSourcesQuery, MAX_ARTIFACT_SOURCE_PAGE_SIZE, RegistryError, VerifiedArtifactSource,
+    ArtifactSourceSensitivity, ClaimArtifactReconciliationRequest,
+    ClaimExpiredArtifactReconciliationRequest, CreateArtifactSourceRequest,
+    DetachArtifactSourceRequest, ListArtifactSourcesQuery, MAX_ARTIFACT_CLAIM_RECOVERY_BATCH,
+    MAX_ARTIFACT_SOURCE_PAGE_SIZE, RegistryError, VerifiedArtifactSource,
 };
 
 use super::PostgresRegistry;
 
+mod reconciliation;
+use reconciliation::{
+    checked_cutoff, database_now, insert_blob_if_missing_at_database_time, validate_claim_lease,
+};
+
 const SOURCE_ID_PREFIX: &str = "src_";
 const MAX_SOURCE_ID_SUFFIX_BYTES: usize = 128;
 const MAX_MIME_TYPE_BYTES: usize = 255;
 
 impl PostgresRegistry {
+    /// Acquires a short, fenced reconciliation lease after checking references
+    /// across every workspace. A lease may be replayed by its original token,
+    /// or stolen only after expiry.
+    pub async fn claim_artifact_reconciliation(
+        &self,
+        request: ClaimArtifactReconciliationRequest<'_>,
+    ) -> Result<ArtifactClaimOutcome, RegistryError> {
+        let lease_duration = validate_claim_lease(request.claimed_at, request.lease_expires_at)?;
+        if request.detached_grace.is_negative() {
+            return Err(RegistryError::InvalidArtifactSource {
+                field: "detached_grace",
+            });
+        }
+        if !valid_artifact_size(request.artifact.size_bytes()) {
+            return Err(RegistryError::InvalidArtifactSource {
+                field: "size_bytes",
+            });
+        }
+
+        let mut transaction = self.pool().begin().await?;
+        let artifact_ref = request.artifact.artifact_ref();
+        let size_bytes = i64::try_from(request.artifact.size_bytes()).map_err(|_| {
+            RegistryError::InvalidArtifactSource {
+                field: "size_bytes",
+            }
+        })?;
+        insert_blob_if_missing_at_database_time(&mut transaction, artifact_ref, size_bytes).await?;
+        let row = lock_blob(&mut transaction, artifact_ref.digest_hex()).await?;
+        let database_now = database_now(&mut transaction).await?;
+        if !blob_metadata_matches(&row, artifact_ref, size_bytes)? {
+            transaction.rollback().await?;
+            return Ok(ArtifactClaimOutcome::MetadataConflict);
+        }
+        if global_active_reference(&mut transaction, artifact_ref.digest_hex()).await? {
+            transaction.rollback().await?;
+            return Ok(ArtifactClaimOutcome::ActiveReference);
+        }
+        if global_detached_reference_in_grace(
+            &mut transaction,
+            artifact_ref.digest_hex(),
+            checked_cutoff(database_now, request.detached_grace)?,
+        )
+        .await?
+        {
+            transaction.rollback().await?;
+            return Ok(ArtifactClaimOutcome::DetachedReferenceInGrace);
+        }
+
+        let claim_token = row.try_get::<Option<String>, _>("claim_token")?;
+        let claim_expires_at =
+            row.try_get::<Option<time::OffsetDateTime>, _>("claim_expires_at")?;
+        if let (Some(current_token), Some(expires_at)) = (claim_token, claim_expires_at) {
+            if current_token == request.token.as_str() && expires_at > database_now {
+                transaction.commit().await?;
+                return Ok(ArtifactClaimOutcome::Claimed(
+                    ArtifactReconciliationClaim::new(artifact_ref.clone(), request.token),
+                ));
+            }
+            if expires_at > database_now || current_token == request.token.as_str() {
+                transaction.rollback().await?;
+                return Ok(ArtifactClaimOutcome::HeldByOther);
+            }
+        }
+
+        let updated = sqlx::query(
+            "update artifact_blobs
+                set claim_token = $1, claim_expires_at = $2, updated_at = greatest(updated_at, $3)
+              where digest = $4",
+        )
+        .bind(request.token.as_str())
+        .bind(database_now + lease_duration)
+        .bind(database_now)
+        .bind(artifact_ref.digest_hex())
+        .execute(&mut *transaction)
+        .await?
+        .rows_affected();
+        debug_assert_eq!(updated, 1);
+        transaction.commit().await?;
+        Ok(ArtifactClaimOutcome::Claimed(
+            ArtifactReconciliationClaim::new(artifact_ref.clone(), request.token),
+        ))
+    }
+
+    /// Reads a bounded set of expired claims without taking their leases.
+    ///
+    /// Recovery first probes physical presence through the artifact store. Only
+    /// a confirmed absence should call `claim_expired_artifact_reconciliation`.
+    /// Leaving final or quarantine entries untouched lets the ordinary scanner
+    /// reclaim them with a store-validated `RegisteredArtifact`.
+    pub async fn list_expired_artifact_reconciliation_probes(
+        &self,
+        now: time::OffsetDateTime,
+        limit: u32,
+    ) -> Result<Vec<ArtifactExpiredClaimProbe>, RegistryError> {
+        self.list_expired_artifact_reconciliation_probes_after(now, None, limit)
+            .await
+    }
+
+    /// Continues the bounded expired-claim read after an opaque prior probe.
+    ///
+    /// Keyset pagination prevents an unsafe or still-present first claim from
+    /// starving later absent claims without persisting worker state in V12.
+    pub async fn list_expired_artifact_reconciliation_probes_after(
+        &self,
+        now: time::OffsetDateTime,
+        after: Option<&ArtifactExpiredClaimProbe>,
+        limit: u32,
+    ) -> Result<Vec<ArtifactExpiredClaimProbe>, RegistryError> {
+        let limit = limit.min(MAX_ARTIFACT_CLAIM_RECOVERY_BATCH);
+        if limit == 0 {
+            return Ok(Vec::new());
+        }
+        let after_expires_at = after.map(ArtifactExpiredClaimProbe::claim_expires_at);
+        let after_digest = after.map(|probe| probe.artifact_ref().digest_hex());
+        let rows = sqlx::query(
+            "select artifact_ref, claim_token, claim_expires_at
+               from artifact_blobs
+              where claim_token is not null
+                and claim_expires_at <= $1
+                and (
+                    $2::timestamptz is null
+                    or (claim_expires_at, digest) > ($2::timestamptz, $3::text)
+                )
+              order by claim_expires_at asc, digest asc
+              limit $4",
+        )
+        .bind(now)
+        .bind(after_expires_at)
+        .bind(after_digest)
+        .bind(i64::from(limit))
+        .fetch_all(self.pool())
+        .await?;
+        rows.into_iter()
+            .map(|row| {
+                let artifact_ref = ArtifactRef::parse(&row.try_get::<String, _>("artifact_ref")?)
+                    .map_err(|_| RegistryError::InvalidArtifactSource {
+                    field: "artifact_ref",
+                })?;
+                let prior_token = row.try_get::<Option<String>, _>("claim_token")?.ok_or(
+                    RegistryError::InvalidArtifactSource {
+                        field: "claim_token",
+                    },
+                )?;
+                let claim_expires_at = row
+                    .try_get::<Option<time::OffsetDateTime>, _>("claim_expires_at")?
+                    .ok_or(RegistryError::InvalidArtifactSource {
+                        field: "claim_expires_at",
+                    })?;
+                Ok(ArtifactExpiredClaimProbe::new(
+                    artifact_ref,
+                    prior_token,
+                    claim_expires_at,
+                ))
+            })
+            .collect()
+    }
+
+    /// Compare-and-swap steals an expired probe after recovery observed absence.
+    ///
+    /// The caller must probe physical state again after a successful claim: a
+    /// concurrent scanner may have changed the inode between the read and CAS.
+    pub async fn claim_expired_artifact_reconciliation(
+        &self,
+        probe: &ArtifactExpiredClaimProbe,
+        request: ClaimExpiredArtifactReconciliationRequest,
+    ) -> Result<Option<ArtifactReconciliationClaim>, RegistryError> {
+        let lease_duration = validate_claim_lease(request.claimed_at, request.lease_expires_at)?;
+        if request.token.as_str() == probe.prior_token() {
+            return Err(RegistryError::InvalidArtifactSource {
+                field: "claim_token",
+            });
+        }
+        let mut transaction = self.pool().begin().await?;
+        let Some(row) =
+            lock_blob_optional(&mut transaction, probe.artifact_ref().digest_hex()).await?
+        else {
+            transaction.rollback().await?;
+            return Ok(None);
+        };
+        let database_now = database_now(&mut transaction).await?;
+        let current_token = row.try_get::<Option<String>, _>("claim_token")?;
+        let expires_at = row.try_get::<Option<time::OffsetDateTime>, _>("claim_expires_at")?;
+        if current_token.as_deref() != Some(probe.prior_token())
+            || expires_at.is_none_or(|value| value > database_now)
+        {
+            transaction.rollback().await?;
+            return Ok(None);
+        }
+        let claimed = sqlx::query(
+            "update artifact_blobs
+                set claim_token = $1,
+                    claim_expires_at = $2,
+                    updated_at = greatest(updated_at, $3)
+              where digest = $4
+                and claim_token = $5
+                and claim_expires_at <= $3",
+        )
+        .bind(request.token.as_str())
+        .bind(database_now + lease_duration)
+        .bind(database_now)
+        .bind(probe.artifact_ref().digest_hex())
+        .bind(probe.prior_token())
+        .execute(&mut *transaction)
+        .await?
+        .rows_affected()
+            == 1;
+        transaction.commit().await?;
+        Ok(claimed
+            .then(|| ArtifactReconciliationClaim::new(probe.artifact_ref().clone(), request.token)))
+    }
+
+    /// Rechecks an owned claim immediately before blocking filesystem I/O.
+    ///
+    /// `create_artifact_source` holds the same blob lock and rejects any active
+    /// claim, so a `Mutate` outcome fences the recheck-to-filesystem window.
+    pub async fn recheck_artifact_reconciliation_claim(
+        &self,
+        claim: &ArtifactReconciliationClaim,
+        _now: time::OffsetDateTime,
+        detached_grace: time::Duration,
+    ) -> Result<ArtifactClaimRecheckOutcome, RegistryError> {
+        if detached_grace.is_negative() {
+            return Err(RegistryError::InvalidArtifactSource {
+                field: "detached_grace",
+            });
+        }
+        let mut transaction = self.pool().begin().await?;
+        let Some(row) =
+            lock_blob_optional(&mut transaction, claim.artifact_ref().digest_hex()).await?
+        else {
+            transaction.rollback().await?;
+            return Ok(ArtifactClaimRecheckOutcome::Stale);
+        };
+        let database_now = database_now(&mut transaction).await?;
+        let current_token = row.try_get::<Option<String>, _>("claim_token")?;
+        let expires_at = row.try_get::<Option<time::OffsetDateTime>, _>("claim_expires_at")?;
+        if current_token.as_deref() != Some(claim.token().as_str())
+            || expires_at.is_none_or(|value| value <= database_now)
+        {
+            transaction.rollback().await?;
+            return Ok(ArtifactClaimRecheckOutcome::Stale);
+        }
+        if global_active_reference(&mut transaction, claim.artifact_ref().digest_hex()).await? {
+            transaction.commit().await?;
+            return Ok(ArtifactClaimRecheckOutcome::ActiveReference);
+        }
+        if global_detached_reference_in_grace(
+            &mut transaction,
+            claim.artifact_ref().digest_hex(),
+            checked_cutoff(database_now, detached_grace)?,
+        )
+        .await?
+        {
+            transaction.commit().await?;
+            return Ok(ArtifactClaimRecheckOutcome::DetachedReferenceInGrace);
+        }
+        transaction.commit().await?;
+        Ok(ArtifactClaimRecheckOutcome::Mutate)
+    }
+
+    /// Records a filesystem observation without performing filesystem I/O.
+    ///
+    /// Only confirmed absence clears the claim and transitions V12 metadata to
+    /// `unavailable`; every ambiguous observation deliberately retains it for
+    /// a later bounded recovery attempt.
+    pub async fn finalize_artifact_reconciliation_claim(
+        &self,
+        claim: &ArtifactReconciliationClaim,
+        observation: ArtifactClaimFinalization,
+        _observed_at: time::OffsetDateTime,
+    ) -> Result<ArtifactClaimFinalizeOutcome, RegistryError> {
+        let mut transaction = self.pool().begin().await?;
+        let Some(row) =
+            lock_blob_optional(&mut transaction, claim.artifact_ref().digest_hex()).await?
+        else {
+            transaction.rollback().await?;
+            return Ok(ArtifactClaimFinalizeOutcome::Stale);
+        };
+        let database_now = database_now(&mut transaction).await?;
+        let current_token = row.try_get::<Option<String>, _>("claim_token")?;
+        let expires_at = row.try_get::<Option<time::OffsetDateTime>, _>("claim_expires_at")?;
+        if current_token.as_deref() != Some(claim.token().as_str())
+            || expires_at.is_none_or(|value| value <= database_now)
+        {
+            transaction.rollback().await?;
+            return Ok(ArtifactClaimFinalizeOutcome::Stale);
+        }
+
+        let (lifecycle, clear_claim, outcome) = match observation {
+            ArtifactClaimFinalization::Deleted | ArtifactClaimFinalization::AlreadyAbsent => (
+                "unavailable",
+                true,
+                ArtifactClaimFinalizeOutcome::Unavailable,
+            ),
+            ArtifactClaimFinalization::Quarantined | ArtifactClaimFinalization::Retryable => {
+                ("available", false, ArtifactClaimFinalizeOutcome::Retained)
+            }
+        };
+        let updated = if clear_claim {
+            sqlx::query(
+                "update artifact_blobs
+                    set storage_lifecycle = $1, claim_token = null, claim_expires_at = null,
+                        updated_at = greatest(updated_at, $2)
+                  where digest = $3 and claim_token = $4 and claim_expires_at > $2",
+            )
+            .bind(lifecycle)
+            .bind(database_now)
+            .bind(claim.artifact_ref().digest_hex())
+            .bind(claim.token().as_str())
+            .execute(&mut *transaction)
+            .await?
+            .rows_affected()
+        } else {
+            sqlx::query(
+                "update artifact_blobs
+                    set updated_at = greatest(updated_at, $1)
+                  where digest = $2 and claim_token = $3 and claim_expires_at > $1",
+            )
+            .bind(database_now)
+            .bind(claim.artifact_ref().digest_hex())
+            .bind(claim.token().as_str())
+            .execute(&mut *transaction)
+            .await?
+            .rows_affected()
+        };
+        if updated != 1 {
+            transaction.rollback().await?;
+            return Ok(ArtifactClaimFinalizeOutcome::Stale);
+        }
+        transaction.commit().await?;
+        Ok(outcome)
+    }
+
+    /// Alias used by startup recovery once its filesystem probe has produced a
+    /// typed observation. The registry never performs the probe itself.
+    pub async fn recover_artifact_reconciliation_claim(
+        &self,
+        claim: &ArtifactReconciliationClaim,
+        observation: ArtifactClaimFinalization,
+        recovered_at: time::OffsetDateTime,
+    ) -> Result<ArtifactClaimFinalizeOutcome, RegistryError> {
+        self.finalize_artifact_reconciliation_claim(claim, observation, recovered_at)
+            .await
+    }
+
     pub async fn create_artifact_source(
         &self,
         request: CreateArtifactSourceRequest<'_>,
@@ -254,6 +608,41 @@ async fn ensure_blob(
             field: "size_bytes",
         }
     })?;
+    insert_blob_if_missing(
+        transaction,
+        request.artifact.artifact_ref(),
+        size_bytes,
+        request.created_at,
+    )
+    .await?;
+
+    let row = lock_blob(transaction, digest).await?;
+    if !blob_metadata_matches(&row, request.artifact.artifact_ref(), size_bytes)? {
+        return Err(source_conflict(request.source_id));
+    }
+    if row.try_get::<Option<String>, _>("claim_token")?.is_some() {
+        return Err(RegistryError::ArtifactClaimInProgress);
+    }
+    if row.try_get::<String, _>("storage_lifecycle")? == "unavailable" {
+        sqlx::query(
+            "update artifact_blobs
+                set storage_lifecycle = 'available', updated_at = greatest(updated_at, $1)
+              where digest = $2 and claim_token is null",
+        )
+        .bind(request.created_at)
+        .bind(digest)
+        .execute(&mut **transaction)
+        .await?;
+    }
+    Ok(())
+}
+
+async fn insert_blob_if_missing(
+    transaction: &mut Transaction<'_, Postgres>,
+    artifact_ref: &ArtifactRef,
+    size_bytes: i64,
+    created_at: time::OffsetDateTime,
+) -> Result<(), RegistryError> {
     sqlx::query(
         "insert into artifact_blobs (
             digest, artifact_ref, size_bytes, storage_lifecycle,
@@ -261,25 +650,87 @@ async fn ensure_blob(
          ) values ($1, $2, $3, 'available', null, null, $4, $4)
          on conflict (digest) do nothing",
     )
-    .bind(digest)
-    .bind(request.artifact.artifact_ref().as_str())
+    .bind(artifact_ref.digest_hex())
+    .bind(artifact_ref.as_str())
     .bind(size_bytes)
-    .bind(request.created_at)
+    .bind(created_at)
     .execute(&mut **transaction)
     .await?;
+    Ok(())
+}
 
-    let row = sqlx::query(
-        "select artifact_ref, size_bytes from artifact_blobs where digest = $1 for update",
+async fn lock_blob(
+    transaction: &mut Transaction<'_, Postgres>,
+    digest: &str,
+) -> Result<PgRow, RegistryError> {
+    lock_blob_optional(transaction, digest)
+        .await?
+        .ok_or(RegistryError::InvalidArtifactSource {
+            field: "artifact_blob",
+        })
+}
+
+async fn lock_blob_optional(
+    transaction: &mut Transaction<'_, Postgres>,
+    digest: &str,
+) -> Result<Option<PgRow>, RegistryError> {
+    sqlx::query(
+        "select artifact_ref, size_bytes, storage_lifecycle, claim_token, claim_expires_at
+           from artifact_blobs
+          where digest = $1
+          for update",
+    )
+    .bind(digest)
+    .fetch_optional(&mut **transaction)
+    .await
+    .map_err(Into::into)
+}
+
+fn blob_metadata_matches(
+    row: &PgRow,
+    artifact_ref: &ArtifactRef,
+    size_bytes: i64,
+) -> Result<bool, RegistryError> {
+    Ok(
+        row.try_get::<String, _>("artifact_ref")? == artifact_ref.as_str()
+            && row.try_get::<i64, _>("size_bytes")? == size_bytes,
+    )
+}
+
+async fn global_active_reference(
+    transaction: &mut Transaction<'_, Postgres>,
+    digest: &str,
+) -> Result<bool, RegistryError> {
+    sqlx::query_scalar::<_, bool>(
+        "select exists(
+            select 1 from artifact_sources
+             where blob_digest = $1 and lifecycle = 'active'
+         )",
     )
     .bind(digest)
     .fetch_one(&mut **transaction)
-    .await?;
-    let recorded_ref = row.try_get::<String, _>("artifact_ref")?;
-    let recorded_size = row.try_get::<i64, _>("size_bytes")?;
-    if recorded_ref != request.artifact.artifact_ref().as_str() || recorded_size != size_bytes {
-        return Err(source_conflict(request.source_id));
-    }
-    Ok(())
+    .await
+    .map_err(Into::into)
+}
+
+async fn global_detached_reference_in_grace(
+    transaction: &mut Transaction<'_, Postgres>,
+    digest: &str,
+    detached_after: time::OffsetDateTime,
+) -> Result<bool, RegistryError> {
+    sqlx::query_scalar::<_, bool>(
+        "select exists(
+            select 1 from artifact_sources
+             where blob_digest = $1
+               and lifecycle = 'detached'
+               and detached_at > $2
+         )",
+    )
+    .bind(digest)
+    .bind(detached_after)
+    .fetch_one(&mut **transaction)
+    .await
+    .map_err(Into::into)
 }
 
 async fn get_source_in_transaction(

crates/crank-registry/src/postgres/artifact_source/reconciliation.rs

@@ -0,0 +1,68 @@
+use crank_artifacts::ArtifactRef;
+use sqlx::{Postgres, Transaction};
+
+use crate::{PostgresRegistry, RegistryError};
+
+const MAX_ARTIFACT_CLAIM_LEASE: time::Duration = time::Duration::minutes(5);
+
+impl PostgresRegistry {
+    /// Returns the PostgreSQL clock used by production reconciliation leases.
+    pub async fn artifact_reconciliation_now(&self) -> Result<time::OffsetDateTime, RegistryError> {
+        sqlx::query_scalar("select clock_timestamp()")
+            .fetch_one(self.pool())
+            .await
+            .map_err(RegistryError::from)
+    }
+}
+
+pub(super) async fn insert_blob_if_missing_at_database_time(
+    transaction: &mut Transaction<'_, Postgres>,
+    artifact_ref: &ArtifactRef,
+    size_bytes: i64,
+) -> Result<(), RegistryError> {
+    sqlx::query(
+        "insert into artifact_blobs (
+            digest, artifact_ref, size_bytes, storage_lifecycle,
+            claim_token, claim_expires_at, created_at, updated_at
+         ) values ($1, $2, $3, 'available', null, null, clock_timestamp(), clock_timestamp())
+         on conflict (digest) do nothing",
+    )
+    .bind(artifact_ref.digest_hex())
+    .bind(artifact_ref.as_str())
+    .bind(size_bytes)
+    .execute(&mut **transaction)
+    .await?;
+    Ok(())
+}
+
+pub(super) fn validate_claim_lease(
+    claimed_at: time::OffsetDateTime,
+    lease_expires_at: time::OffsetDateTime,
+) -> Result<time::Duration, RegistryError> {
+    let duration = lease_expires_at - claimed_at;
+    if duration <= time::Duration::ZERO || duration > MAX_ARTIFACT_CLAIM_LEASE {
+        return Err(RegistryError::InvalidArtifactSource {
+            field: "claim_lease",
+        });
+    }
+    Ok(duration)
+}
+
+pub(super) fn checked_cutoff(
+    now: time::OffsetDateTime,
+    grace: time::Duration,
+) -> Result<time::OffsetDateTime, RegistryError> {
+    now.checked_sub(grace)
+        .ok_or(RegistryError::InvalidArtifactSource {
+            field: "detached_grace",
+        })
+}
+
+pub(super) async fn database_now(
+    transaction: &mut Transaction<'_, Postgres>,
+) -> Result<time::OffsetDateTime, RegistryError> {
+    sqlx::query_scalar("select clock_timestamp()")
+        .fetch_one(&mut **transaction)
+        .await
+        .map_err(Into::into)
+}