Gordon

Appearance

gordon-kernel ​

Purpose ​

Shared kernel for the Gordon trading platform. Provides the error taxonomy (GordonError, ErrorKind, ErrorCode) and the validated W3C TraceId scalar — the narrow, frozen-ish leaf that every v7 service depends on. Carved out of gordon-contracts at the 7.0 split (2026-05-15) to isolate the stable, never-churning surface from higher-frequency domain types and bus wire payloads.

Version + status ​

2.0.0 — frozen-ish. Minor bumps on new ErrorCode / ErrorKind variants. Major bumps on renames, removals, or boundary shifts. Every consumer pins ^2 since the DP-15a batch (2026-05-17).

Public surface ​

  • error — GordonError, ErrorKind, Result<T>. From<sqlx::Error>, From<reqwest::Error>, From<serde_json::Error> (orphan-rule forces these to live here). ErrorKind::ColumnDecodeFailed { column: String } added at 2.0.
  • errors — ErrorCode enum, ErrorCategory, ErrorSeverity, remediation URL accessor, the unified gordon_log! macro plus gordon_error! / gordon_warn! thin shims that emit stable structured logs.
  • trace — TraceId: validated W3C 32-hex scalar. Manual Deserialize routes every wire value through TraceId::new, so garbage payloads fail decode at the type boundary.

2.0 changes (DP-15a, 2026-05-17) ​

  • TraceContext moved to gordon-platform::trace. Runtime plumbing now lives in the runtime crate. TraceId stays here as a pure value-type wire scalar so gordon-protocol is not forced to depend on a runtime-libs crate.
  • #[non_exhaustive] dropped on ErrorCode. Major-pinning (^2) is the new contract. New variants arrive as part of explicit major bumps, not opportunistic minors.
  • gordon_error! / gordon_warn! collapsed onto gordon_log!. Single primitive macro parametric over tracing::Level; the two named macros survive as thin level-pinned shims so call sites remain greppable in Loki.
  • ErrorKind::ColumnDecodeFailed { column: String } added. sqlx::Error::ColumnDecode routes here instead of the opaque SchemaMismatch sentinel.

Macros ​

gordon_log! is the primitive. gordon_error! / gordon_warn! pin tracing::Level::ERROR / Level::WARN. All three are #[macro_export]'d at the crate root. Every consumer crate that calls any of these macros must have tracing as a direct dependency (not just transitive).

rust
use gordon_kernel::{gordon_log, gordon_error, gordon_warn};

Dependencies of note ​

  • serde — TraceId derives Serialize; the manual Deserialize enforces W3C format validation.
  • sqlx, reqwest, serde_json — minimal, default-features-off; only their Error types are touched for the From<> impls.
  • tracing — underpins gordon_log!.

Invariants ​

  • Frozen-ish. Drift ceiling: 1 minor max. Lagging consumers signal a fix-now obligation.
  • No domain types. Litmus: could this code be lifted into another trading platform? If not, it leaks domain.
  • Zero #[allow(...)].
  • Every ErrorCode variant has a non-test constructor OR a Vestigial since vX.Y docstring. Enforced by scripts/check-errorcode-construction.sh (workspace pre-push Gate 10). A variant with no constructor and no vestigial annotation is treated as a safety claim the runtime does not honour.

Adding a new ErrorCode variant ​

  1. Add the variant to src/errors/codes.rs.
  2. Implement the four accessor arms in src/errors/accessors.rs.
  3. Add a row in the workspace docs/reference/error-codes.md.
  4. Run cargo test — it_errors_taxonomy.rs enforces exhaustiveness.
  5. Wire a non-test constructor within one cycle.
  6. Commit with feat: for minor; feat!: (with BREAKING CHANGE: footer) for major.

Where it lives ​

  • Repo: gordon-kernel/
  • kellnr: https://kellnr.lepaux.com/crates/gordon-kernel (LAN-only)
  • Not on crates.io.

Gordon — keep compounding without blowing up

David Lepaux