Core Types

Corpus

The main corpus instance returned by create_corpus().build().

type Corpus<Stores extends Record<string, Store<any>>> = {
  stores: Stores
  metadata: MetadataClient
  data: DataClient
}

CorpusBuilder

Builder interface for configuring a Corpus.

type CorpusBuilder<Stores extends Record<string, Store<any>>> = {
  with_backend: (backend: Backend) => CorpusBuilder<Stores>
  with_store: <Id extends string, T>(
    definition: StoreDefinition<Id, T>
  ) => CorpusBuilder<Stores & Record<Id, Store<T>>>
  build: () => Corpus<Stores>
}

Store

Interface for interacting with a versioned data store.

type Store<T> = {
  readonly id: string
  readonly codec: Codec<T>
  put: (data: T, opts?: PutOpts) => Promise<Result<SnapshotMeta, CorpusError>>
  get: (version: string) => Promise<Result<Snapshot<T>, CorpusError>>
  get_latest: () => Promise<Result<Snapshot<T>, CorpusError>>
  get_handle: (version: string) => Promise<Result<{ meta: SnapshotMeta; handle: SnapshotHandle<T> }, CorpusError>>
  get_latest_handle: () => Promise<Result<{ meta: SnapshotMeta; handle: SnapshotHandle<T> }, CorpusError>>
  get_meta: (version: string) => Promise<Result<SnapshotMeta, CorpusError>>
  list: (opts?: ListOpts) => AsyncIterable<SnapshotMeta>
  delete: (version: string) => Promise<Result<void, CorpusError>>
  put_stream: T extends StreamableValue
    ? (stream: ReadableStream<T>, opts?: PutOpts) => Promise<Result<SnapshotMeta, CorpusError>>
    : never
}

get_handle / get_latest_handle and put_stream are the streaming surface — see Streaming.

SnapshotHandle

Lazy handle returned by Store.get_handle / Store.get_latest_handle.

type SnapshotHandle<T> = {
  value: () => Promise<Result<T, CorpusError>>
  bytes: () => Promise<Result<Uint8Array, CorpusError>>
  stream: T extends StreamableValue
    ? () => Promise<Result<ReadableStream<T>, CorpusError>>
    : never
}

Method	Returns	Notes
`value()`	Decoded `T`	Always available.
`bytes()`	The stored bytes (post-encode, pre-decode)	Always available. Includes any wrapper layers (gzip, encrypt).
`stream()`	Decoded `ReadableStream<T>`	Only present when `T extends StreamableValue` and the codec has `decode_stream`.

StreamableValue

type StreamableValue = string | Uint8Array

Value types that can be chunked across a ReadableStream. Streaming reads/writes are only meaningful for byte- or text-shaped payloads — structured T (e.g. User) cannot be streamed without a chunked decoder (NDJSON, etc.) which is out of scope for the v1 streaming API.

Result

All corpus operations return a Result type for explicit error handling — no thrown exceptions.

type Result<T, E = CorpusError> =
  | { ok: true; value: T }
  | { ok: false; error: E }

// Helper functions
const ok = <T>(value: T): Result<T, never>
const err = <E>(error: E): Result<never, E>

Usage

const result = await store.get(version)

if (result.ok) {
  console.log(result.value.data)
} else {
  console.error(result.error.kind)
}

CorpusError

Union type of all possible errors.

type CorpusError =
  | { kind: 'not_found'; store_id: string; version: string }
  | { kind: 'already_exists'; store_id: string; version: string }
  | { kind: 'storage_error'; cause: Error; operation: string }
  | { kind: 'decode_error'; cause: Error }
  | { kind: 'encode_error'; cause: Error }
  | { kind: 'hash_mismatch'; expected: string; actual: string }
  | { kind: 'invalid_config'; message: string }
  | { kind: 'validation_error'; cause: Error; message: string }
  | { kind: 'observation_not_found'; id: string }

Kind	Description
`not_found`	Requested snapshot version doesn’t exist
`already_exists`	Snapshot with this version already exists
`storage_error`	Backend I/O operation failed
`decode_error`	Codec failed to parse stored data
`encode_error`	Codec failed to serialize data
`hash_mismatch`	Content hash verification failed
`invalid_config`	Corpus configuration is invalid
`validation_error`	Schema validation failed (for observations)
`observation_not_found`	Requested observation ID doesn’t exist

SnapshotMeta

Metadata about a stored snapshot.

type SnapshotMeta = {
  store_id: string
  version: string
  parents: ParentRef[]
  created_at: Date
  invoked_at?: Date
  content_hash: string
  content_type: ContentType
  size_bytes: number
  data_key: string
  tags?: string[]
}

PutOpts

Options for storing a snapshot.

type PutOpts = {
  parents?: ParentRef[]
  invoked_at?: Date
  tags?: string[]
}

ListOpts

Options for listing snapshots.

type ListOpts = {
  limit?: number
  cursor?: string
  before?: Date
  after?: Date
  tags?: string[]
}