npm package: @hlos-ai/schemas
Description: HLOS Kernel v2 API contract types: responses, errors, receipts, IDs
Latest version: 0.7.1

# @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

```bash
pnpm add @hlos-ai/schemas
```

## Exports

```typescript
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,

  // 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>`

```typescript
// 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>`

```typescript
// 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

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

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

## Links

- [HLOS Platform](https://hlos.ai)