@hlos-ai/schemas

HLOS Kernel v2 API contract types.

Source of Truth: This package in hlos/packages/hlos-schemas is the canonical source. The standalone hlos-ai/schemas repo is deprecated and will not receive updates.

Published to npm (public) on tag: schemas-v*

Installation

pnpm add @hlos-ai/schemas

Exports

import {
  // Surface enum
  type Surface, SurfaceSchema, SURFACES,

  // Error codes
  type KernelErrorCode, KernelErrorCodeSchema, ERROR_CODE_STATUS,

  // Response envelopes
  type SuccessResponse, type ErrorResponse, success, error,
  type KernelOk, KernelOkSchema, type KernelError, KernelErrorSchema,
  kernelOk, kernelError, type ApiResponse,

  // Receipt
  type SignedReceiptV0, SignedReceiptV0Schema,
  RECEIPT_TYPE_URI, RECEIPT_VERSION, isSignedReceiptV0,

  // Branded IDs
  type WalletId, type PassportId, type ReceiptId,
  type CorrelationId, type IdempotencyKey, type CrossingId,
  generateReceiptId, generateCrossingId,

  // ID format validators
  CrossingIdFormatSchema, ReceiptIdFormatSchema,
  PassportIdFormatSchema, WalletIdFormatSchema,

  // Attribution
  type FundingSource, FundingSourceSchema,
  type CredentialSource, CredentialSourceSchema,
  deriveFundingSource,

  // Crossing hash
  type CrossingSnapshotV0, CrossingSnapshotV0Schema,
  type CrossingHashInputV0, CrossingHashInputV0Schema,

  // Settlement receipt
  SETTLEMENT_AUTHORITY,
  type CrossingSettledReceipt, CrossingSettledReceiptSchema,

  // Family W — Privacy-Preserving Proofs
  W_RPID_DOMAIN, W_TXCTX_DOMAIN,
  type RPID, RPIDSchema,
  type TransactionContext, TransactionContextSchema,
  type TransactionContextHash, TransactionContextHashSchema,
  encodeEpoch, validateTimeWindow,
  W_GOLDEN_FIXTURES,

  // Agents contracts
  type AgentsListResponse, AgentsListResponseSchema,
  type AgentPassportStubResponse, AgentPassportStubResponseSchema,
  type AgentStatus, AgentStatusSchema,
  type AgentType, AgentTypeSchema,

  // Encoding utilities (zero dependencies)
  bytesToBase64url, base64urlToBytes,
  Base64urlSha256Schema, Base64urlEd25519SigSchema,

  // Receipt hash computation (requires @noble/hashes)
  jcsCanonicalize,
  computeReceiptHash, computeContentHash,
  RECEIPT_HASH_GOLDEN_FIXTURE,

  // Finality — Notary Attestation
  type NotaryAttestation, NotaryAttestationSchema,
  type NotarizeResponse, NotarizeResponseSchema,
  type LogInclusionProof, LogInclusionProofSchema,
  FinalityLevel,

  // Golden fixtures
  GOLDEN_FIXTURES,
  FINALITY_GOLDEN_FIXTURES,
} from '@hlos-ai/schemas';

Response Patterns

Reads → SuccessResponse<T>

// GET /api/v2/wallets/:id
const response: SuccessResponse<WalletBalance> = {
  success: true,
  data: { wallet_id: 'wallet_...', balance_cents: 5000 },
  meta: { correlation_id: 'corr-123' },
};

Mutations → SignedReceiptV0<T>

// POST /api/v2/wallets/:id/spend
const receipt: SignedReceiptV0<SpendResult> = {
  '@type': 'https://hlos.ai/schema/SignedReceiptV0',
  version: 0,
  receipt_id: 'rcpt_...',
  content: { type: 'spend', amount_cents: 100 },
  content_hash: 'base64url...',  // SHA-256, base64url
  signature: 'base64url...',     // Ed25519, base64url
  key_id: 'hlos-v2-1',
  issued_at: '2026-01-23T...',
};

Required Headers

| Header | Reads | Mutations | |--------|-------|-----------| | Authorization | ✅ | ✅ | | X-HLOS-Correlation-ID | ✅ | ✅ | | X-HLOS-Surface | ✅ | ✅ | | X-HLOS-Idempotency-Key | ❌ | ✅ |

Encoding (Frozen)

| Field | Encoding | |-------|----------| | content_hash | base64url of raw 32-byte SHA-256 | | signature | base64url of Ed25519 signature | | version | Number (0), not semver string |

Surface Enum

type Surface = 'mcp' | 'x402' | 'events' | 'cli' | 'web' | 'acp' | 'api';

All v2 requests must include X-HLOS-Surface header.

Links

• HLOS Platform