loader-entries: Add set-options-for-source for source-tracked kargs

Add a new `bootc loader-entries set-options-for-source` command that
manages kernel arguments from independent sources (e.g. TuneD, admin)
by tracking ownership via `x-options-source-<name>` extension keys in
BLS config files. This solves the problem of karg accumulation on bootc
systems with transient /etc, where tools like TuneD lose their state
files on reboot and cannot track which kargs they previously set.

The command stages a new deployment with the updated kargs and source
keys. The kargs diff is computed by removing the old source's args and
adding the new ones, preserving all untracked options. Source keys
survive the staging roundtrip via ostree's `bootconfig-extra`
serialization (ostree >= 2026.1, version check active).

Staged deployment handling:
- No staged deployment: stages based on the booted commit
- Staged deployment exists (e.g. from `bootc upgrade`): replaces it
  using the staged commit and origin, preserving pending upgrades while
  layering the source kargs change on top

Includes a multi-reboot TMT integration test covering: input validation,
kargs surviving staging roundtrip, source replacement, multiple sources
coexisting (including pre-reboot), source removal, idempotency, system
kargs preservation, empty --options vs no --options, and staged
deployment interaction with bootc switch.

Example usage:
  bootc loader-entries set-options-for-source --source tuned \
    --options "isolcpus=1-3 nohz_full=1-3"

Closes: #899
See: ostreedev/ostree#3570

Assisted-by: OpenCode (Claude Opus 4.6)
Signed-off-by: Joseph Marrero Corchado <jmarrero@redhat.com>

Author: jmarrero

crates/lib/src/cli.rs

@@ -716,6 +716,54 @@ pub(crate) enum InternalsOpts {
     },
 }
 
+/// Options for the `set-options-for-source` subcommand.
+#[derive(Debug, Parser, PartialEq, Eq)]
+pub(crate) struct SetOptionsForSourceOpts {
+    /// The name of the source that owns these kernel arguments.
+    ///
+    /// Must contain only alphanumeric characters, hyphens, or underscores.
+    /// Examples: "tuned", "admin", "bootc-kargs-d"
+    #[clap(long)]
+    pub(crate) source: String,
+
+    /// The kernel arguments to set for this source.
+    ///
+    /// If not provided, the source is removed and its options are
+    /// dropped from the merged `options` line.
+    #[clap(long)]
+    pub(crate) options: Option<String>,
+}
+
+/// Operations on Boot Loader Specification (BLS) entries.
+///
+/// These commands support managing kernel arguments from multiple independent
+/// sources (e.g., TuneD, admin, bootc kargs.d) by tracking argument ownership
+/// via `x-options-source-<name>` extension keys in BLS config files.
+///
+/// See <https://github.com/ostreedev/ostree/pull/3570>
+#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
+pub(crate) enum LoaderEntriesOpts {
+    /// Set or update the kernel arguments owned by a specific source.
+    ///
+    /// Each source's arguments are tracked via `x-options-source-<name>`
+    /// keys in BLS config files. The `options` line is recomputed as the
+    /// merge of all tracked sources plus any untracked (pre-existing) options.
+    ///
+    /// This stages a new deployment with the updated kernel arguments.
+    ///
+    /// ## Examples
+    ///
+    /// Add TuneD kernel arguments:
+    /// bootc loader-entries set-options-for-source --source tuned --options "isolcpus=1-3 nohz_full=1-3"
+    ///
+    /// Update TuneD kernel arguments:
+    /// bootc loader-entries set-options-for-source --source tuned --options "isolcpus=0-7"
+    ///
+    /// Remove TuneD kernel arguments:
+    /// bootc loader-entries set-options-for-source --source tuned
+    SetOptionsForSource(SetOptionsForSourceOpts),
+}
+
 #[derive(Debug, clap::Subcommand, PartialEq, Eq)]
 pub(crate) enum StateOpts {
     /// Remove all ostree deployments from this system
@@ -821,6 +869,11 @@ pub(crate) enum Opt {
     /// Stability: This interface may change in the future.
     #[clap(subcommand, hide = true)]
     Image(ImageOpts),
+    /// Operations on Boot Loader Specification (BLS) entries.
+    ///
+    /// Manage kernel arguments from multiple independent sources.
+    #[clap(subcommand)]
+    LoaderEntries(LoaderEntriesOpts),
     /// Execute the given command in the host mount namespace
     #[clap(hide = true)]
     ExecInHostMountNamespace {
@@ -1899,6 +1952,18 @@ async fn run_from_opt(opt: Opt) -> Result<()> {
                 crate::install::install_finalize(&root_path).await
             }
         },
+        Opt::LoaderEntries(opts) => match opts {
+            LoaderEntriesOpts::SetOptionsForSource(opts) => {
+                let storage = get_storage().await?;
+                let sysroot = storage.get_ostree()?;
+                crate::loader_entries::set_options_for_source_staged(
+                    sysroot,
+                    &opts.source,
+                    opts.options.as_deref(),
+                )?;
+                Ok(())
+            }
+        },
         Opt::ExecInHostMountNamespace { args } => {
             crate::install::exec_in_host_mountns(args.as_slice())
         }

crates/lib/src/lib.rs

@@ -82,6 +82,7 @@ pub(crate) mod journal;
 mod k8sapitypes;
 mod kernel;
 mod lints;
+mod loader_entries;
 mod lsm;
 pub(crate) mod metadata;
 mod parsers;