Reference

Contract Versioning

OpenAPI, schemas, protocols, CLI, SDKs, generated examples, and error codes.

PublicSource-ownedMarkdown export

HELM Decision PathEvery governed call produces receipts that can be inspected, exported, and verified.

Audience

Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

Source Truth

Public route: reference/sdks/contract-versioning
Source document: helm-ai-enterprise/docs/public/reference/sdks/contract-versioning.md
Public manifest: helm-ai-enterprise/docs/public-docs.manifest.json
Source inventory: helm-ai-enterprise/docs/source-inventory.manifest.json
Validation: corepack pnpm run docs:coverage, corepack pnpm run docs:truth, and npm run coverage:inventory from docs-platform

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

Troubleshooting

Symptom	First check
A link or route is missing from the docs website	Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation.
A claim is not backed by code or tests	Remove the claim or add the missing code, example, schema, or validation command before publishing.

Version Format

HELM uses semantic versioning for the API contract:

Major (breaking): endpoint removal, required field addition, error shape change
Minor (additive): new endpoint, optional field, new reason code
Patch (fix): documentation, example correction

Current Version

0.1.0 — Initial Kernel release.

Version Sources

Location	What it governs
`api/openapi/helm.openapi.yaml` -> `info.version`	Canonical contract version
`sdk/*/package.json` / `pyproject.toml` / etc.	SDK package version (tracks contract)
`apps/controlplane/cmd/controlplane` build metadata	Server binary version

Stability Guarantees

Stable (v0.1+)

Error envelope shape: { error: { message, type, code, reason_code, details? } }
Reason code set (additive only — codes are never removed)
Endpoint paths for: proxy, approval, proofgraph, evidence, conformance, health

Unstable (may change in v0.2)

Response field additions (additive, won't break)
New endpoints (additive)
details object contents

Drift Prevention

Generated types in sdk/*/types_gen.* are regenerated by scripts/sdk/gen.sh. CI runs scripts/ci/sdk_drift_check.sh on every PR — fails if diff exists.

Adding a New Endpoint

Add to api/openapi/helm.openapi.yaml
Run bash scripts/sdk/gen.sh
Update wrapper clients in sdk/*/client.*
Add examples to examples/
CI will validate drift + build

Diagram

Diagram1. Ingestion & Context Plane -> Contract schema -> SDK codegen -> SDK package -> SDK contract tests -> Public SDK docs -> Compatibility window

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        schema["Contract schema"]
        codegen["SDK codegen"]
        sdk["SDK package"]
        tests["SDK contract tests"]
        docs["Public SDK docs"]
        lifecycle["Compatibility window"]
    end

    %% Operational Flow Edges
    schema --> codegen
    codegen --> sdk
    sdk --> tests
    tests --> docs
    schema --> lifecycle

    %% Premium Styling Rules

Mermaid source

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        schema["Contract schema"]
        codegen["SDK codegen"]
        sdk["SDK package"]
        tests["SDK contract tests"]
        docs["Public SDK docs"]
        lifecycle["Compatibility window"]
    end

    %% Operational Flow Edges
    schema --> codegen
    codegen --> sdk
    sdk --> tests
    tests --> docs
    schema --> lifecycle

    %% Premium Styling Rules

Operational Readiness

Use this page as the public operating layer for Contract Versioning. The source of truth is helm-ai-enterprise/docs/public/reference/sdks/contract-versioning.md; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, llms-full.txt, and MCP without exposing protected routes.

Validation command: corepack pnpm run docs:coverage && corepack pnpm run docs:truth. For website parity, also run npm run exports:boundary and npm run thin-pages:check from docs-platform.

Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.