gunnar_wire/

caps.rs

//! Capabilities, and the table that keeps the advertisement honest.
//!
//! # The bug this module exists to make impossible
//!
//! A protocol-v2 client will not send an argument unless the corresponding
//! **feature** appears in the value of the capability it belongs to. A server
//! that parses `filter <spec>` but advertises `fetch=shallow wait-for-done` has
//! partial-clone support that can never activate. Worse, it looks *exactly*
//! like working code: no error is raised, no test fails, the client simply
//! never exercises the path. Stock `git` 2.53 does this deliberately
//! (`uploadpack.allowFilter` defaults off), which is why the shape is easy to
//! copy by accident.
//!
//! So the advertisement is not written down anywhere. There is one table
//! ([`FETCH_ARGUMENTS`], [`LS_REFS_ARGUMENTS`]) that says, per argument, which
//! feature gates it, and both the **parser** and the **advertisement** are
//! derived from it. Adding an argument to the parser without advertising its
//! feature is not something you can forget to do; it is something you cannot
//! express. That is a fix by construction rather than a guard watching two
//! copies agree (one implementation), and `tests/advertisement.rs` still asserts the
//! resulting invariant from the outside, red-first.
//!
//! # The other bug, which the paragraph above did NOT prevent
//!
//! That paragraph was true of the **v2 arguments** and of nothing else, and it
//! was read as covering everything — an early audit
//! said outright that *"advertised but not honoured is not something this
//! codebase can express"*. It was expressible in three other places, and it was
//! expressed:
//!
//! * `upload_pack_v0_capabilities` was a hand-written `vec![]`,
//! * `receive_pack_capabilities` was a second one, and
//! * the **v2 capability names** were a third, in `upload_pack.rs`.
//!
//! `"push-options".to_owned()` sat in the second of those. It was advertised,
//! `receive_pack::ReceivePack::serve` parsed the section, and the only consumer
//! anywhere in the tree was `.len()` in a log field. A client that ran
//! `git push -o ci.skip` was told on the wire that the server speaks push
//! options and the option went nowhere — a wrong answer on the wire, not a
//! missing feature.
//!
//! [`ADVERTISED`] closes it the same way: **one place decides what is
//! advertised, for all three surfaces**, every row carries a [`Honoured`]
//! saying where it is honoured, and `tests/advertisement.rs` checks each claim
//! against the source with comments stripped — because
//! `contains("push-options")` is satisfied by the paragraph explaining
//! push-options two lines above the call site.

use gix_hash::Kind;

/// The product half of the `agent=` capability.
pub const PRODUCT: &str = "gunnar";

/// The `agent=` value gunnar advertises: `gunnar/<crate version>`.
pub fn default_agent() -> String {
    format!("{PRODUCT}/{}", env!("CARGO_PKG_VERSION"))
}

/// git's name for a hash algorithm, as it appears in `object-format=`.
pub fn object_format_name(kind: Kind) -> &'static str {
    match kind {
        Kind::Sha1 => "sha1",
        Kind::Sha256 => "sha256",
        // `gix_hash::Kind` is `#[non_exhaustive]`. A hash gunnar has never
        // heard of cannot be advertised as one it has, so it gets a name no
        // client will match and `check_object_format` rejects every request
        // against it. Loudly wrong beats quietly wrong.
        _ => "unsupported",
    }
}

/// The inverse of [`object_format_name`].
pub fn object_format_from_name(name: &str) -> Option<Kind> {
    match name {
        "sha1" => Some(Kind::Sha1),
        "sha256" => Some(Kind::Sha256),
        _ => None,
    }
}

/// Whether an argument carries a value after its name.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Value {
    /// The whole line is the argument name: `done`, `thin-pack`.
    None,
    /// A single space, then the value: `want <oid>`, `ref-prefix <p>`.
    Required,
}

/// One argument a protocol-v2 command accepts.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Argument {
    /// The name as it appears on the wire.
    pub name: &'static str,
    /// Whether a value follows.
    pub value: Value,
    /// The feature that must appear in the capability's advertised value
    /// before a client is allowed to send this argument, or `None` for the
    /// arguments every v2 client may always send.
    pub feature: Option<&'static str>,
}

const fn plain(name: &'static str, value: Value) -> Argument {
    Argument {
        name,
        value,
        feature: None,
    }
}

const fn gated(name: &'static str, value: Value, feature: &'static str) -> Argument {
    Argument {
        name,
        value,
        feature: Some(feature),
    }
}

/// Every argument `command=ls-refs` accepts.
pub const LS_REFS_ARGUMENTS: &[Argument] = &[
    plain("symrefs", Value::None),
    plain("peel", Value::None),
    plain("ref-prefix", Value::Required),
    gated("unborn", Value::None, "unborn"),
];

/// Every argument `command=fetch` accepts.
///
/// The four `deepen*` forms and `shallow` are all gated on the single
/// `shallow` feature, exactly as git defines it: advertising `shallow` is a
/// promise to accept all five, which is why they are implemented rather than
/// rejected.
pub const FETCH_ARGUMENTS: &[Argument] = &[
    plain("want", Value::Required),
    plain("have", Value::Required),
    plain("done", Value::None),
    plain("thin-pack", Value::None),
    plain("no-progress", Value::None),
    plain("include-tag", Value::None),
    plain("ofs-delta", Value::None),
    gated("shallow", Value::Required, "shallow"),
    gated("deepen", Value::Required, "shallow"),
    gated("deepen-relative", Value::None, "shallow"),
    gated("deepen-since", Value::Required, "shallow"),
    gated("deepen-not", Value::Required, "shallow"),
    gated("filter", Value::Required, "filter"),
    gated("want-ref", Value::Required, "ref-in-want"),
    gated("wait-for-done", Value::None, "wait-for-done"),
];

