# gizlang:journal

Shared log coordinates. Durable publication, retention and product events remain with their storage owners; no database or wire adapter is imported.

```gizlang
import * as Journal from "gizlang:journal";
```

## Types

### `Position`

```gizlang
type Position = { shard: string; history: string; sequence: i64; operation: i64; }
```

A place in a journal: its shard, its history, the sequence of the commit and the operation within it.

- `shard`: `string`
- `history`: `string`
- `sequence`: `i64`
- `operation`: `i64`

### `Acknowledgement`

```gizlang
type Acknowledgement = { floor: i64; observed: Position; }
```

Explicit acceptance of terminal outcomes through a request floor and cut.
Product owners retain pending intents and decide what is safely collectible.

- `floor`: `i64`
- `observed`: `gizlang_journal.Position`

## Functions

### `validAcknowledgement`

```gizlang
function validAcknowledgement(acknowledgement: Acknowledgement, history: string, maximumCut: i64): bool
```

Whether ACKNOWLEDGEMENT is valid for HISTORY: it observes the end of a commit of HISTORY at most MAXIMUMCUT.

### `boundary`

```gizlang
function boundary(history: string, sequence: i64): Position
```

The position at the end of commit SEQUENCE of HISTORY.

### `compare`

```gizlang
function compare(a: Position, b: Position): i64 throws string
```

Histories are incomparable; a new history requires a snapshot.

Effects: fail.

### `cursor`

```gizlang
function cursor(position: Position): string
```

Exact coordinates encoded in an opaque, URL-safe, checksummed envelope.

Effects: fail.

### `readCursor`

```gizlang
function readCursor(text: string): Position throws string
```

The position that `text` spells (the form `cursor` writes), or why it is not one.

Effects: fail.

### `retained`

```gizlang
function retained(position: Position, history: string, first: i64, last: i64): bool
```

Whether POSITION is in HISTORY and in the commits FIRST to LAST that the journal keeps.

Effects: fail.

## Constants

### `COMMIT_END`

```gizlang
const COMMIT_END = 9223372036854775807
```

The position that no commit reaches: the open end of a range.

### `SHARD`

```gizlang
const SHARD = "local"
```

The name of the shard of a local journal.