Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RFD-0023 — Kernel API v2 — resource-oriented redesign

Committed Opened 2026-05-03 · Committed 2026-05-03

Question

The original kernel HTTP API at /api/kernel/* accumulated as a flat command-style surface. As the system grew, the surface became hard to navigate and harder to evolve. What’s the v2 design?

Decision

Path-versioned at /api/v2/*. v1 stays operational during the migration window; v2 never loads v1 primitives directly.

Four-surface resource model:

  • /api/v2/schema/* — TBox: concept / role / property declarations, axiom decls, package bundle ingest.
  • /api/v2/canonical/* — ABox primitives: assertions, retractions, individuals, the foundational fact layer.
  • /api/v2/derived/* — derived facts produced by saturation; read-only; demand-driven.
  • /api/v2/scenarios/* — scenario / fork operations: copy-on-write branches, what-if reasoning, rollback.

ADT-honest primitive axiom layer plus an ergonomic composed instance layer. The primitives expose the underlying axiom shapes directly (one ABox primitive per AxiomBody variant). The composed layer provides ergonomic endpoints for common patterns (assert-with-justification, declare-and-axiomatize, etc.).

Named Argon ops as a secondary additive surface. Mutations (RFD-0007) registered in the active package expose as POST /api/v2/<name> endpoints alongside the primitives. The routing is dynamic per-tenant.

Typed via utoipa. SDK generated via orca-codegen. Integration tests carry the documentation.

Rationale

Resource-oriented over command-oriented. v1’s command-style design (/api/kernel/assert, /api/kernel/retract) made every operation a top-level verb. The resource-oriented design lets a single resource path host multiple operations (GET, POST, DELETE) and surfaces the underlying domain structure.

Four surfaces match the underlying architecture. TBox / ABox / Derived / Scenarios is how the kernel internally partitions its work (RFD-0021’s event log + RFD-0022’s projections). Mirroring that in the API makes the surface predictable: a developer who understands the kernel architecture finds the right endpoint by analogy.

ADT-honest primitives plus composed. The primitive layer matches the AxiomBody enum 1:1. The composed layer provides ergonomic shortcuts. Both are documented; the composed layer doesn’t lock developers out of primitive access.

v1 isolation during migration. v2 not loading v1 primitives directly means the migration is straightforward: v1 endpoints stay until clients have moved; no shared state ties v2’s correctness to v1’s continued operation.

Typed via utoipa. Generated OpenAPI spec at kernel/api-spec.v2.json with typed Rust SDK and TypeScript SDK. CI gates verify the spec, the SDKs, and the source agree.

Consequences

  • v2 endpoints in kernel/api/src/v2/.
  • kernel/api-spec.v2.json is the authoritative API contract; regenerated as the source evolves.
  • kernel/api-sdk/ (Rust) and userspace/kernel-api-client/ (TypeScript) generate from the spec.
  • v1 at /api/kernel/* continues to operate; deprecation timeline is a separate concern.
  • New endpoints land as v2-native; v1 receives only critical fixes.