alkgit/docs/architecture/decisions/018-backend-trait-signatures-and-storage-error-model.md

ADR-018: Backend trait signatures and the storage error model

Status

Accepted (resolves review 002 R-1/R-2; amends the scope of ADR-012 §1's A-2 amendment ("all five traits' signatures") and corrects backend.md's RegistryError over-claim ("every failure the trait family can produce"))

Context

Review 001 A-2 pinned #[async_trait] on all five backend traits and its remediation row claims "signatures per ADR-012 §1" — but ADR-012 §1 contains only the registry pair (GitRegistry, GitRegistryStore). Review 002 (R-1) found traits 3–5 (GitRefs, GitPackGen, GitPackIngest) have no pinned signatures anywhere in the corpus: no method names, no shape for the repo parameter, no type for the prepared-updates handoff that atomic depends on, no representation for object ids or push options. These are exactly the implementation-fork hazards review 001's criticals describe: the wire layer and the gix impls are separate workstreams, every invented shape silently enters OQ-03's freeze inventory, and the trait signatures are the first thing both touch.

Review 002 (R-2) found the N-3 pin over-claims in the other direction: RegistryError's five variants cover the registry family (traits 1–2) well, but not the object-storage traits' characteristic failures (missing-object aborts, fsck/unpack failures, CAS-denied refs). The "no catch-all, every failure the trait family can produce" sentence cannot hold for a family it does not describe.

Decision

1. The registry traits stand as pinned

GitRegistry/GitRegistryStore signatures are ADR-012 §1 as amended; nothing here changes them. RegistryError is re-scoped as the error type of the registry family only (see 7).

2. The repo parameter is &RepoRecord on every object-storage method

The wire layer resolves the repo once (ADR-007 step 2), holds the RepoRecord, and passes it. The record carries storage_root — the server-side path the gix impls open (gix-discover + gix_odb::Store::at, backend.md) — so the trait needs no second registry lookup, no registry handle on the object traits, and no new handle type. The never-on-the-wire rule (ADR-008) governs wire surfaces and op responses (N-3's exclusion is an op-response rule); the serving path is in-process by definition and already flows the record.

3. The object-id representation is gix_hash::ObjectId

gix-hash is always-on in the manifest (the wire layer parses pkt-line hex into it), so the trait family shares it rather than inventing a parallel oid type. The type is hash-format-parameterized internally (the enum carries the format tag), so the representation survives an OQ-05 policy change; sha1 is the only constructed format in v1.

4. Signatures

#[async_trait]
pub trait GitRefs: Send + Sync {
    /// Ref listing — advertisement + ls-refs response data.
    /// The full set; ref-prefix filtering is wire-side (client-driven).
    async fn list_refs(&self, repo: &RepoRecord) -> Result<Vec<RefLine>, StorageError>;

    /// One CAS transaction per call (the atomic-correctness home, ADR-013 §7).
    /// Runs the per-ref CAS; per-ref denials are outcomes (RefOutcome), not errors.
    async fn apply_updates(&self, repo: &RepoRecord, updates: Vec<RefUpdate>, atomic: bool) -> Result<Vec<RefOutcome>, StorageError>;
}

#[async_trait]
pub trait GitPackGen: Send + Sync {
    /// closure(wants) − closure(boundary_haves) → pack streamed into sink
    /// (ADR-004's pipeline; missing objects abort per ADR-004 — never a broken pack).
    async fn generate(&self, repo: &RepoRecord, wants: Vec<ObjectId>, boundary_haves: Vec<ObjectId>, limits: Limits, sink: Box<dyn io::Write + Send>) -> Result<(), StorageError>;

    /// The negotiation ack seam (ADR-014 §5, §2's done-round amendment).
    /// A have is recognized iff it exists in the object store; the is-commit
    /// refinement is the wire layer's ACK-line rule, not this method's.
    async fn common_haves(&self, repo: &RepoRecord, haves: Vec<ObjectId>) -> Result<Vec<ObjectId>, StorageError>;
}

#[async_trait]
pub trait GitPackIngest: Send + Sync {
    /// Unpack + index + fsck; prepares the ref updates. Never applies them
    /// (the single CAS home is `GitRefs::apply_updates` — ADR-013 §6–7).
    async fn prepare(&self, repo: &RepoRecord, pack: Box<dyn io::Read + Send>, push_options: Option<PushOptions>, limits: Limits) -> Result<PreparedPush, StorageError>;
}

Owned-value parameters (Vec, Limits, the boxed streams) are the spawn_blocking-friendly shape: the gix impls move them into their internal blocking tasks (backend.md concurrency model — the permit stays wire-side, the threads stay impl-side). Boxed Send + 'static streams are the blocking-side ends the substrate bridges produce (the sideband sink's io::Write end; the request body's io::Read end — the parked-channel bridges are ADR-005 substrate structure, wire-layer-constructed).

5. The shared object-storage types

/// One listed ref. `oid: None` is the unborn symref line (the N-5 rider's
/// "symref-target with no oid"; the wire layer maps it to the zero-oid
/// advertisement/ls-refs line). Advertisement projects oid+name only —
/// peeled tags and symref targets are ls-refs-arg data.
pub struct RefLine {
    pub name: String,
    pub oid: Option<ObjectId>,
    pub peeled: Option<ObjectId>,
    pub symref_target: Option<String>,
}

/// One prepared/applied ref update. `expected: None` = must-not-exist
/// (create); `new: None` = delete. Identical in the prepare handoff and
/// the CAS call — one type across the seam (R-1's fork point).
pub struct RefUpdate {
    pub name: String,
    pub expected: Option<ObjectId>,
    pub new: Option<ObjectId>,
}

/// Per-ref CAS outcome (an outcome, not an error — a stale ref is a
/// business result of receive-pack, ADR-013 §7–8). The reason string is
/// the client-displayed `ng <ref> <reason>` text (server-chosen, verbatim).
pub struct RefOutcome {
    pub name: String,
    pub result: Result<(), String>,
}

/// The prepare output. `unpack` is the report's unpack leg (ok, or the
/// `unpack ng <reason>` text); pack-level validation failures (parse,
/// index, fsck connectivity) land here as the ng leg, not as Err —
/// the session continues to the report per ADR-013 §8. `Err` is for
/// substrate/infrastructure failure only (7).
pub struct PreparedPush {
    pub unpack: Result<(), String>,
    pub updates: Vec<RefUpdate>,
}

/// Parsed push-options — `(key, value)` pairs verbatim, un-interpreted
/// (ADR-013 §11; repeated keys preserved). `None` on `prepare` until the
/// config gate opens; opening the gate later is value-additive.
pub struct PushOptions {
    pub pairs: Vec<(String, String)>,
}

Ref-name validation is not in these types: the deny-list and the funny refname mapping live in the transport layer (ADR-013 §9); the transport consumes PreparedPush.updates, validates names, and builds the apply_updates call.

6. The atomic flag is the call's, not the list's

apply_updates(..., atomic: bool): non-atomic applies each update and reports per-ref outcomes; atomic prepares the whole transaction and commits it only if every update succeeds, mapping the abort to ng <ref> atomic push failure per ADR-013 §10. One flag because both behaviors share one transaction mechanism (§4 above); a per-update policy flag would be a trait redesign for a case ADR-013 already settles.

7. The storage error model: StorageError for traits 3–5

RegistryError (backend.md §Registry types and schemas) is re-scoped: it is the error type of the registry family (traits 1–2) — the "every failure the trait family can produce" sentence now reads "every failure the registry family can produce." The object-storage family gets its own error type:

/// Object-storage family error (GitRefs / GitPackGen / GitPackIngest).
pub enum StorageError {
    /// A requested object does not exist. Generation aborts per ADR-004
    /// (never a broken pack); fsck-level missing reachability is reported
    /// through `PreparedPush.unpack`, not this variant.
    ObjectMissing { oid: ObjectId },
    /// Structurally invalid backend input (malformed pack stream reaching
    /// the impl, an unborn/misconfigured storage root). Session-op error.
    Invalid(String),
    /// Backing-store/filesystem failure (message-only — not
    /// `std::io::Error`, which is not a stable surface; same rule as
    /// `RegistryError::Io`).
    Io(String),
}

Variant	Wire mapping
ObjectMissing	sideband error band (fetch) — reason text may include the oid (the client computed it; no oracle risk)
Invalid	protocol error band (duplex) or 4xx-class body (stateless)
Io	session/op error, substrate-appropriate — same treatment as RegistryError::Io

Per-ref CAS failures are RefOutcome values, not errors (5 above); fsck failures and pack-level corruption are PreparedPush.unpack ng legs (5) — both are protocol reports the session survives, which is exactly what separates them from the error type.

Consequences

• Positive: the trait surface is fully pinned in one place (backend.md remains authoritative per ADR-004's amendment note) — the wire layer, gix impls, and any third-backend embedder now implement against the same signatures; the prepared-updates handoff and the atomic mechanism are type-expressible; the freeze inventory gains real shapes instead of prose (OQ-03); PushOptions' additive path is concrete.
• Negative: frozen Rust-adjacent shapes grow (the five types and the method set join OQ-03's inventory — first-publish compat surface); RefOutcome/unpacked reason strings are the client-visible text surface, which is exactly as ADR-013 §8 planned but is now typed here.
• Neutral: the manifest needs no change (gix-hash, async-trait, and the substrate's channel/parking primitives are all already carried); parameter ownership (boxed streams, owned vecs) is the implementation-fork prevention for the A-6 execution model.

References

• Review 002 R-1, R-2 (the triggers), R-3/R-5/R-6 (the op-surface decisions this ADR's siblings pin in backend.md)
• Review 001 A-2 (the #[async_trait] amendment whose scope is completed here), A-6 (the execution model these signatures imply), N-4 (the PushOptions parameter this ADR types)
• ADR-012 §1 (the registry signatures — unchanged), §3 (ops over the store), ADR-004 (the generation/ingestion pipelines these signatures wrap; backend.md authoritative), ADR-013 §6–9, §11 (prepare/CAS/ atomic/validation/push-options semantics), ADR-014 §2, §5 (common_haves, done-round boundary), ADR-005 (the substrate bridges the boxed streams terminate), ADR-002 (the session tuples carrying the resolution these methods consume), ADR-008 (never-on-the-wire scoping), ADR-009 (Limits in the signatures)
• backend.md §"The trait family" (mirror), §"Registry types and schemas" (the re-scoped RegistryError + StorageError table), OQ-03 (freeze inventory these shapes enter)
• gitoxide: gix_hash::ObjectId (the shared oid type), gix-ref transactions (the CAS apply_updates wraps)