capri/types

Public data types shared by Capri’s repository, path, migration, and projection APIs.

Repository capabilities are represented by opaque Repository, Prefix, and TypedPath values so record types remain attached to storage paths. Error types preserve the distinction between absence, invalid stored data, conflicts, and underlying Khepri failures.

Types

Child

</>

A decoded direct child beneath a repository-bound prefix.

all yields these values for direct children only, not deeper descendants.

pub type Child(record) {
  Child(key: Key, path: TypedPath(record), value: record)
}

Constructors

Child(key: Key, path: TypedPath(record), value: record)

Corruption

</>

Stored state that violates a repository’s declared contract.

pub type Corruption {
  MissingPayload(Path)
  UnexpectedStoredProcedure(Path)
}

Constructors

```
MissingPayload(Path)
```
```
UnexpectedStoredProcedure(Path)
```

Decoder

</>

A decoder used to validate and canonicalize repository payloads.

CustomDecoder must return an empty error list for a successful value.

pub type Decoder(value) {
  Decoder(decode.Decoder(value))
  CustomDecoder(
    function: fn(dynamic.Dynamic) -> #(
      value,
      List(decode.DecodeError),
    ),
  )
}

Constructors

```
Decoder(decode.Decoder(value))
```

CustomDecoder(
  function: fn(dynamic.Dynamic) -> #(
    value,
    List(decode.DecodeError),
  ),
)

Entry

</>

One keyed value in a repository migration dataset.

pub type Entry(value) {
  Entry(key: Key, value: value)
}

Constructors

```
Entry(key: Key, value: value)
```

Error

</>

Registration and opening failures. Decode errors retain the exact child path that contained the invalid payload.

pub type Error {
  Conflict(path: Path)
  DataLossDetected(
    path: Path,
    from_version: Int,
    to_version: Int,
  )
  DataLossNotProven(
    path: Path,
    from_version: Int,
    to_version: Int,
  )
  DescendantsPresent(path: Path)
  DuplicateKey(path: Path)
  InvalidChildKey(prefix: Path, key: dynamic.Dynamic)
  InvalidMigration(from_version: Int, to_version: Int)
  InvalidMigrationOrder(expected: Int, actual: Int)
  InvalidPrefix
  InvalidRepositoryId
  InvalidRepositoryVersion(version: Int)
  KhepriError(khepri_error.Error)
  MalformedMetadata(path: Path, payload: dynamic.Dynamic)
  MigrationCallbackFailed(
    path: Path,
    from_version: Int,
    to_version: Int,
    failure: MigrationFailure,
  )
  MigrationRequired(
    path: Path,
    from_version: Int,
    to_version: Int,
  )
  MigrationVersionMismatch(
    path: Path,
    expected: Int,
    actual: Int,
  )
  MissingChildPayload(path: Path)
  MissingMigration(
    path: Path,
    from_version: Int,
    to_version: Int,
  )
  MissingRepositoryMetadata(path: Path)
  NewerRepositoryVersion(
    path: Path,
    registered: Int,
    requested: Int,
  )
  RecordDecodeFailed(
    path: Path,
    errors: List(decode.DecodeError),
  )
  RepositoryAlreadyRegistered(path: Path)
  RepositoryIdMismatch(
    path: Path,
    expected: String,
    actual: String,
  )
  ReservedPrefix(path: Path)
  UnexpectedChildStoredProcedure(path: Path)
}

Constructors

```
Conflict(path: Path)
```

DataLossDetected(path: Path, from_version: Int, to_version: Int)

DataLossNotProven(path: Path, from_version: Int, to_version: Int)

```
DescendantsPresent(path: Path)
```
```
DuplicateKey(path: Path)
```

InvalidChildKey(prefix: Path, key: dynamic.Dynamic)

InvalidMigration(from_version: Int, to_version: Int)

InvalidMigrationOrder(expected: Int, actual: Int)

```
InvalidPrefix
```
```
InvalidRepositoryId
```
```
InvalidRepositoryVersion(version: Int)
```
```
KhepriError(khepri_error.Error)
```

MalformedMetadata(path: Path, payload: dynamic.Dynamic)

MigrationCallbackFailed(
  path: Path,
  from_version: Int,
  to_version: Int,
  failure: MigrationFailure,
)

MigrationRequired(path: Path, from_version: Int, to_version: Int)

MigrationVersionMismatch(path: Path, expected: Int, actual: Int)

```
MissingChildPayload(path: Path)
```

MissingMigration(path: Path, from_version: Int, to_version: Int)

```
MissingRepositoryMetadata(path: Path)
```

NewerRepositoryVersion(
  path: Path,
  registered: Int,
  requested: Int,
)

RecordDecodeFailed(path: Path, errors: List(decode.DecodeError))

```
RepositoryAlreadyRegistered(path: Path)
```

RepositoryIdMismatch(
  path: Path,
  expected: String,
  actual: String,
)

```
ReservedPrefix(path: Path)
```

UnexpectedChildStoredProcedure(path: Path)

Key

</>

A supported Khepri path component.

Atoms should come from a bounded set; do not create atoms from untrusted or unbounded input.

pub type Key {
  Atom(atom.Atom)
  Binary(BitArray)
  String(String)
}

Constructors

```
Atom(atom.Atom)
```
```
Binary(BitArray)
```
```
String(String)
```

MigrationFailure

</>

A validation failure returned by a migration callback.

pub type MigrationFailure {
  InvalidMigrationData(message: String)
}

Constructors

```
InvalidMigrationData(message: String)
```

OperationError

</>

Errors returned by repository record operations.

A missing record is represented by None where applicable, not by this error type. AlreadyExists is specific to insert-only writes.

pub type OperationError {
  AlreadyExists(path: Path)
  CorruptRepository(reason: Corruption)
  InvalidData(path: Path, errors: List(decode.DecodeError))
  OperationConflict(path: Path)
  StoreError(khepri_error.Error)
}

Constructors

```
AlreadyExists(path: Path)
```
```
CorruptRepository(reason: Corruption)
```

InvalidData(path: Path, errors: List(decode.DecodeError))

```
OperationConflict(path: Path)
```
```
StoreError(khepri_error.Error)
```

Path

</>

An untyped Khepri address, including the store root.

Repository registration and binding require a non-root, non-reserved path.

pub type Path {
  Path(Subpath)
  Root
}

Constructors

```
Path(Subpath)
```
```
Root
```

Prefix

opaque </>

A validated, non-root prefix carrying a repository capability.

It is produced by repository registration, opening, or binding and is used to derive typed direct-child paths and projection scopes.

pub opaque type Prefix(record)

Repository

opaque </>

A typed, versioned repository definition.

Definitions are inert until registered, opened, or bound to a store path. Appending a migration changes the repository’s record type and version.

pub opaque type Repository(record)

StoreHandle

opaque </>

A handle to a running Khepri store.

pub opaque type StoreHandle

Subpath

</>

The non-empty components of a Path.

pub type Subpath {
  Segment(Key, Subpath)
  Target(Key)
}

Constructors

```
Segment(Key, Subpath)
```
```
Target(Key)
```

TypedPath

opaque </>

An exact child path whose payload is governed by its prefix’s repository.

Record operations use this capability to select the correct decoder.

pub opaque type TypedPath(record)