Diffusion lands a bump itself where a repository chose it f4d6ef418a96

-- Diffusion auto-land (docs/diffusion.md §4.2, Andy's choice 2026-10-13):

-- whether this repository lands a bump itself once both halves of its pill

-- are green. `auto`, `propose`, or empty for propose (off by default); a

-- subrepo's `.oxymodules` entry (`land = auto | propose`) overrides it.

ALTER TABLE repositories ADD COLUMN diffusion_land TEXT NOT NULL DEFAULT '';

    /// `auto` or `propose`; absent keeps it as it is.

    #[serde(default)]

    land: Option<String>,

    };

    let land = match d.land.as_deref() {

        Some(l @ ("auto" | "propose")) => Some(l),

        None => None,

        Some(_) => return Err(ApiError(StatusCode::BAD_REQUEST, "land is auto or propose".into())),

    if let Some(l) = land {

        db::repos::set_diffusion_land(&app.db, row.id, l).await?;

    }

    if land == Some("auto") {

        let (app, row) = (app.clone(), row.clone());

        tokio::spawn(async move { crate::diffusion::land_ready(&app, &row).await });

    }

    Ok(Json(

        serde_json::json!({ "follow": rule.follow, "from": rule.from, "land": if row.diffusion_land == "auto" { "auto" } else { "propose" } }),

    ))

    match crate::web::proposals::land_as(&app, &repo, &row, &me, number, &via, false).await {

    /// Diffusion auto-land: `auto`, `propose`, or empty for propose

    /// (migration 0061).

    #[sqlx(default)]

    pub diffusion_land: String,

    Ok(())

}

pub async fn set_diffusion_land(pool: &Pool, id: i64, setting: &str) -> sqlx::Result<()> {

    sqlx::query("UPDATE repositories SET diffusion_land = ? WHERE id = ?").bind(setting).bind(id).execute(pool).await?;

    (why, watch, lands): (Why, Vec<String>, bool),

        "Moves the subrepo `{path}` to [{slug}](/{slug})'s `{ub}`, {when} (`{}`). Only the pin changes; this repository's own checks test it.{amber}{flagged}\n\n**What it brings** ({count}):\n\n{}\n\nOpened and kept up to date by Diffusion (docs/diffusion.md). {}",

        lines.join("\n"),

        if lands {

            "This repository lands its bumps itself (`land = auto`): it lands once the upstream state it pins has passed its own checks and this repository's run on it passes, unless its required checks, approvals or trust policy say otherwise. An untested upstream always waits for a person."

        } else {

            "It never lands by itself."

        }

                let n = propose(app, &consumer, &target, &path, upstream, (from, heads.clone()), (why, r.watch.clone(), r.land_auto)).await;

                propose(app, &consumer, &target, &path, upstream, (from, to), (why, r.watch.clone(), r.land_auto)).await;

                // The upstream may just have turned green under a bump its

                // consumer already passed.

                if green && r.land_auto {

                    tokio::spawn(try_land(app.clone(), consumer.clone(), path.clone()));

                }

}

/// Why a bump was not landed by itself (docs/diffusion.md §4.2).

#[derive(Debug, PartialEq, Eq)]

pub enum Held {

    /// No open bump at that path.

    NoBump,

    /// The consumer did not choose `land = auto`.

    Manual,

    /// The upstream has no checks: amber never lands by itself.

    Unverified,

    /// The upstream state the bump pins has no passing run.

    UpstreamUnchecked,

    /// The consumer's run on the bump as it is now has not passed.

    NotPassed,

    /// The landing was refused (required checks, approvals, the trust policy).

    Refused(String),

/// Land the open bump at `path` in `consumer` itself, as the `diffusion`

/// account, when the consumer chose `land = auto` (its `.oxymodules` entry,

/// else Settings › Diffusion) and both halves of its pill are green: the

/// upstream state it pins passed its own run (never amber: an upstream

/// with no checks always waits for a person), and the consumer's run on

/// the bump as it is now passed. It lands through the web's own path

/// (`land_as`), signed by the hub's key, so required checks, approvals and

/// the trust policy decide as for anyone; a refusal is noted once on the

/// proposal's timeline. The proposal's number when it landed.

pub async fn auto_land(app: &Shared, consumer: &RepoRow, path: &str) -> Result<i64, Held> {

    let path = path.trim_matches('/');

    let bm = bump_bookmark(path);

    let Some(cname) = RepoName::new(&consumer.owner, &consumer.name) else { return Err(Held::NoBump) };

    let bump = db::proposals::list(&app.db, consumer.id, &["open"])

        .await

        .ok()

        .and_then(|ps| ps.into_iter().find(|p| p.source_bookmark == bm && p.author == ACCOUNT))

        .ok_or(Held::NoBump)?;

    let learned = target(&app.db, consumer).await;

    let modules = oxymodules(app, &cname, &learned).await;

    if !rule(&app.config.diffusion.follow, consumer, modules.as_deref(), path).land_auto {

        return Err(Held::Manual);

    }

    let upstream_id: Option<i64> = sqlx::query_scalar(

        "SELECT upstream_repo_id FROM diffusion_pins WHERE consumer_id = ? AND path = ? AND upstream_repo_id IS NOT NULL LIMIT 1",

    )

    .bind(consumer.id)

    .bind(path)

    .fetch_optional(&app.db)

    .await

    .ok()

    .flatten();

    let Some(upstream) = (match upstream_id {

        Some(id) => db::repos::get_by_id(&app.db, id).await.ok().flatten(),

        None => None,

    }) else {

        return Err(Held::UpstreamUnchecked);

    };

    if unverified(app, &upstream).await {

        return Err(Held::Unverified);

    }

    // What the bump pins, and the bump bookmark's heads now.

    let (p, b) = (path.to_string(), bm.clone());

    let (pinned, now) = app

        .repos

        .read(&cname, move |r, cache| {

            let heads = heads_of(r, &b)?;

            if heads.is_empty() {

                return Ok((None, heads));

            }

            let loaded = cache.load(r, &heads)?;

            let pin = match loaded.snapshot.files.get(&p).map(|f| &f.content) {

                Some(oxy_core::state::FileContent::Opaque { blobs }) => match blobs.first() {

                    Some(blob) => oxy_core::subrepo::Pin::decode(&r.read_blob(blob)?).ok(),

                    None => None,

                },

                _ => None,

            };

            Ok((pin, heads))

        })

        .await

        .map_err(|e| Held::Refused(e.to_string()))?;

    let Some(oxy_core::subrepo::Pin::Oxy { heads: pinned, .. }) = pinned else { return Err(Held::UpstreamUnchecked) };

    let same = |text: &str, want: &[ChangeHash]| {

        let mut a: Vec<String> = text.split('+').filter(|h| !h.is_empty()).map(str::to_string).collect();

        let mut b: Vec<String> = want.iter().map(|h| h.to_hex()).collect();

        a.sort();

        b.sort();

        a == b

    };

    let upstream_runs: Vec<String> = sqlx::query_scalar(

        "SELECT heads FROM flow_runs WHERE repo_id = ? AND bookmark = ? AND status = 'passed' ORDER BY id DESC LIMIT 100",

    )

    .bind(upstream.id)

    .bind(&upstream.default_bookmark)

    .fetch_all(&app.db)

    .await

    .unwrap_or_default();

    if !upstream_runs.iter().any(|h| same(h, &pinned)) {

        return Err(Held::UpstreamUnchecked);

    }

    let run: Option<(String, String)> =

        sqlx::query_as("SELECT status, heads FROM flow_runs WHERE repo_id = ? AND bookmark = ? ORDER BY id DESC LIMIT 1")

            .bind(consumer.id)

            .bind(&bm)

            .fetch_optional(&app.db)

            .await

            .ok()

            .flatten();

    if !run.is_some_and(|(status, heads)| status == "passed" && same(&heads, &now)) {

        return Err(Held::NotPassed);

    }

    let me = account(&app.db).await.ok_or_else(|| Held::Refused("the diffusion account is missing".into()))?;

    let via = "Diffusion, both halves green";

    match crate::web::proposals::land_as(app, &cname, consumer, &me, bump.number, via, true).await {

        Ok(_) => {

            tracing::info!("diffusion: {}/{} landed #{} itself (both halves green)", consumer.owner, consumer.name, bump.number);

            Ok(bump.number)

        }

        Err(crate::web::proposals::Landing::NotFound) => Err(Held::NoBump),

        Err(crate::web::proposals::Landing::Refused(why)) => {

            // Said once, so the timeline explains why a green bump waits.

            let said = db::proposals::events(&app.db, bump.id)

                .await

                .unwrap_or_default()

                .iter()

                .any(|e| e.event == "not landed by itself" && e.detail == why);

            if !said {

                db::proposals::add_event(&app.db, bump.id, ACCOUNT, "not landed by itself", &why).await.ok();

            }

            Err(Held::Refused(why))

        }

    }

}

/// [`auto_land`] in the background, logged. Boxed as `Send`: a landing

/// moves the target as a push would, which may bump and land again.

pub fn try_land(app: Shared, consumer: RepoRow, path: String) -> std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send>> {

    Box::pin(async move {

        match auto_land(&app, &consumer, &path).await {

            Ok(_) | Err(Held::NoBump | Held::Manual) => {}

            Err(why) => tracing::info!("diffusion: {}/{} {path} waits for a person: {why:?}", consumer.owner, consumer.name),

        }

    })

}

/// Try every open bump of `consumer` (its setting turned to `auto`).

pub async fn land_ready(app: &Shared, consumer: &RepoRow) {

    let paths: Vec<String> = sqlx::query_scalar("SELECT DISTINCT path FROM diffusion_pins WHERE consumer_id = ?")

        .bind(consumer.id)

        .fetch_all(&app.db)

        .await

        .unwrap_or_default();

    for path in paths {

        tokio::spawn(try_land(app.clone(), consumer.clone(), path));

    }

}

    /// Land a bump itself once both halves are green (`land = auto`, or

    /// the repository's setting); otherwise it only proposes.

    // Landing by itself: the entry's word, else the setting; never by default.

    let land_auto = land.unwrap_or(row.diffusion_land == "auto");

    Rule { follow, land_auto, target, watch, from }

    }

    #[test]

    fn landing_by_itself_is_chosen_per_repository_and_per_entry() {

        let mut r = row("green");

        assert!(!rule("off", &r, None, "rstar-api").land_auto, "never by default");

        r.diffusion_land = "auto".into();

        assert!(rule("off", &r, None, "rstar-api").land_auto, "the setting");

        assert!(!rule("off", &r, Some(MODULES), "rstar-api").land_auto, "the entry's `land = propose` wins");

        assert!(rule("off", &r, Some(MODULES), "other").land_auto, "an entry without `land` takes the setting");

        r.diffusion_land = String::new();

        let auto = MODULES.replace(r#"land = "propose""#, "land = auto");

        assert!(rule("off", &r, Some(&auto), "rstar-api").land_auto);

        // A bump's run passed: a consumer that lands its bumps itself may

        // land it now (docs/diffusion.md §4.2).

        if let Some(path) = done.bookmark.strip_prefix("diffusion/").filter(|_| done.status == "passed") {

            tokio::spawn(crate::diffusion::try_land(app.clone(), row.clone(), path.to_string()));

        }

/// The hub's own key, acting for itself: how Diffusion lands a bump

/// (docs/diffusion.md §4.2). A trust policy admits it only where it

/// authorises the hub's key to move the bookmark.

pub fn hub_signer(app: &Shared) -> Result<Signer, String> {

    let (hub_key, hub_secret) = crate::keys::load_secret(&app.config.keys_dir()).map_err(|e| format!("the hub key is unavailable: {e}"))?;

    let identity = app.hub_key.identity.clone();

    Ok(Signer { author: identity.clone(), hub_key, hub_secret, hub_identity: identity })

}

    match land_as(&app, &repo, &row, &me.account, number, "web", false).await {

/// (`via`: `web`, or `api (token NAME)`). `as_hub` signs with the hub's own

/// key rather than `me`'s delegation (Diffusion's auto-land). Returns the

/// new state.

    as_hub: bool,

    let signer = if as_hub { super::edit::hub_signer(app) } else { super::edit::signer_for(app, me.id).await };

    let result = match signer {

    /// `auto` or `propose` (absent keeps it as it is).

    #[serde(default)]

    land: String,

    };

    let land = match f.land.as_str() {

        "auto" | "propose" => Some(f.land.as_str()),

        "" => None,

        _ => return settings_page(&app, shell, row, role, None, Some("Pick propose or auto for landing.".into())).await,

    if let Some(l) = land {

        db::repos::set_diffusion_land(&app.db, row.id, l).await.map_err(|e| Error::from_db(shell.clone(), e))?;

    }

    let what =

        format!("{}{}", if setting.is_empty() { "default" } else { setting }, land.map(|l| format!(", land {l}")).unwrap_or_default());

    accounts::audit(&app.db, viewer.account(), "repo.diffusion", &format!("{owner}/{name}"), &what).await.ok();

    // Turned to land by itself: any bump already green lands now.

    if land == Some("auto") {

        let (app, row) = (app.clone(), row.clone());

        tokio::spawn(async move { crate::diffusion::land_ready(&app, &row).await });

    }

/// Diffusion auto-land (docs/diffusion.md §4.2; Andy chose "opt-in, per

/// repository", 2026-10-13): a consumer that chose `land = auto` has a bump

/// landed by itself, as the diffusion account, once both halves are green;

/// a bump from an upstream with no checks (amber) always waits.

#[tokio::test(flavor = "multi_thread")]

async fn a_consumer_that_chose_auto_lands_green_bumps_itself() {

    let h = hub().await;

    db::accounts::create_account(&h.app.db, "andy", "[email protected]", "x", "salt", true).await.unwrap();

    create(&h.app, "andy", "api").await;

    create(&h.app, "andy", "game").await;

    let hub_app = &h.app;

    // Run every queued job to a pass.

    let pass_all = move || async move {

        for _ in 0..20 {

            let Some(a) = claim(hub_app).await else {

                tokio::time::sleep(std::time::Duration::from_millis(30)).await;

                if !jobs_left(hub_app).await {

                    break;

                }

                continue;

            };

            let id = a["job_id"].as_i64().unwrap();

            let (name, ph) = (a["job"]["name"].as_str().unwrap().to_string(), a["pipeline_hash"].as_str().unwrap().to_string());

            assert_eq!(

                finish(hub_app, id, serde_json::json!({ "exit_code": 0, "duration_ms": 10, "receipt": receipt(&name, &ph, 0) })).await,

                StatusCode::NO_CONTENT

            );

        }

    };

    let api_work = tempfile::tempdir().unwrap();

    let api = client(&format!("{}/andy/api", h.base), api_work.path());

    write(api_work.path(), ".flow/pipeline.kdl", &pipeline(""));

    write(api_work.path(), "test.sh", "echo ok\n");

    api.snapshot("t").unwrap();

    api.commit("api v1", &[]).unwrap();

    assert!(api.push("origin", false).unwrap().iter().all(|r| r.ok));

    pass_all().await;

    let game_work = tempfile::tempdir().unwrap();

    let game = client(&format!("{}/andy/game", h.base), game_work.path());

    game.submodule_add(&format!("{}/andy/api", h.base), "deps/api", Some("main")).unwrap();

    write(game_work.path(), ".flow/pipeline.kdl", &pipeline(""));

    write(game_work.path(), "test.sh", "echo ok\n");

    game.snapshot("t").unwrap();

    game.commit("game on api v1", &[]).unwrap();

    assert!(game.push("origin", false).unwrap().iter().all(|r| r.ok));

    pass_all().await;

    let game_row = db::repos::get(&h.app.db, "andy", "game").await.unwrap().unwrap();

    for _ in 0..100 {

        let n: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM diffusion_pins WHERE consumer_id = ?")

            .bind(game_row.id)

            .fetch_one(&h.app.db)

            .await

            .unwrap();

        if n > 0 {

            break;

        }

        tokio::time::sleep(std::time::Duration::from_millis(30)).await;

    }

    let (st, body) =

        call(&h.app, "PUT", "/api/v1/repos/andy/game/diffusion", Some("site"), Some(r#"{"follow":"green","land":"auto"}"#.into())).await;

    assert_eq!(st, StatusCode::OK, "{body}");

    assert!(body.contains(r#""land":"auto""#), "{body}");

    let (st, _) =

        call(&h.app, "PUT", "/api/v1/repos/andy/game/diffusion", Some("site"), Some(r#"{"follow":"green","land":"soon"}"#.into())).await;

    assert_eq!(st, StatusCode::BAD_REQUEST);

    // The upstream moves and passes: the bump is proposed, its run passes,

    // and it lands by itself.

    write(api_work.path(), "a2.c", "v2\n");

    api.snapshot("t").unwrap();

    api.commit("api v2: faster sprites", &[]).unwrap();

    assert!(api.push("origin", false).unwrap().iter().all(|r| r.ok));

    let mut landed = None;

    for _ in 0..100 {

        pass_all().await;

        let all = db::proposals::list(&h.app.db, game_row.id, &[]).await.unwrap();

        if let Some(p) = all.into_iter().find(|p| p.source_bookmark == "diffusion/deps/api" && p.state == "landed") {

            landed = Some(p);

            break;

        }

        tokio::time::sleep(std::time::Duration::from_millis(50)).await;

    }

    let p = landed.expect("landed by itself once both halves were green");

    assert!(p.body.contains("lands its bumps itself"), "{}", p.body);

    let events = db::proposals::events(&h.app.db, p.id).await.unwrap();

    let landing = events.iter().find(|e| e.event == "landed").expect("a landing on the timeline");

    assert_eq!(landing.actor, "diffusion");

    assert!(landing.detail.contains("Diffusion, both halves green"), "{}", landing.detail);

    // The game's main now pins api v2.

    let mut behind = serde_json::Value::Null;

    for _ in 0..100 {

        let (_, list) = call(&h.app, "GET", "/api/v1/repos/andy/api/consumers", Some("site"), None).await;

        let list: Vec<serde_json::Value> = serde_json::from_str(&list).unwrap();

        behind = list.iter().find(|c| c["name"] == "game").map(|c| c["behind"].clone()).unwrap_or_default();

        if behind == 0 {

            break;

        }

        tokio::time::sleep(std::time::Duration::from_millis(50)).await;

    }

    assert_eq!(behind, 0, "main moved to the bump");

    // An upstream with no checks: its bump passes in the consumer, but

    // amber never lands by itself, whatever the setting.

    create(&h.app, "andy", "lib").await;

    create(&h.app, "andy", "app").await;

    let lib_work = tempfile::tempdir().unwrap();

    let lib = client(&format!("{}/andy/lib", h.base), lib_work.path());

    write(lib_work.path(), "lib.h", "v1\n");

    lib.snapshot("t").unwrap();

    lib.commit("lib v1", &[]).unwrap();

    assert!(lib.push("origin", false).unwrap().iter().all(|r| r.ok));

    let app_work = tempfile::tempdir().unwrap();

    let app = client(&format!("{}/andy/app", h.base), app_work.path());

    app.submodule_add(&format!("{}/andy/lib", h.base), "deps/lib", Some("main")).unwrap();

    let modules = std::fs::read_to_string(app_work.path().join(".oxymodules")).unwrap();

    write(app_work.path(), ".oxymodules", &format!("{modules}follow = green\nland = auto\n"));

    write(app_work.path(), ".flow/pipeline.kdl", &pipeline(""));

    write(app_work.path(), "test.sh", "echo ok\n");

    app.snapshot("t").unwrap();

    app.commit("app on lib", &[]).unwrap();

    assert!(app.push("origin", false).unwrap().iter().all(|r| r.ok));

    pass_all().await;

    let app_row = db::repos::get(&h.app.db, "andy", "app").await.unwrap().unwrap();

    for _ in 0..100 {

        let n: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM diffusion_pins WHERE consumer_id = ?")

            .bind(app_row.id)

            .fetch_one(&h.app.db)

            .await

            .unwrap();

        if n > 0 {

            break;

        }

        tokio::time::sleep(std::time::Duration::from_millis(30)).await;

    }

    write(lib_work.path(), "lib.c", "v2\n");

    lib.snapshot("t").unwrap();

    lib.commit("lib v2", &[]).unwrap();

    assert!(lib.push("origin", false).unwrap().iter().all(|r| r.ok));

    let mut passed = false;

    for _ in 0..100 {

        pass_all().await;

        let s: Option<String> = sqlx::query_scalar(

            "SELECT status FROM flow_runs WHERE repo_id = ? AND bookmark = 'diffusion/deps/lib' ORDER BY id DESC LIMIT 1",

        )

        .bind(app_row.id)

        .fetch_optional(&h.app.db)

        .await

        .unwrap();

        if s.as_deref() == Some("passed") {

            passed = true;

            break;

        }

        tokio::time::sleep(std::time::Duration::from_millis(50)).await;

    }

    assert!(passed, "the app's run on the bump passed");

    assert_eq!(oxygenhub::diffusion::auto_land(&h.app, &app_row, "deps/lib").await, Err(oxygenhub::diffusion::Held::Unverified));

    let open = db::proposals::list(&h.app.db, app_row.id, &["open"]).await.unwrap();

    assert!(open.iter().any(|p| p.source_bookmark == "diffusion/deps/lib"), "amber waits for a person");

}

of the upstream later clears it.

**Landing by itself** (built 2026-10-14, oxygenhub#174; Andy chose

"opt-in, per repository" after rstar-api's first green/green): `land =

auto` in the entry, else the repository's Settings › Diffusion › Landing

(`PUT …/diffusion {"land": "auto"}`), off by default. The hub lands a bump

itself, as the `diffusion` account, when both halves are green: the exact

upstream state the bump pins passed its own run, and the consumer's

newest run on the bump bookmark passed on the bump as it is now. Never

for amber: an upstream with no checks always waits for a person. It lands

through the web's own path (`land_as`), signed by the hub's own key, so

the consumer's required checks, approvals and trust policy decide as for

anyone; a policy that does not let the hub's key move the bookmark keeps

the bump waiting, and the proposal's timeline says why, once. It is tried

when the bump's run passes, when the upstream's run passes under a bump

already made, and when the setting is turned to `auto`. The timeline

records "landed (Diffusion, both halves green)".

- **Architecture** (OxygenFlow spec §11.2–§11.3, oxygenflow#36): a runner reports each image's architecture on its claims (`image_archs`), kept in `flow_images`; a job is offered only to a runner whose architecture matches its sandbox's `arch`, else its image's as known. The hub knows an image's architecture from its own files, read through its ext4 to its shell's ELF header (`jet::rootfs`) out of the kept chunks, when it is sent (the manifest's word is taken only when the image cannot be read) and, once at start, for every kept image that had none; an image nobody can read takes the architecture of the runner its first job passed on, and a runner's own report, read from the image it holds, wins over that (oxygenhub#173, Andy's "detect and learn"). Only an image nobody has read or run matches any runner. The queue says which architecture a waiting job asks for. **Images by hash** (oxygenflow#39, Jetstream): `flow rootfs push HASH` sends a rootfs image as the FastCDC chunks the hub lacks (`POST /flow/images/missing`, `PUT /flow/images/chunks/{hash}`, by a token that may write repositories) and then its manifest (`PUT /flow/images/{hash}`), which the hub accepts only when every chunk is held and they make an image with that hash; chunks are kept zstd-compressed under `<data>/images`, shared by every image, and `jet_images` lists what is held. Runners and accounts fetch with `GET /flow/images/{hash}` and `GET /flow/images/chunks/{hash}`. A runner whose claims say `fetches_images` is offered jobs whose image only the hub holds, and fetches it before its preflight. Each claim also carries the runner's `facts` (OxygenFlow spec §11.1, oxygenflow#40): free disk, load, speed score and class, kernel; the hub keeps the latest on the runner, shows them on Admin › Runners and in `GET /runners`. A job's finish carries the most disk and memory it took (`peak_disk_mib`, `peak_memory_mib`, oxygenflow#41); a new job's `need_disk_mib` is the most its last five runs of the same repository and name took, plus a quarter and 64 MiB, and it is offered only to a runner whose claim reports at least that much free disk; the waiting reason says so. **Ranking** (oxygenflow#42): a job that another free runner which polled in the last 10 s would do better (it holds the job's build cache, which counts most: claims list the caches a runner holds, `caches`, each `flow_core::api::cache_slot(repo, job)`, oxygenflow#51; or it holds the job's image while the claimant would fetch it; or it has a higher speed class) is held from the claimant for up to 15 s, then any runner that fits takes it; each job records why it ran where it did (`placed`: "holds its build cache, holds the image, idle, speed 100 (class 3)", with "after N s held for a better runner" when it was), shown on the run page, in the API and by `oh run view`. A run whose jobs pin an image held by neither the hub nor a runner sets a failing `pipeline/images` check on its state (#137), naming the images and how to send them (`flow rootfs push`), so a proposal pinning a new image shows it before it lands; a later run of the state turns it to passed once every image is held. A placement pass every 15 seconds works out why each ready queued job no runner can take waits, from what each online runner offered at its last claim (scope, tier, architecture, image held, labels, memory and CPUs, a recent decline), and shows it on the job (API `waiting`, `oh run view` and `oh run watch`, its panel open on the run page) and in its check's summary, so a proposal says why its check is stuck (#28). **Diffusion** (#148, `docs/diffusion.md`): a push that moves a repository's default bookmark, or the bookmark its work lands on (the most common target of its proposals landed in the last 90 days), records each Oxygen subrepo pin in the new state (`diffusion_pins`: consumer, bookmark, path, the upstream's Oxygen repository id, the pinned heads); a hub that had no index fills it at start. `GET /repos/{owner}/{name}/consumers` lists the consumers the caller may read, each with its pin and how many changes of this repository's default bookmark it lacks (`behind`, null when the pin names changes this repository does not hold), and the overview shows them under Diffuses to. `GET /repos/{owner}/{name}/diffusion` (#153) gives both directions, `takes_from` (each upstream the repository pins) and `diffuses_to` (each consumer the caller may read), every entry naming its `upstream` and `consumer`, its `path`, `bookmark`, `behind`, `follow`, open `bump`, the bump's newest `run` and `run_status`, and the pill's halves (`upstream_state`, `consumer_state`: `tone` green, amber, red, grey or off, `word`, `title`); hub-api's `Diffusion`. A repository that pins, or is pinned by, another on the hub has a **Diffusion tab** (#150): Diffuses to (each consumer's pin bookmark, how far behind, its status, its open bump and that bump's newest run, its last landed bump, how it follows) and Takes from (each upstream it pins, with the same); its overview shows both in brief, and Admin › Diffusion lists every upstream with its consumers. Each consumer's status is a two-half pill: the upstream on the left (checked when its newest default-bookmark run passed, untested when it has no checks, failing, or testing) and the consumer on the right (passes or fails for its run on the bump, testing, waiting, or up to date), each half coloured green, amber, red or grey; the API keeps one overall `colour` as well. Landing a proposal on the hub refreshes the pin index and propagates as a push does. A bump's run, started by the `diffusion` account, is given the upstream it bumps as a subrepo whatever that account may read (the consumer's own pin of it was committed by someone who may write the consumer); its other subrepos need read access as usual. A consumer follows a subrepo's upstream as its `.oxymodules` entry says (`follow = off | green | any`, `land = propose | auto`, `target` naming the bookmark to bump, `watch` listing paths whose upstream changes are flagged), else as its repository setting says (Settings › Diffusion, or `PUT /repos/{owner}/{name}/diffusion {"follow": ...}` by its owners and admins; migration 0058), else as `[diffusion] follow` in hub.toml says (default `off`). A **bump** moves a consumer's pin at a path to a newer upstream state: one change on the target bookmark's heads that replaces only the pin (oxy-core `build_pin_change`), signed with the hub's key, on the bookmark `diffusion/<path>`, which the hub owns and rebuilds on the target each time (a forced update). When the pin has changes the upstream's state lacks (say, from an upstream proposal not landed yet), the bump moves to both, so a consumer never loses changes it relies on; it is skipped when that combination would conflict, when the pin names changes the upstream does not hold, when the pin already holds the state, or when the bump bookmark already moves it there, and the hub logs why. A bump is **proposed** once per bump bookmark, by the hub's `diffusion` account (made on first use, never able to sign in), into the target, labelled `dependencies`, its body the upstream changes the pin lacks (newest first, linking to the upstream's change pages); a later bump edits the same open proposal. It is triggered when a push moves the upstream's default bookmark (for consumers following `any`) or when a run of that bookmark passes (for `green`). Diffusion lands a bump only where the consumer chose it (`land = auto` in the entry, else Settings › Diffusion › Landing or `PUT /repos/{owner}/{name}/diffusion {"land": "auto"}`, migration 0061; off by default, #174): once both halves are green (the upstream state it pins passed its own run, and the consumer's run on the bump as it is now passed), as the `diffusion` account through `land_as`, signed by the hub's key, so required checks, approvals and the trust policy decide; never for an unverified upstream; a refusal is noted once on the proposal's timeline. An upstream with no checks of its own (Flow off, or no run ever of its default bookmark) is **unverified**: it never turns green, so its moves also bump consumers following `green`, and those proposals are marked amber with the `upstream unverified` label and a note in the body; a later bump from a passing run removes the label. A bump already in place refreshes its proposal's text and labels. A consumer's `watch` patterns (`*` within a path segment, `**` across them, `?` one character; a plain path covers everything below it) flag the upstream changes touching a matching file: they are listed first under "Touches what you watch", with the files, and marked ⚑ in the changelog. Turning Diffusion on for a consumer (the setting or the API) catches it up at once: it is bumped to each upstream's newest state whose default-bookmark run passed, or to its newest state when it follows every move. **Images page** (#146): Admin › Runners › Images lists every rootfs image a runner holds, the hub keeps, or a job ran on in the last 90 days (from each job's sandbox), newest use first: its size and architecture, where it is (the hub, each runner holding it, each runner fetching it from the swarm now), the repositories whose jobs used it, and who sent it; an image held nowhere is marked. **The swarm** (#144, oxygenflow docs/jetstream.md §8.1): a runner in an image swarm reports its peer address, its site and the BLAKE3 of its TLS certificate with each claim (`swarm`; without a certificate it is not in the swarm), kept in memory and shown on Admin › Runners. `POST /flow/swarm/announce {image, state}` (by a runner; `fetching`, `done` or `stopped`) returns the online runners in its site that hold the image or announced fetching it in the last 45 seconds, each with its certificate's fingerprint, which the fetcher pins its TLS connection to, and a ticket signed with the hub key (JSON naming the runner, its site and an expiry 15 minutes on, hex, then the signature) that peers check against `/.well-known/oxyhub-key` before serving chunks; a runner that has not reported an address is told to add `[runner.swarm]` (409).

  <p>When a repository this one pins as a subrepo moves on, Diffusion opens a proposal here that moves the pin, tested by this repository's own pipeline, with the upstream's changes listed. By default it never lands anything by itself.</p>

  <h3>Landing</h3>

  <div class="choice">

    <label><input type="radio" name="land" value="propose"{% if row.diffusion_land != "auto" %} checked{% endif %}> propose only: a person lands each bump</label>

    <label><input type="radio" name="land" value="auto"{% if row.diffusion_land == "auto" %} checked{% endif %}> land by itself when both halves are green: the upstream state it pins passed its own checks and this repository's run on the bump passed</label>

  </div>

  <p class="small mute">An untested (amber) upstream always waits for a person. A landing by Diffusion still needs this repository's required checks and approvals, and a trust policy that lets the hub's key move the bookmark; otherwise the bump waits, and its timeline says why.</p>

  <p class="small mute">A subrepo's <code>.oxymodules</code> entry overrides this with <code>follow = green</code>, <code>any</code> or <code>off</code>; <code>land = auto</code> or <code>propose</code> overrides the landing, <code>target</code> names the bookmark to move (else the one this repository's proposals land on) and <code>watch</code> lists paths whose upstream changes are flagged.</p>