@dynamicalsystems/kernel-api

The DSG Kernel HTTP API contract: the committed OpenAPI document and the TypeScript types generated from it.

Usage

import type { paths, components, operations } from "@dynamicalsystems/kernel-api";
import document from "@dynamicalsystems/kernel-api/openapi.json";

Refusals

Every 401, 403, 404, 409, and 503 refusal the kernel sends carries one body, the shared dsg.core.refusal/3 profile, with exactly five required fields:

| Field | Value | | --------------- | ---------------------------------------------------------------------------------------- | | profile | The literal dsg.core.refusal/3. | | code | A shared refusal code from @dynamicalsystems/idl, or the kernel's own reason verbatim. | | sentence | One sentence a person can read. | | stage | The hop that refused, from the shared stage list in @dynamicalsystems/idl. | | correlationId | The request's id, for the kernel's log. |

The code and stage lists are defined in dsg-idl and are not restated here. A refusal may also carry detail, and governance refusals may carry recordId and decisionId; both are optional and are the subject of a pending dsg-idl change request (docs/changes/refusal-governance-extension.md in that repository).

Other failures are closed bodies: 400 { "error": "invalid_request", "detail" } from request validation and 500 { "error": "internal", "requestId" } from the error handler.

Peer dependency

@dynamicalsystems/[email protected] exactly; the workspace catalog pins the same version.

Version

The package version is bumped deliberately in package.json when the HTTP contract changes; it is not derived from the kernel release tag. release.yml runs on every v* tag, builds the package, and publishes with pnpm publish --provenance only when that version is not already on npm. A kernel release that leaves the version untouched publishes nothing. Record every wire-visible change in CHANGELOG.md with the version that carries it.

Regenerating

One command regenerates both artifacts from the route schemas:

pnpm --filter @kernel/api openapi:generate

That writes apps/api/openapi.json, copies it to packages/kernel-api/openapi.json, and runs types:generate in this package to refresh src/openapi-types.ts, which carries a generated-file header naming the generator and the source document. Never edit either file by hand: pnpm --filter @kernel/api openapi:check regenerates and fails on any drift, including a stale src/openapi-types.ts. Type generation runs with this package's own typescript 5.9.3 because openapi-typescript 7 does not support TypeScript 7.