feat(generate-lockfile): Add unstable --publish-time flag (#16265)

### What does this PR try to resolve?

Implementation for #5221, #15491

Tracking issues: #16270, #16271

Use cases:
- Improved reproduction steps using cargo scripts without including a
  lockfile
- Debugging issues in the past
- Manual stop gap for #15973

This seemed like the shortest path to testing the proposed `pubtime`
index entries (#15491) so we can unblock other work on it like #15973.
While this has some big caveats, the design is straightforward.
In contrast, #15973 has a lot more design questions (is this a
resolver-wide setting or a per-registry setting, what formats are
accepted, etc) that could slow down development and testing `pubtime`.

### How to test and review this PR?

Unresolved questions (deferred to the tracking issues):
- How do we compensate for the caveats, with one option being to leave
  this perma-unstable?
- How should we deal with Summary `pubtime` parse errors?
- How strict should we be on the Summary `pubtime` format?
- Should we offer a convenient way of getting a compatible timestamp?

Future possibilities:
- Ability to lock to a timestamp with `cargo update` updating the
  timestamp (could be useful for cargo scripts)

Author: weihanglo

Cargo.lock

@@ -34,7 +34,7 @@ cargo-platform = { path = "crates/cargo-platform", version = "0.3.0" }
 cargo-test-macro = { version = "0.4.8", path = "crates/cargo-test-macro" }
 cargo-test-support = { version = "0.9.1", path = "crates/cargo-test-support" }
 cargo-util = { version = "0.2.26", path = "crates/cargo-util" }
-cargo-util-schemas = { version = "0.10.3", path = "crates/cargo-util-schemas" }
+cargo-util-schemas = { version = "0.11.0", path = "crates/cargo-util-schemas" }
 cargo_metadata = "0.23.1"
 clap = "4.5.51"
 clap_complete = { version = "4.5.60", features = ["unstable-dynamic"] }

Cargo.toml

@@ -228,6 +228,7 @@ pub(crate) fn create_index_line(
     yanked: bool,
     links: Option<String>,
     rust_version: Option<&str>,
+    pubtime: Option<&str>,
     v: Option<u32>,
 ) -> String {
     // This emulates what crates.io does to retain backwards compatibility.
@@ -251,6 +252,9 @@ pub(crate) fn create_index_line(
     if let Some(rust_version) = rust_version {
         json["rust_version"] = serde_json::json!(rust_version);
     }
+    if let Some(pubtime) = pubtime {
+        json["pubtime"] = serde_json::json!(pubtime);
+    }
 
     json.to_string()
 }

crates/cargo-test-support/src/publish.rs

@@ -578,6 +578,7 @@ pub struct Package {
     links: Option<String>,
     rust_version: Option<String>,
     cargo_features: Vec<String>,
+    pubtime: Option<String>,
     v: Option<u32>,
 }
 
@@ -1243,6 +1244,7 @@ fn save_new_crate(
         new_crate.links,
         new_crate.rust_version.as_deref(),
         None,
+        None,
     );
 
     write_to_index(registry_path, &new_crate.name, line, false);
@@ -1273,6 +1275,7 @@ impl Package {
             links: None,
             rust_version: None,
             cargo_features: Vec::new(),
+            pubtime: None,
             v: None,
         }
     }
@@ -1460,6 +1463,12 @@ impl Package {
         self
     }
 
+    /// The publish time for the package in ISO8601 with UTC timezone (e.g. 2025-11-12T19:30:12Z)
+    pub fn pubtime(&mut self, time: &str) -> &mut Package {
+        self.pubtime = Some(time.to_owned());
+        self
+    }
+
     /// Sets the index schema version for this package.
     ///
     /// See `cargo::sources::registry::IndexPackage` for more information.
@@ -1536,6 +1545,7 @@ impl Package {
                 self.yanked,
                 self.links.clone(),
                 self.rust_version.as_deref(),
+                self.pubtime.as_deref(),
                 self.v,
             )
         };

crates/cargo-test-support/src/registry.rs

@@ -1,6 +1,6 @@
 [package]
 name = "cargo-util-schemas"
-version = "0.10.3"
+version = "0.11.0"
 rust-version = "1.91"  # MSRV:1
 edition.workspace = true
 license.workspace = true

crates/cargo-util-schemas/Cargo.toml

@@ -68,6 +68,13 @@
         "null"
       ]
     },