/// Look an argument up by name.
pub fn argument(table: &'static [Argument], name: &str) -> Option<&'static Argument> {
    table.iter().find(|a| a.name == name)
}

/// The features of `table`, in first-seen order and without duplicates.
///
/// This is the only place an advertised feature list comes from.
pub fn features(table: &'static [Argument]) -> Vec<&'static str> {
    let mut out: Vec<&'static str> = Vec::new();
    for arg in table {
        if let Some(feature) = arg.feature {
            if !out.contains(&feature) {
                out.push(feature);
            }
        }
    }
    out
}

/// Render `name=<features>` for a v2 capability, or bare `name` when the
/// command has no gated arguments at all.
pub fn capability(name: &str, table: &'static [Argument]) -> String {
    let features = features(table);
    if features.is_empty() {
        name.to_owned()
    } else {
        format!("{name}={}", features.join(" "))
    }
}

/// What a client may turn off in the fetch capability.
///
/// `filter` is the one capability an operator plausibly wants to decline
/// (serving a partial clone means serving arbitrary blob subsets), so it is a
/// knob rather than a constant. Declining it removes the feature from the
/// advertisement **and** makes the parser reject the argument, together, in
/// [`fetch_capability`] and [`crate::upload_pack::FetchRequest::parse`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Offered {
    /// Whether `filter` is advertised and accepted.
    pub filter: bool,
}

impl Default for Offered {
    fn default() -> Self {
        Offered { filter: true }
    }
}

impl Offered {
    /// Is `feature` on offer?
    pub fn has(&self, feature: &str) -> bool {
        match feature {
            "filter" => self.filter,
            _ => true,
        }
    }

    /// May `argument` be sent by a client, given what is on offer?
    pub fn accepts(&self, argument: &Argument) -> bool {
        argument.feature.is_none_or(|f| self.has(f))
    }
}

// ════════════════════════════════════════════════════════════════════════════
// The advertisement — ONE table, all three surfaces
// ════════════════════════════════════════════════════════════════════════════

/// Where the code that honours a capability lives.
///
/// Every entry in every advertisement table carries one of these, and
/// `tests/advertisement.rs` reads them: the named file, **with its comments
/// stripped**, must contain the named code. Comments are stripped because
/// `contains("push-options")` is satisfied by the paragraph explaining
/// push-options two lines above the call — a guard that a doc comment can
/// satisfy is a guard that survives the deletion of the thing it guards.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Honoured {
    /// Read by code in `file` containing the substring `code`.
    ///
    /// `file` is relative to the workspace root.
    By {
        /// Workspace-relative path.
        file: &'static str,
        /// A substring of the line that reads it, e.g. `peer.has("atomic")`.
        code: &'static str,
    },
    /// Read by a public item of a crate gunnar **depends on**, not by a file in
    /// this tree.
    ///
    /// This variant exists because the other one could not tell the truth here.
    /// `ofs-delta`'s obligation is discharged by `gunnar-pack`, which lived at
    /// `../edda/crates/gunnar-pack` and was cited as a workspace-relative PATH —
    /// a path that only resolves on a machine with an edda checkout beside
    /// gunnar. From a fresh clone (and, since 2026-09-09, from every clone, since
    /// the crate is a crates.io dependency) the citation named a file that is not
    /// there, and the guard failed for the absence of a sibling rather than for
    /// anything about gunnar.
    ///
    /// A path was the wrong shape for the claim anyway. What is being asserted is
    /// that a named ITEM exists in a named CRATE, and the compiler can assert
    /// that exactly — `advertisement.rs` carries a `use` of every item cited this
    /// way, so the guard is a build error rather than a substring search, and it
    /// holds whether the crate resolves from the registry or from a patched
    /// sibling checkout.
    ByDependency {
        /// The crate as cargo names it, e.g. `gunnar-pack`.
        krate: &'static str,
        /// The public item that does the work, e.g. `index_thin_pack`.
        item: &'static str,
    },
    /// There is nothing to do, and here is the argument for why.
    ///
    /// The reason is a sentence, not a marker: this variant is the escape hatch
    /// and it has to cost something to use. Today exactly three capabilities
    /// use it, and each says what makes it vacuous rather than unimplemented.
    Vacuously(&'static str),
}

/// What follows a capability's name on the wire.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CapValue {
    /// Nothing: the name alone, `atomic`.
    Bare,
    /// `=sha1` / `=sha256`, from the repository's hash.
    ObjectFormat,
    /// `=gunnar/1.1.0`, from the caller's agent string.
    Agent,
    /// `=<features>`, generated from a v2 argument table by [`features`].
    ///
    /// A bare name when the table gates nothing, which is what
    /// [`capability`] already does.
    Features(&'static [Argument]),
}

/// One capability gunnar advertises, and the thing that honours it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Capability {
    /// The name as it appears on the wire, without any `=value`.
    pub name: &'static str,
    /// What follows the name.
    pub value: CapValue,
    /// The [`Offered`] knob that can withdraw this capability, if any.
    ///
    /// `None` means it is always advertised. `Some(feature)` means it appears
    /// only when [`Offered::has`] says so — and the parser must refuse the
    /// argument in the same breath, which is what `Offered` exists to make
    /// impossible to get wrong.
    pub offered: Option<&'static str>,
    /// Where it is honoured.
    pub honoured: Honoured,
    /// The [`WantPolicy`] this row is a promise about, if any.
    ///
    /// `None` for every capability whose truth does not depend on what a
    /// client is allowed to `want` — which is all of them but the two
    /// `allow-*-sha1-in-want` rows.
    ///
    /// This exists because the drift `Honoured` catches runs one way only. A
    /// row honoured by nothing is caught by the guard; a **policy honoured by
    /// no row** is not, because there is no row to look at. `WantPolicy` was
    /// exactly that: enforced by `check_wants` on every request and named in no
    /// advertisement, so a stock client refused the request on its own side and
    /// the server never heard it. See [`WantPolicy::advertises`].
    pub requires: Option<crate::upload_pack::WantPolicy>,
}

