nordisk/holger

holger error codes — holger-<subsystem>-<n>

FROZEN. APPEND-ONLY. NEVER REUSED.

The machine half of every non-UI error holger emits. Each error carries two channels in one message — a visible human string AND this stable code:

[holger-update-22] sequence rollback: bundle sequence 7 is not newer than the accepted 9
 ^^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 machine channel   human channel (the typed error's own safe, path-free message)

Why it matters here

holger is a secure artifact server. The Secure Update Gateway's refusals are trust verdicts: an operator (and an automated importer) must be able to tell "your signature is invalid" from "this bundle is a replay" from "the disk is full". Collapsed into one opaque "rejected", those three demand three different responses and get one. The code makes the verdict machine-checkable while the prose keeps it readable.

The law

• FROZEN — a published code never changes meaning. Reword a summary freely; never re-point a code at a different failure.
• APPEND-ONLY — retire a code by leaving it in the registry and ceasing to emit it. NEVER reuse the number: a retired code in an old audit row must stay unambiguous.
• UNIQUE within its subsystem and globally across the app.
• Consumers may prepend a mount prefix; the parser finds the bracketed code anywhere in the string.
• WIRED or RESERVED, and the claim is guarded. Every row declares whether it is raised today (wired) or merely claimed (reserved), plus the file it is raised in. errcode/tests/wiring_guard.rs checks that against the real source tree in BOTH directions.

wired vs reserved — why the split exists

A registry that merely LISTS codes will happily claim coverage it does not have, and holger shipped exactly that. For four sessions the registry declared 65 codes while 0 of the 38 tonic::Status construction sites — the only surface a remote client ever sees — carried one. Nothing failed, because nothing checked. The declaration was green; the wire raised nothing.

• wired — raised at a real error site in the row's src file. Drop the code from that site and the guard FAILS, naming the code and the file.
• reserved — the number is claimed, frozen and unique so it can never be handed to a different failure later, but no site raises it yet. If a reserved code turns out to BE raised, the guard fails the other way and the row must be promoted.

The second direction is what stops the split degenerating into "mark everything reserved and the guard goes quiet".

The honest number

The count is the headline of the registry section below. Its tables, its counts and each subsystem's next free ordinal are generated from holger_errcode::ALL (the codes! table) by errcode/tests/registry_doc_is_current.rs, which fails while this file and the registry disagree (HOL-DOCFIND, 2026-11-01: the hand-written count said 116 codes in 9 subsystems while the registry held 332 in 42). Regenerate after a registry change:

HOLGER_ERRCODES_REGEN=1 cargo test -p holger-errcode --test registry_doc_is_current

The headings and the prose under each heading are written by hand and kept by the generator. cargo test -p holger-errcode --test wiring_guard is what proves the wired/reserved split honest.

The reserved rows are reserved for stated reasons, not by neglect:

The gRPC wire contract

Every refusal on holger's network surface is built by one function — grpc::coded(&ErrCode, tonic::Code, detail) in server/lib/src/grpc.rs, or by one of its two siblings there: internal_err(e) (a backend failure: the detail goes to the log, the client gets holger-server-4 and "internal error") and refusal(code, why) (a reason worded by the module that decided it: a reason that carries a registry code goes out verbatim with that code on the metadata too, and a reason that carries no code is backend text and is handled as internal_err). grpc.rs holds the only Status::new; the census test grpc::tests::no_service_builds_a_raw_status fails on any other Status::<ctor>( or map_err(Status::..) in server/lib/src (lane C3, 2026-10-20: 46 raw sites at the recount, all routed). So a site cannot drift into a different shape and the two channels can never disagree:

This is the same shape nornir (7b7357a), korp (status_from_tagged) and dwarves (DwarvesError::to_status) use — one suite convention, not four.

Why it matters more than a tonic code: holger-server-1 ("no such repository") and holger-server-2 ("no such artifact") are BOTH tonic::Code::NotFound. The holger code is the only thing that separates them, and a client that must retry one and not the other needs that difference.

Where it lives

errcode/ — a leaf crate with ZERO dependencies, deliberately: the Secure Update Gateway core (update-bundle) is network-free and self-contained, and the registry has to be usable from there and from server/lib while remaining the ONE place codes are allocated. That is what makes a single global uniqueness gate possible.

Codes are declared through the codes! macro, which enrols each one into holger_errcode::ALL in the same breath — a code cannot enter the app without entering the uniqueness gate.

How a typed error gets its code

Every one of holger's error enums carries a code() whose match is exhaustive on purpose — adding a variant without allocating it a code is a COMPILE error, not a runtime surprise:

err.tagged() renders both channels; holger_errcode::parse(&msg) recovers the code.

Gates

Run them: cargo test -p holger-errcode -p holger-update-bundle -p holger-server-lib

What these gates do NOT prove

The wire test asserts 5 distinct codes across 2 of the 8 gRPC services, because those are the refusals a client can provoke from a default RON config. The other 33 sites are covered at SOURCE level only (the wiring guard sees the raise; nothing yet proves their Status leaves the process). Notably holger-server-9 is unreachable from a default config — holger builds a promotion engine by default, so the "capability not configured" branch needs a config that omits one. Closing that gap means a config matrix, not another assertion.

Asserting a code in a test

Assert the code, never a substring of the prose:

assert_eq!(holger_errcode::parse(&e.tagged()), Some(&holger_errcode::UPDATE_SEQUENCE_ROLLBACK));

Suite namespaces

holger-<subsystem>-<n> (this app) · nornir-<subsystem>-<n> · korp-<subsystem>-<n> · dwarves-<subsystem>-<n> · facet-<component>-<n> (facett UI).

The registry — 351 codes across 45 subsystems, 320 wired / 31 reserved

status is the row's WIRING CLAIM, not a wish: wired = raised at a real error site in src today; reserved = the number is claimed, frozen and unique, but nothing raises it yet. errcode/tests/wiring_guard.rs checks BOTH directions against the real source tree, so a lying row FAILS the build.

update — the Secure Update Gateway (update-bundle + holger bundle)

40 code(s) — 37 wired, 3 reserved.

Next free ordinal in update: 41

promote — the promotion ladder (server/lib/src/promote/)

10 code(s) — 10 wired, 0 reserved.

Next free ordinal in promote: 11

intake — the artifact intake chain (server/lib/src/promote/intake.rs)

UNTRUSTED → INGESTED → SCANNED → POLICY_CHECKED → APPROVED → SEALED → PROMOTED → AVAILABLE, with QUARANTINED and BLOCKED as holds. IntakeError::code() maps every refusal.

20 code(s) — 20 wired, 0 reserved.

Next free ordinal in intake: 21

npm — the npm door of the intake chain (server/lib/src/promote/npm.rs, lane P5)

5 code(s) — 5 wired, 0 reserved.

Next free ordinal in npm: 6

cargo — the cargo door of the intake chain (server/lib/src/promote/cargo.rs, lane HOL-CARGO-PUBLISH-DOOR)

4 code(s) — 4 wired, 0 reserved.

Next free ordinal in cargo: 5

bundles — the bundles door of the intake chain (server/lib/src/import_door.rs, lane HOL-BUNDLES-DOOR)

2 code(s) — 2 wired, 0 reserved.

Next free ordinal in bundles: 3

oci — scanned pushes into a writable oci registry (server/lib/src/promote/oci_push.rs, lane HOL-OCI-EVIDENCE)

3 code(s) — 3 wired, 0 reserved.

Next free ordinal in oci: 4

duty — separation of duties on the intake chain (server/lib/src/promote/duties.rs)

Developer, Importer, SecurityApprover, RepositoryAdmin and Auditor are duties of the auth block (edda nornir-auth-policy::Duty). The importer never approves; APPROVED needs promotion.intake.approvals distinct approvers; every approval is an attested statement in the approval evidence slot. DutyError::code() maps every refusal.

7 code(s) — 7 wired, 0 reserved.

Next free ordinal in duty: 8

model — AI model files on the intake chain (server/lib/src/scanner/model.rs)

GGUF, Safetensors and ONNX are first-class model artifacts in a raw repository: the holger-model scanner (slot model) tells each by its content, checks its header and records the architecture, parameter count, tensor count, dtypes and quantization as evidence and as model.* properties. The pickle family (pkl, pickle, pt, pth, joblib, and PyTorch zip checkpoints that hold data.pkl) is blocked by default; models.allow_pickle: ["repo"] turns the block into a warning for the repositories it names.

8 code(s) — 8 wired, 0 reserved.

Next free ordinal in model: 9

audit — the append-only audit log (server/lib/src/audit/)

1..3 are the WRITE failures (the append did not happen). 4..7 are the TAMPER-EVIDENCE verdicts, added when the log stopped being append-only by convention only: every record now carries a blake3 link digest over its own fields and its predecessor's digest, and each segment is seeded from the previous segment's tail. An operator must be able to tell "the disk failed" from "a row was rewritten" from "a whole segment is gone" — they demand three different responses.

13 code(s) — 10 wired, 3 reserved.

Next free ordinal in audit: 14

auth — authentication + RBAC, raised at the gRPC doors

6 code(s) — 4 wired, 2 reserved.

Next free ordinal in auth: 7

server — the request surface (server/lib)

14 code(s) — 14 wired, 0 reserved.

Next free ordinal in server: 15

metered — the paid state (server/lib/src/metered.rs)

7 code(s) — 7 wired, 0 reserved.

Next free ordinal in metered: 8

storage — repositories + object storage (server/repository/*)

5 code(s) — 0 wired, 5 reserved.

Next free ordinal in storage: 6

cli — the thin client holger-cli (holger-cli/, lane B3)

A refusal the server sent keeps the server's own code.

4 code(s) — 4 wired, 0 reserved.

Next free ordinal in cli: 5

jobs — the background job runner

3 code(s) — 0 wired, 3 reserved.

Next free ordinal in jobs: 4

marketplace — cloud-marketplace fulfilment (server/lib/src/marketplace/)

Trust verdicts on an unauthenticated, mutating door (/-/marketplace/landing, /-/marketplace/callback, /-/marketplace/webhook), so every refusal must be distinguishable in the audit row: "the marketplace rejected your token" is not "you are rate-limited" is not "we never sold that plan" is not "you signed in from the wrong directory". Raised by MarketplaceError::code; the HTTP door answers the mapped status, puts the bare code in the JSON body's code field, and sends a browser to the console with ?error=<code>. A caller sees the code and its frozen summary only (MarketplaceError::public_message); the detail stays in the audit row and the server log. The marketplace doors were cut in 9521bf0; the codes stay frozen.

14 code(s) — 0 wired, 14 reserved.

Next free ordinal in marketplace: 15

front — holger.rs's public front page (holger-front/)

5 code(s) — 5 wired, 0 reserved.

Next free ordinal in front: 6

attest — the attestation evidence plane (server/lib/src/attest.rs)

An attestation is a signed statement ABOUT SPECIFIC BYTES. These are deliberately not one "attestation rejected" code: the answers demand different actions — re-sign, re-run the gate against the right artifact, enrol the gate's key, teach the server the predicate, fix the producer's JSON, or fix the trust root itself.

★ attest-3 is the load-bearing one. A DSSE envelope that verifies perfectly but whose in-toto subject[].digest names DIFFERENT bytes is a genuine signature over somebody else's artifact.

★ attest-10 and attest-11 are W17's (2026-09-21). Before them, an unreadable declared trust root was an attest-8 store-I/O error at best and, for an empty or non-DER file, no error at all: from_der_root_files pushed the bytes and the estate verified against fewer roots than it had declared while the boot log said the evidence plane was mounted.

11 code(s) — 11 wired, 0 reserved.

Next free ordinal in attest: 12

plugin — the WASM package-handler host (plugin/host/)

A loaded .wasm is untrusted code running inside the server process. Before these codes the host had Engine::default() and no resource bounds at all — a module could spin forever and hang the request thread, or grow its linear memory until the host OOM'd — and it loaded any file in ron_plugin_dir with no provenance check whatsoever.

Every bound is a NAMED refusal, never a silent kill, because the operator's next move differs per verdict: a runaway handler gets thrown out, a handler that is merely too big for its ceiling gets a bigger ceiling, and a module that fails verification means the plugin directory is not what the operator thinks it is. The limits also fail safe: PluginLimits::default() is bounded, so a missing config is the strict answer, and a configured 0 is refused (holger-plugin-5) rather than read as "unlimited".

plugin-6..9 are the provenance half. A module that fails verification is a ScanError::UntrustedModule — a BOOT error — never a catalog that quietly holds one handler fewer, which is the same rule registry.rs already applies to a missing plugin directory.

13 code(s) — 13 wired, 0 reserved.

Next free ordinal in plugin: 14

mvp — the MVP line's OWN refusals (stinky 1.4, 2026-09-21)

1 code(s) — 1 wired, 0 reserved.

Next free ordinal in mvp: 2

twin — the FOLLOWER role (plan §3 W9, stinky 02 §4.1/§6 S2-3)

22 code(s) — 21 wired, 1 reserved.

Next free ordinal in twin: 23

peer — a downstream holger paired with an upstream holger

5 code(s) — 5 wired, 0 reserved.

Next free ordinal in peer: 6

grow — the data set grows WITHOUT a restart (server/lib/src/grow.rs)

3 code(s) — 3 wired, 0 reserved.

Next free ordinal in grow: 4

scan — the scanner framework and its evidence store (server/lib/src/scanner/)

Every artifact's scan evidence is kept by its SHA-256, append-only and audited, and signed as an attestation. A record that could not be stored, audited or signed is a refusal. ScanError::code() maps every refusal.

5 code(s) — 5 wired, 0 reserved.

Next free ordinal in scan: 6

airgap — the signed export of the approved set and its verified import (server/lib/src/promote/airgap.rs)

The export takes AVAILABLE artifacts from production with their evidence, attestations and SBOMs; its verdict is computed from the stored evidence and an artifact without passing evidence is refused by name. The import re-verifies every payload hash and every evidence attestation and lands each artifact AVAILABLE, audit first.

10 code(s) — 10 wired, 0 reserved.

Next free ordinal in airgap: 11

offline — network: Offline (server/lib/src/egress.rs)

An offline holger refuses a config that needs the network at boot, and refuses every outbound dial before a socket is opened.

3 code(s) — 3 wired, 0 reserved.

Next free ordinal in offline: 4

import — the box's import doors (lane W4, server/lib/src/import_door.rs)

11 code(s) — 11 wired, 0 reserved.

Next free ordinal in import: 12

admission — the door's fair-share gate (server/lib/src/admission*.rs)

2 code(s) — 2 wired, 0 reserved.

Next free ordinal in admission: 3

migration — MigrationService (server/lib/src/grpc/migration.rs)

1 code(s) — 1 wired, 0 reserved.

Next free ordinal in migration: 2

account — the repositories a person has (server/lib/src/account.rs, lane P4)

holger.account.v1.CreateRepository: an admin makes a private repository. Each refusal names what was asked for; nothing is made on any of them.

7 code(s) — 7 wired, 0 reserved.

Next free ordinal in account: 8

token — repository tokens for package clients (lane P3)

A repository token is what cargo, pip, npm and mvn carry instead of a passkey (server/lib/src/repo_token.rs, gRPC holger.token.v1.TokenService, CLI holger-server token). A refusal names the token's fault and never another person, another repository or what the token is for; an unknown secret gets the plain 401 a forged one gets.

11 code(s) — 11 wired, 0 reserved.

Next free ordinal in token: 12

provenance — (lane G3a, 2026-10-23): the intake provenance scanner

13 code(s) — 13 wired, 0 reserved.

Next free ordinal in provenance: 14

sandbox — (lane SANDBOX-SCAN, 2026-10-23): scanning runs in a container

20 code(s) — 20 wired, 0 reserved.

Next free ordinal in sandbox: 21

sync — the sync protocol between an upstream and its downstreams (Holger v2.0 H4)

11 code(s) — 11 wired, 0 reserved.

Next free ordinal in sync: 12

downstream — (Holger v2.0 H3, 2026-10-25): the on-prem gateway, --features downstream

5 code(s) — 5 wired, 0 reserved.

Next free ordinal in downstream: 6

depset — a pull's dependency closure, approved as one set (lane HOL-DEPSET-APPROVE)

4 code(s) — 4 wired, 0 reserved.

Next free ordinal in depset: 5

boundary — a downstream's one-way boundary (lane HOL-CDS, owner 2026-10-30)

3 code(s) — 3 wired, 0 reserved.

Next free ordinal in boundary: 4

export — the upstream's push into the diode folder (lane HOL-CDS)

2 code(s) — 2 wired, 0 reserved.

Next free ordinal in export: 3

listen — the listeners' safe defaults (lane HOL-NCSC, NCSC P1, owner 2026-10-30)

6 code(s) — 6 wired, 0 reserved.

Next free ordinal in listen: 7

tls — the doors' TLS material (lane HOL-NCSC, NCSC P3)

1 code(s) — 1 wired, 0 reserved.

Next free ordinal in tls: 2

sigs — scanner signatures as a signed bundle (lane HOL-NCSC, NCSC P2/P3)

3 code(s) — 3 wired, 0 reserved.

Next free ordinal in sigs: 4

trust — the estate's Sigstore trust root (server/lib/src/sigstore_trust.rs, lane HOL-OCI-EVIDENCE)

3 code(s) — 3 wired, 0 reserved.

Next free ordinal in trust: 4

time — the monotone time floor and the signed time token (lane HOL-NCSC, NCSC P3)

3 code(s) — 3 wired, 0 reserved.

Next free ordinal in time: 4

key — a private key file is the process's alone (lane HOL-NCSC, NCSC P3)

2 code(s) — 2 wired, 0 reserved.

Next free ordinal in key: 3