+    "pubtime": {
+      "description": "The publish time for the package.  Unstable.\n\nIn ISO8601 with UTC timezone (e.g. 2025-11-12T19:30:12Z)",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
     "v": {
       "description": "The schema version for this entry.\n\nIf this is None, it defaults to version `1`. Entries with unknown\nversions are ignored.\n\nVersion `2` schema adds the `features2` field.\n\nVersion `3` schema adds `artifact`, `bindep_targes`, and `lib` for\nartifact dependencies support.\n\nThis provides a method to safely introduce changes to index entries\nand allow older versions of cargo to ignore newer entries it doesn't\nunderstand. This is honored as of 1.51, so unfortunately older\nversions will ignore it, and potentially misinterpret version 2 and\nnewer entries.\n\nThe intent is that versions older than 1.51 will work with a\npre-existing `Cargo.lock`, but they may not correctly process `cargo\nupdate` or build a lock from scratch. In that case, cargo may\nincorrectly select a new package that uses a new index schema. A\nworkaround is to downgrade any packages that are incompatible with the\n`--precise` flag of `cargo update`.",
       "type": [

crates/cargo-util-schemas/index.schema.json

@@ -46,6 +46,10 @@ pub struct IndexPackage<'a> {
     /// can be `None` if published before then or if not set in the manifest.
     #[cfg_attr(feature = "unstable-schema", schemars(with = "Option<String>"))]
     pub rust_version: Option<RustVersion>,
+    /// The publish time for the package.  Unstable.
+    ///
+    /// In ISO8601 with UTC timezone (e.g. 2025-11-12T19:30:12Z)
+    pub pubtime: Option<String>,
     /// The schema version for this entry.
     ///
     /// If this is None, it defaults to version `1`. Entries with unknown

crates/cargo-util-schemas/src/index.rs

@@ -1,3 +1,6 @@
+use clap_complete::engine::ArgValueCompleter;
+use clap_complete::engine::CompletionCandidate;
+
 use crate::command_prelude::*;
 
 use cargo::ops;
@@ -9,13 +12,46 @@ pub fn cli() -> Command {
         .arg_manifest_path()
         .arg_lockfile_path()
         .arg_ignore_rust_version_with_help("Ignore `rust-version` specification in packages")
+        .arg(
+            clap::Arg::new("publish-time")
+                .long("publish-time")
+                .value_name("yyyy-mm-ddThh:mm:ssZ")
+                .add(ArgValueCompleter::new(datetime_completer))
+                .help("Latest publish time allowed for registry packages (unstable)")
+                .help_heading(heading::MANIFEST_OPTIONS)
+        )
         .after_help(color_print::cstr!(
             "Run `<bright-cyan,bold>cargo help generate-lockfile</>` for more detailed information.\n"
         ))
 }
 
+fn datetime_completer(current: &std::ffi::OsStr) -> Vec<CompletionCandidate> {
+    let mut completions = vec![];
+    let Some(current) = current.to_str() else {
+        return completions;
+    };
+
+    if current.is_empty() {
+        // While not likely what people want, it can at least give them a starting point to edit
+        let timestamp = jiff::Timestamp::now();
+        completions.push(CompletionCandidate::new(timestamp.to_string()));
+    } else if let Ok(date) = current.parse::<jiff::civil::Date>() {
+        if let Ok(zoned) = jiff::Zoned::default().with().date(date).build() {
+            let timestamp = zoned.timestamp();
+            completions.push(CompletionCandidate::new(timestamp.to_string()));
+        }
+    }
+    completions
+}
+
 pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
-    let ws = args.workspace(gctx)?;
+    let publish_time = args.get_one::<String>("publish-time");
+    let mut ws = args.workspace(gctx)?;
+    if let Some(publish_time) = publish_time {
+        gctx.cli_unstable()
+            .fail_if_stable_opt("--publish-time", 5221)?;
+        ws.set_resolve_publish_time(publish_time.parse().map_err(anyhow::Error::from)?);
+    }
     ops::generate_lockfile(&ws)?;
     Ok(())
 }

src/bin/cargo/commands/generate_lockfile.rs

@@ -22,6 +22,7 @@ pub struct VersionPreferences {
     prefer_patch_deps: HashMap<InternedString, HashSet<Dependency>>,
     version_ordering: VersionOrdering,
     rust_versions: Vec<PartialVersion>,
+    publish_time: Option<jiff::Timestamp>,
 }
 
 #[derive(Copy, Clone, Default, PartialEq, Eq, Hash, Debug)]
@@ -53,6 +54,10 @@ impl VersionPreferences {
         self.rust_versions = vers;
     }
 
+    pub fn publish_time(&mut self, publish_time: jiff::Timestamp) {
+        self.publish_time = Some(publish_time);
+    }
+
     /// Sort (and filter) the given vector of summaries in-place
     ///
     /// Note: all summaries presumed to be for the same package.
@@ -63,6 +68,7 @@ impl VersionPreferences {
     /// 3. `first_version`, falling back to [`VersionPreferences::version_ordering`] when `None`
     ///
     /// Filtering:
+    /// - `publish_time`
     /// - `first_version`
     pub fn sort_summaries(
         &self,
@@ -77,6 +83,15 @@ impl VersionPreferences {
                     .map(|deps| deps.iter().any(|d| d.matches_id(*pkg_id)))
                     .unwrap_or(false)
         };
+        if let Some(max_publish_time) = self.publish_time {
+            summaries.retain(|s| {
+                if let Some(summary_publish_time) = s.pubtime() {
+                    summary_publish_time <= max_publish_time
+                } else {
+                    true
+                }
+            });
+        }
         summaries.sort_unstable_by(|a, b| {
             let prefer_a = should_prefer(&a.package_id());
             let prefer_b = should_prefer(&b.package_id());

src/cargo/core/resolver/version_prefs.rs

@@ -29,6 +29,7 @@ struct Inner {
     checksum: Option<String>,
     links: Option<InternedString>,
     rust_version: Option<RustVersion>,
+    pubtime: Option<jiff::Timestamp>,
 }
 
 /// Indicates the dependency inferred from the `dep` syntax that should exist,
@@ -90,6 +91,7 @@ impl Summary {
                 checksum: None,
                 links: links.map(|l| l.into()),
                 rust_version,
+                pubtime: None,
             }),
         })
     }
@@ -124,6 +126,10 @@ impl Summary {
         self.inner.rust_version.as_ref()
     }
 
+    pub fn pubtime(&self) -> Option<jiff::Timestamp> {
+        self.inner.pubtime
+    }
+
     pub fn override_id(mut self, id: PackageId) -> Summary {
         Arc::make_mut(&mut self.inner).package_id = id;
         self
@@ -133,6 +139,10 @@ impl Summary {
         Arc::make_mut(&mut self.inner).checksum = Some(cksum);
     }
 
+    pub fn set_pubtime(&mut self, pubtime: jiff::Timestamp) {
+        Arc::make_mut(&mut self.inner).pubtime = Some(pubtime);
+    }
+
     pub fn map_dependencies<F>(self, mut f: F) -> Summary
     where
         F: FnMut(Dependency) -> Dependency,