const fn cap(name: &'static str, code: &'static str, file: &'static str) -> Capability {
    Capability {
        name,
        value: CapValue::Bare,
        offered: None,
        honoured: Honoured::By { file, code },
        requires: None,
    }
}

/// The file both push-side capability readers live in.
const RECEIVE: &str = "crates/gunnar-wire/src/receive_pack.rs";
/// The file the fetch-side capability readers live in.
const UPLOAD: &str = "crates/gunnar-wire/src/upload_pack.rs";

/// `agent=`, which is the same row on all three surfaces.
const AGENT: Capability = Capability {
    name: "agent",
    value: CapValue::Agent,
    offered: None,
    honoured: Honoured::Vacuously(
        "an identifier for the peer's logs. There is no behaviour attached to \
         it at either end; git itself only records it.",
    ),
    requires: None,
};

/// `object-format=`, which is the same row on all three surfaces.
const OBJECT_FORMAT: Capability = Capability {
    name: "object-format",
    value: CapValue::ObjectFormat,
    offered: None,
    honoured: Honoured::By {
        file: "crates/gunnar-wire/src/caps.rs",
        code: "pub fn check_object_format",
    },
    requires: None,
};

/// Every capability `git-upload-pack` advertises in **protocol v0**.
///
/// Plain `multi_ack` is deliberately absent: it is an ACK mode with its own
/// semantics that nothing here implements, and advertising a negotiation richer
/// than the one implemented is the same class of bug this module exists to
/// prevent. It is absent by *not being in this table*, which is now the only
/// way to be absent.
///
/// `multi_ack_detailed` and `no-done` **are** here, and the comment on the first
/// row says why: without them stock git negotiates in single-ACK, which has no
/// correct answer over stateless-rpc and cannot finish a fetch over smart HTTP.
pub const UPLOAD_PACK_V0: &[Capability] = &[
    // ── the ACK mode, and why these two are not optional ────────────────────
    //
    // This table used to carry neither, on the reasoning that gunnar negotiated
    // in single-ACK mode and that advertising a richer ACK protocol than the
    // one implemented is the bug this module exists to prevent. The reasoning
    // was sound and the conclusion was wrong, and stock git rather than an
    // argument is what decided it.
    //
    // A v0 client picks its ACK mode from what the server offers. Offered
    // neither, git 2.53.0 falls back to single-ACK, in which a bare
    // `ACK <oid>` is TERMINAL: it means "negotiation is over, a packfile
    // follows". Over a CONNECTED session that can be served correctly, and
    // `b9fee55` did exactly that — git's rule is on `have_obj.nr`, so nothing
    // more goes out once the ACK has, and the surplus `NAK` that used to sit in
    // the pipe is gone. That fix is real and the `else` arm in
    // `serve_v0_session` still carries it.
    //
    // Over **stateless-rpc there is no correct answer at all**, which is the
    // part a connected fix cannot reach. The round ends with the HTTP response,
    // so the client takes the terminal `ACK`, opens a FRESH `POST` carrying
    // `want` and `done` and no `have`s, and reads that response as a raw
    // sideband packfile — while the server, seeing a request with no commons,
    // correctly opens it with `NAK`. There is nothing else it could send: the
    // request genuinely has no common `have` in it. git demuxes the `N` as a
    // band number and dies with `fetch-pack: protocol error: bad band #78`.
    //
    // MEASURED 2026-08-05, git 2.53.0, a corpus of 12 pushes cut back a
    // third: `git fetch http://…` exited **128 against `b9fee55` itself**, on
    // both sha1 and sha256, and 0 against `git http-backend` on the identical
    // repository. The advertisements differed in these two names and in nothing
    // else that changes the client's behaviour. That is why the mode is now
    // implemented rather than declined — not because the earlier fix was wrong.
    //
    // `no-done` is what stateless-rpc is really after: it lets the server send
    // `ACK <oid> ready`, the terminal `ACK` and the packfile in ONE response
    // rather than making the client spend a second HTTP request to say `done`.
    //
    // Plain `multi_ack` is still absent, and deliberately: it is a third ACK
    // mode with its own semantics that nothing here implements, so it is not
    // advertised. A client too old to know `multi_ack_detailed` gets
    // single-ACK, which is correct on the connected sessions it can reach.
    cap(
        "multi_ack_detailed",
        r#"peer.has("multi_ack_detailed")"#,
        UPLOAD,
    ),
    cap("no-done", r#"peer.has("no-done")"#, UPLOAD),
    cap("side-band-64k", r#"peer.has("side-band-64k")"#, UPLOAD),
    // The **v0** reader, not the v2 argument arm. This row cited
    // `"thin-pack" => out.thin_pack = true`, which is the v2 parser, while v0
    // read the capability nowhere at all — so every v0 fetch was served as a
    // whole pack against an advertisement promising otherwise (found and fixed
    // in `222f7b2`: 1.343x the bytes on a real incremental). A v0 row must cite
    // a v0 consumer, or the guard is satisfied by the other protocol's code.
    cap("thin-pack", r#"peer.has("thin-pack")"#, UPLOAD),
    cap("ofs-delta", r#"peer.has("ofs-delta")"#, UPLOAD),
    cap("no-progress", r#"peer.has("no-progress")"#, UPLOAD),
    cap("include-tag", r#"peer.has("include-tag")"#, UPLOAD),
    // Again the **v0** arms (`parse_v0_shallow_line`), not the v2 ones. Both
    // exist and both are real, but a v0 row citing the v2 parser would stay
    // green if the v0 half were deleted — which is exactly what happened to
    // `thin-pack` above.
    cap("shallow", r#""shallow" => request"#, UPLOAD),
    cap("deepen-since", "request.shallow.since =", UPLOAD),
    cap("deepen-not", r#""deepen-not" => request"#, UPLOAD),
    // The capability, not the line arm (GHUNT-1): a row citing the line parser stayed green
    // while no v0 client could reach it.
    cap("deepen-relative", r#"peer.has("deepen-relative")"#, UPLOAD),
    Capability {
        name: "filter",
        value: CapValue::Bare,
        // The one capability an operator plausibly declines. Withdrawing it
        // removes it from HERE and makes the parser refuse the argument, in
        // one place, which is what `Offered` is for.
        offered: Some("filter"),
        honoured: Honoured::By {
            file: UPLOAD,
            code: r#""filter" => out.filter"#,
        },
        requires: None,
    },
    // ── the two rows that were missing, and the failure they hid ────────────
    //
    // `check_wants` has always enforced a `WantPolicy`, and the v0
    // advertisement said nothing about it. `fetch-pack.c` will not send a
    // `want` for an unadvertised object unless one of these two names was in
    // the advertisement, so the request was refused **client-side** — no
    // server error, no log line, nothing to notice. That is the inverted form
    // of the drift the rest of this table catches: not a promise nothing keeps,
    // but something kept that was never promised.
    //
    // MEASURED 2026-08-05, stock git 2.53.0 over `ext::`, one commit two
    // steps behind `main`'s tip:
    //
    // | request | v0 | v2 |
    // |---|---|---|
    // | `fetch <oid>` of a reachable non-tip commit | `Server does not allow request for unadvertised object` | 6 objects, OK |
    // | `clone --filter=blob:none`, then check out | **4 refusals, checkout failed** | OK |
    //
    // The second row is the one that matters: a partial clone fetches its blobs
    // back by bare oid. v2 has no such capability at all (`upload_pack_v2` sets
    // `ALLOW_ANY_SHA1` unconditionally), which is why every v2 arm was green
    // while every v0 arm was broken.
    //
    // Both are honoured by `check_wants`, and deliberately by the *same* line:
    // there is one policy decision, not two, and a row citing a second site
    // would go green on code that agreed with it by accident.
    Capability {
        name: "allow-reachable-sha1-in-want",
        value: CapValue::Bare,
        offered: None,
        honoured: Honoured::By {
            file: UPLOAD,
            code: "fn check_wants",
        },
        requires: Some(crate::upload_pack::WantPolicy::ReachableFromRefs),
    },
    Capability {
        name: "allow-tip-sha1-in-want",
        value: CapValue::Bare,
        offered: None,
        honoured: Honoured::By {
            file: UPLOAD,
            code: "fn check_wants",
        },
        // git sets `ALLOW_TIP_SHA1` on its own or as part of `ALLOW_ANY_SHA1`,
        // and gunnar has no separate "tips only, plus hidden ones" policy —
        // `AdvertisedTips` already serves every tip it advertises, so the
        // capability would say nothing. Only `Any` is a promise beyond
        // reachability.
        requires: Some(crate::upload_pack::WantPolicy::Any),
    },
    OBJECT_FORMAT,
    AGENT,
];

/// Every capability `git-receive-pack` advertises. Push has only v0.
pub const RECEIVE_PACK: &[Capability] = &[
    cap("report-status", r#"peer.has("report-status")"#, RECEIVE),
    cap(
        "report-status-v2",
        r#"peer.has("report-status-v2")"#,
        RECEIVE,
    ),
    Capability {
        name: "delete-refs",
        value: CapValue::Bare,
        offered: None,
        // Not `peer.has("delete-refs")`, and that is correct rather than a
        // gap: the capability tells the CLIENT it may send a delete command,
        // and the server's obligation is to carry one out. The code that does
        // is the honouring.
        honoured: Honoured::By {
            file: RECEIVE,
            code: "if command.is_delete()",
        },
        requires: None,
    },
    cap("side-band-64k", r#"peer.has("side-band-64k")"#, RECEIVE),
    Capability {
        name: "quiet",
        value: CapValue::Bare,
        offered: None,
        honoured: Honoured::Vacuously(
            "`quiet` asks receive-pack to suppress its progress reporting. \
             gunnar's receive-pack emits no progress on that connection at \
             all, so there is nothing to suppress and nothing to read the \
             capability for. Vacuously honoured, and recorded as such rather \
             than counted as a reader.",
        ),
        requires: None,
    },
    cap("atomic", r#"peer.has("atomic")"#, RECEIVE),
    Capability {
        name: "ofs-delta",
        value: CapValue::Bare,
        offered: None,
        // The push side is the RECEIVER of ofs-deltas: advertising it tells
        // the client it may send them, and the obligation is to RESOLVE them.
        // There is no `peer.has("ofs-delta")` on this surface and there should
        // not be one — the consumer is the indexer that completes the chains.
        honoured: Honoured::ByDependency {
            krate: "gunnar-pack",
            item: "index_thin_pack",
        },
        requires: None,
    },
    cap("push-options", r#"peer.has("push-options")"#, RECEIVE),
    OBJECT_FORMAT,
    AGENT,
];

/// Every capability the **protocol v2** advertisement carries.
///
/// `ls-refs` and `fetch` carry generated feature lists; the others are their
/// own row. This is what `UploadPack::write_capability_advertisement` writes,
/// rather than a fourth hand-written list beside the table — which is what it
/// was until 2026-08-05, in a different file from the two above.
pub const UPLOAD_PACK_V2: &[Capability] = &[
    AGENT,
    Capability {
        name: "ls-refs",
        value: CapValue::Features(LS_REFS_ARGUMENTS),
        offered: None,
        honoured: Honoured::By {
            file: UPLOAD,
            code: "impl LsRefsRequest",
        },
        requires: None,
    },
    Capability {
        name: "fetch",
        value: CapValue::Features(FETCH_ARGUMENTS),
        offered: None,
        honoured: Honoured::By {
            file: UPLOAD,
            code: "impl FetchRequest",
        },
        requires: None,
    },
    Capability {
        name: "server-option",
        value: CapValue::Bare,
        offered: None,
        honoured: Honoured::Vacuously(
            "protocol v2 says a server SHOULD ignore server options it does \
             not understand, and gunnar defines none. The lines are accepted \
             into `PeerCapabilities` rather than rejected, so a client that \
             sends one is not broken by it. This is NOT the `push-options` \
             case: git hands push options to `pre-receive`, so discarding \
             those was a wrong answer, while discarding server options is \
             what the specification asks for.",
        ),
        requires: None,
    },
    OBJECT_FORMAT,
];

/// Every surface, so a guard can walk all of them without naming three
/// constants and going stale when a fourth appears.
pub const ADVERTISED: &[(&str, &[Capability])] = &[
    ("upload-pack v2", UPLOAD_PACK_V2),
    ("upload-pack v0", UPLOAD_PACK_V0),
    ("receive-pack", RECEIVE_PACK),
];

/// Render one capability's wire spelling, or `None` if it is not on offer.
///
/// `want_policy` is a parameter and not a default because the advertisement
/// genuinely depends on it, and a default would be the drift this whole table
/// exists to prevent: the two `allow-*-sha1-in-want` rows are promises about
/// what `check_wants` will serve, and a server that renders them from anything
/// other than the policy it judges by is advertising a different server.
pub fn render(
    cap: &Capability,
    hash_kind: Kind,
    agent: &str,
    offered: Offered,
    want_policy: crate::upload_pack::WantPolicy,
) -> Option<String> {
    if let Some(feature) = cap.offered {
        if !offered.has(feature) {
            return None;
        }
    }
    if let Some(required) = cap.requires {
        if !want_policy.advertises(required) {
            return None;
        }
    }
    Some(match cap.value {
        CapValue::Bare => cap.name.to_owned(),
        CapValue::ObjectFormat => format!("{}={}", cap.name, object_format_name(hash_kind)),
        CapValue::Agent => format!("{}={agent}", cap.name),
        CapValue::Features(table) => {
            // `Offered` also gates individual v2 features, so this is the same
            // filter `fetch_capability` applies — one writer, not two.
            let features: Vec<&str> = features(table)
                .into_iter()
                .filter(|f| offered.has(f))
                .collect();
            if features.is_empty() {
                cap.name.to_owned()
            } else {
                format!("{}={}", cap.name, features.join(" "))
            }
        }
    })
}

/// The wire lines for a whole surface, in table order.
///
/// **This is the only thing that decides what gunnar advertises.** Before
/// 2026-08-05 the v2 list was generated from the argument table while v0 and
/// receive-pack were hand-written `vec![]`s in this file and the v2 capability
/// names were a fourth hand-written list in `upload_pack.rs` — so
/// `push-options` was a bare string literal that nothing else in the tree had
/// to agree with, and it was advertised, parsed and discarded for the whole of
/// v1. An early audit claimed that *"advertised but
/// not honoured is not something this codebase can express"*; that was true of
/// the v2 arguments and false of the other three lists. Now it is true of all
/// of them, because there is nowhere else to write one down.
pub fn advertise(
    table: &'static [Capability],
    hash_kind: Kind,
    agent: &str,
    offered: Offered,
    want_policy: crate::upload_pack::WantPolicy,
) -> Vec<String> {
    table
        .iter()
        .filter_map(|cap| render(cap, hash_kind, agent, offered, want_policy))
        .collect()
}

/// The `fetch=…` capability line for what is on offer.
pub fn fetch_capability(offered: Offered) -> String {
    let features: Vec<&str> = features(FETCH_ARGUMENTS)
        .into_iter()
        .filter(|f| offered.has(f))
        .collect();
    if features.is_empty() {
        "fetch".to_owned()
    } else {
        format!("fetch={}", features.join(" "))
    }
}

/// The `ls-refs=…` capability line.
pub fn ls_refs_capability() -> String {
    capability("ls-refs", LS_REFS_ARGUMENTS)
}

/// The capabilities `git-upload-pack` advertises in **protocol v0**, where
/// they ride on the first reference line rather than in their own section.
///
/// `multi_ack` and `multi_ack_detailed` are deliberately absent: gunnar
/// negotiates in single-ACK mode, which every git since 2005 still speaks, and
/// advertising a richer ACK protocol than the one implemented is the same
/// class of bug this module exists to prevent.
pub fn upload_pack_v0_capabilities(
    hash_kind: Kind,
    agent: &str,
    offered: Offered,
    want_policy: crate::upload_pack::WantPolicy,
) -> Vec<String> {
    advertise(UPLOAD_PACK_V0, hash_kind, agent, offered, want_policy)
}

/// The capabilities `git-receive-pack` advertises.
pub fn receive_pack_capabilities(hash_kind: Kind, agent: &str) -> Vec<String> {
    // `WantPolicy` decides what a client may *fetch*; push has no `want` at
    // all, so no row in `RECEIVE_PACK` carries a `requires` and the value here
    // cannot change a byte. Passed as the default rather than given its own
    // parameter, because a knob that cannot move is one more thing to keep
    // agreeing about.
    advertise(
        RECEIVE_PACK,
        hash_kind,
        agent,
        Offered::default(),
        crate::upload_pack::WantPolicy::default(),
    )
}

/// The capability set a v0 peer sent on its first line, parsed.
///
/// Values are kept as `Option<String>` so `object-format=sha256` and a bare
/// `atomic` are the same shape.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct PeerCapabilities {
    entries: Vec<(String, Option<String>)>,
}

impl PeerCapabilities {
    /// Parse a space-separated capability string.
    ///
    /// Leading and repeated spaces are tolerated: git's own `receive-pack`
    /// client emits `…\0 report-status-v2 …` with a leading space, which a
    /// naive `split(' ')` turns into a phantom empty capability.
    pub fn parse(text: &str) -> Self {
        let entries = text
            .split(' ')
            .filter(|s| !s.is_empty())
            .map(|item| match item.split_once('=') {
                Some((k, v)) => (k.to_owned(), Some(v.to_owned())),
                None => (item.to_owned(), None),
            })
            .collect();
        PeerCapabilities { entries }
    }

    /// Is this capability present, with or without a value?
    pub fn has(&self, name: &str) -> bool {
        self.entries.iter().any(|(k, _)| k == name)
    }

    /// The value of `name=<value>`, if it was sent with one.
    pub fn value(&self, name: &str) -> Option<&str> {
        self.entries
            .iter()
            .find(|(k, _)| k == name)
            .and_then(|(_, v)| v.as_deref())
    }

    /// Every capability name, in the order sent.
    pub fn names(&self) -> impl Iterator<Item = &str> {
        self.entries.iter().map(|(k, _)| k.as_str())
    }
}

/// Check a peer's `object-format` against the repository's actual hash kind.
///
/// The whole point of object-format negotiation: answering `sha1` to a sha256 repository does not
/// fail, it returns an *empty* response, so the mismatch has to be caught here
/// and turned into an error.
pub fn check_object_format(ours: Kind, theirs: Option<&str>) -> crate::Result<()> {
    let Some(theirs) = theirs else {
        return Ok(());
    };
    if object_format_from_name(theirs) == Some(ours) {
        Ok(())
    } else {
        Err(crate::Error::ObjectFormatMismatch {
            ours: object_format_name(ours),
            theirs: theirs.to_owned(),
        })
    }
}

// ════════════════════════════════════════════════════════════════════════════
// The census: every serving-side policy, and what on the wire declares it
// ════════════════════════════════════════════════════════════════════════════
//
// # Why a second table
//
// [`ADVERTISED`] answers *"does everything gunnar promises have a consumer?"*.
// It cannot answer the inverse — *"does everything gunnar enforces have a
// promise?"* — because the inverse has nothing to walk. A row nothing reads is
// visible; **a policy no row names** is not there at all.
//
// That inverse has produced four wrong answers in this tree in a single day,
// and the sharpest of them, `WantPolicy` (`8f4e6e0`), was invisible in the most
// complete way available: `check_wants` enforced it on every request, no
// capability named it, so stock git refused the `want` on its **own** side and
// gunnar never received the request. No error, no log line, no failing test —
// only a user whose partial clone could not check out.
//
// So every field of every serving-side `Config`, plus every field of
// [`Offered`], is listed here with a verdict, and
// `tests/advertisement.rs::every_serving_policy_is_declared_somewhere` reads the
// **struct definitions out of the source** and refuses to pass while one of
// them is missing from this list. Adding a knob that changes what a client gets
// is therefore not something you can forget to classify; it is something that
// does not compile past the test suite.

/// How a serving-side policy reaches the peer.
///
/// The three arms are not degrees of quality — they are three different
/// contracts, and picking the wrong one is the defect. `WantPolicy` was
/// implicitly treated as [`Self::Refuses`] and was in fact silent: the refusal
/// happened inside the *client*, which is the one place a server's error can
/// never reach.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Declared {
    /// Named on the wire as this capability, so a peer can see it **before it
    /// asks** and shape its request around it.
    ///
    /// Required whenever the peer's behaviour depends on knowing: git's client
    /// will not send `filter`, `thin-pack` or a `want` for an unadvertised
    /// object unless the corresponding capability was advertised.
    As(&'static str),
    /// Not on the wire, and it does not have to be, because when it applies the
    /// peer gets an **error that says so**.
    ///
    /// This arm is a claim about something arriving, so it carries the tests
    /// that watched it arrive. "It refuses" is only a safe answer if the
    /// refusal is observable at the far end; a limit that silently truncates a
    /// pack, or that is enforced inside the client, is not this arm.
    Refuses {
        /// `<workspace-relative file>::<test fn>`, one or more, each of which
        /// asserts the peer sees the refusal. Checked to exist.
        seen_by: &'static [&'static str],
        /// What the peer actually sees.
        reason: &'static str,
    },
    /// The peer gets an error that says so — and **nothing in this repository has
    /// watched it arrive**.
    ///
    /// Split out of [`Refuses`](Self::Refuses) on 2026-09-09, because `limits` was
    /// using that arm while citing three tests at
    /// `../edda/crates/storage-git-gix/parked-gix-2/gunnar-wire-gix/tests/fetch_memory.rs`.
    /// Two things were wrong with that and only one of them was the sibling path:
    /// `parked-gix-2` is quarantined salvage, named by neither edda's `include`
    /// list nor any published tarball, so the citation resolved on exactly one
    /// machine and nowhere else. The guard "checks the citation exists", and what
    /// it was checking was one developer's disk.
    ///
    /// So the uncovered case gets its own name instead of borrowing the covered
    /// one's. The reason must say what the peer sees AND what would cover it —
    /// this arm is an admission, and an admission that does not name its way out
    /// becomes furniture.
    RefusesUncovered(&'static str),
    /// Nothing a peer can observe, and here is the argument for why.
    ///
    /// The escape hatch, and it has to cost a sentence — the same rule
    /// [`Honoured::Vacuously`] carries, for the same reason.
    Invisible(&'static str),
}

/// One field of a serving-side configuration struct, and its verdict.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Policy {
    /// The field's name, exactly as the struct spells it.
    pub field: &'static str,
    /// How it reaches the peer.
    pub declared: Declared,
}

/// A struct whose fields are serving-side policy, with a verdict on every one.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PolicySurface {
    /// The surface's name, for a failure message.
    pub surface: &'static str,
    /// Workspace-relative path to the file the struct is written in.
    pub file: &'static str,
    /// The struct's opening line, verbatim, so the guard can find it.
    pub declaration: &'static str,
    /// Every field, in any order. The guard asserts this set equals the set in
    /// the source — in **both** directions, so a stale entry fails too.
    pub fields: &'static [Policy],
}

/// Every configuration surface that decides what a peer gets.
pub const SERVER_POLICIES: &[PolicySurface] = &[
    PolicySurface {
        surface: "upload-pack",
        file: "crates/gunnar-wire/src/upload_pack.rs",
        declaration: "pub struct Config {",
        fields: &[
            Policy {
                field: "agent",
                declared: Declared::As("agent"),
            },
            Policy {
                field: "offered",
                // The struct is one field wide and that field is `filter`;
                // `Offered` has its own row below, so this is not the place the
                // claim is checked.
                declared: Declared::As("filter"),
            },
            Policy {
                field: "want_policy",
                // The defect of 2026-08-05. Before `8f4e6e0` this was enforced
                // by `check_wants` and named by nothing, and the failure landed
                // inside the client where no server error could reach.
                declared: Declared::As("allow-reachable-sha1-in-want"),
            },
            Policy {
                field: "budget",
                declared: Declared::Refuses {
                    seen_by: &["crates/gunnar-cli/tests/wire_config.rs::\
                         a_traversal_budget_of_one_refuses_a_clone_rather_than_truncating_it"],
                    reason: "the walk stops at the ceiling and the request is REFUSED, so the \
                             client's `git clone` fails with the server's message. A budget \
                             that truncated the pack instead would be a wrong answer and would \
                             belong in no arm of this enum — which is why the test asserts the \
                             clone failed AND that no repository was left behind, rather than \
                             asserting an exit code.",
                },
            },
            Policy {
                field: "limits",
                declared: Declared::RefusesUncovered(
                    "UNCOVERED HERE, and the arm now says so rather than citing a path. All \
                     three ceilings raise a named error — `ObjectTooLarge`, `RequestTooLarge`, \
                     `WalkTooLarge` — that travels to the client as an `ERR` pkt-line or on \
                     band 3, and an object over the ceiling is REFUSED and not skipped, \
                     because a pack whose closure does not hold is a corrupt clone rather \
                     than a refused one; `limits.rs` argues that at length. The tests that \
                     watched two of the three arrive \
                     (`a_blob_over_the_ceiling_is_refused_by_name`, \
                     `a_v0_have_flood_is_refused_at_the_ceiling`, \
                     `a_v2_argument_flood_is_refused_at_the_ceiling`) are PARKED in edda's \
                     `storage-git-gix/parked-gix-2/` — quarantined salvage, in no published \
                     tarball and in no clone of this repository — because their fixture \
                     opened an FsStore and the packfile engine is amputated. THE WAY OUT is \
                     a MemStore fixture, which is gix-free and already in gunnar-store: port \
                     the three tests onto it, here, and this field goes back to `Refuses` \
                     with citations that resolve for everyone. The third ceiling, \
                     `walk_bytes`, IS covered — `walk_limit.rs` reads the sentence off the \
                     wire — and is a separate field for that reason.",
                ),
            },
            Policy {
                field: "walk_pool",
                declared: Declared::Refuses {
                    seen_by: &["crates/gunnar-wire/tests/walk_limit.rs::\
                         a_full_pool_is_a_different_sentence_from_a_request_that_will_never_fit"],
                    reason: "the server-wide memory ceiling, and the one policy here whose \
                             answer depends on what OTHER clients are doing. It refuses with \
                             `WalkPoolFull`, which is deliberately a different sentence from \
                             `WalkTooLarge`: this one says the machine is busy and a retry will \
                             work, and the other says the request will never fit. A client that \
                             cannot tell them apart retries the first forever and gives up on \
                             the second. Nothing is advertised, because nothing a client could \
                             be told before it asks would still be true when it did — the \
                             answer is a property of the moment.",
                },
            },
        ],
    },
    PolicySurface {
        surface: "receive-pack",
        file: "crates/gunnar-wire/src/receive_pack.rs",
        declaration: "pub struct Config {",
        fields: &[
            Policy {
                field: "agent",
                declared: Declared::As("agent"),
            },
            Policy {
                field: "budget",
                declared: Declared::Refuses {
                    seen_by: &[
                        "crates/gunnar-wire/tests/protocol.rs::\
                         the_connectivity_budget_refuses_a_push_rather_than_accepting_it_unchecked",
                        "crates/gunnar-wire/tests/protocol.rs::\
                         a_mixed_push_refuses_only_the_reference_that_does_not_close",
                    ],
                    reason: "the connectivity walk's ceiling. Exceeding it, like failing the \
                             walk itself, turns into a per-reference `RefStatus::Rejected` \
                             carrying the reason, which the status report puts in front of \
                             `git push`, and the reference does not move. The first test sets \
                             the budget to 1 over six unreachable commits and reads the status \
                             report; the second is what says the refusal is per reference and \
                             not per push. The first was written for this entry: until then \
                             the only citation available proved the reporting mechanism and \
                             never set a budget, which is a claim standing next to its \
                             evidence rather than on it.",
                },
            },
            Policy {
                field: "pack_ceiling",
                declared: Declared::Refuses {
                    seen_by: &[
                        "crates/gunnar-wire/tests/pack_ceiling.rs::\
                         a_push_over_its_ceiling_is_cut_mid_transfer",
                        "crates/gunnar-wire/tests/pack_ceiling.rs::\
                         a_push_of_exactly_the_ceiling_lands",
                        "crates/gunnar-server/tests/pack_ceiling_store.rs::\
                         a_cut_push_stores_nothing_and_leaves_the_repository_usable",
                        "crates/gunnar-wire/tests/concurrent_pack_ceiling.rs::\
                         simultaneous_pushes_are_not_each_admitted_against_the_same_measurement",
                    ],
                    reason: "the byte ceiling a push is held to WHILE it arrives, and the one \
                             policy here that a client cannot be told before it asks — because \
                             the thing it bounds is not knowable before it asks. A pack header \
                             carries an object count, not a byte count, so neither side knows \
                             the size of a push at negotiation time; there is no number to put \
                             in a capability and nothing a client could do differently if there \
                             were. So it refuses, and the refusal is the whole surface: the \
                             read is cut one byte past the ceiling, `unpack <reason>` carries \
                             the setter's own sentence (which names the ceiling and why \
                             — never the indexer's opinion of a truncated stream), \
                             and every reference is reported `ng`. The first citation is the \
                             one that matters and it asserts BYTES, not a verdict: a server \
                             that read the whole 400 GiB and then refused would satisfy any \
                             assertion about the report and is a different bug. The second is \
                             the boundary — a push of exactly the ceiling LANDS — and the \
                             third is the same cut against the real znippy engine, which is \
                             where `nothing was stored` costs something to be true. The \
                             fourth is the number's OTHER half, added 2026-09-08: the \
                             ceiling is one namespace's room and not one connection's, so \
                             eight pushes that measured it together spend it once between \
                             them (`PackCeiling::ledger`). Without it three green citations \
                             stood over a limit N simultaneous pushes could spend N times.",
                },
            },
            Policy {
                field: "notice",
                declared: Declared::Invisible(
                    "It is not a policy: the push it rides on is ALLOWED. `notice` is one \
                     human-readable line put on the progress band (`remote: …`) beside a \
                     report that is otherwise byte-for-byte what it would have been — the \
                     metered appliance's `plan expired <date>; renew at <url>` for a tenant in \
                     Grace. Nothing about the request has to be shaped around knowing it, so \
                     `As` would be a capability no client would read; nothing is refused, so \
                     `Refuses` would have no arrival to cite. The three things that make \
                     `Invisible` the honest arm rather than the convenient one, all readable \
                     at `receive_pack.rs:1445-1455`: it is sent ONLY inside the `if sideband` \
                     arm, so a client that negotiated no sideband gets the bare report and \
                     never a line where the report should be; it is framed separately on band \
                     2, so a client that ignores band 2 parses the report untouched; and it is \
                     written BEFORE the report on band 1, which is presentation order for a \
                     person and nothing a parser depends on. Its absence is exactly the \
                     behaviour that shipped before it existed. If it ever gates, blocks or \
                     shortens a push, it stops being this arm.",
                ),
            },
        ],
    },
    PolicySurface {
        surface: "what is on offer",
        file: "crates/gunnar-wire/src/caps.rs",
        declaration: "pub struct Offered {",
        fields: &[Policy {
            field: "filter",
            declared: Declared::As("filter"),
        }],
    },
];