# MemoryOptions

Configures an in-memory navigation provider from already committed entries.

## Signatures

```ts
export interface MemoryOptions {
    readonly entries: ReadonlyArray<Destination>;
    readonly origin?: string | undefined;
    readonly base?: string | undefined;
    readonly currentIndex?: number | undefined;
    readonly maxEntries?: number | undefined;
    readonly commit?: (before: BeforeNavigationEvent, runHandlers: (destination: Destination) => Effect.Effect<void>) => Effect.Effect<Destination, NavigationError>;
}
```

## Why

SSR, tests, and non-browser runtimes need deterministic history without emulating `window`.
`maxEntries` bounds retained history; pushing after traversal truncates forward entries. `entries`
must be non-empty, `maxEntries` must be greater than zero, and `currentIndex` must address an entry
that survives the initial tail-retention transform. When `entries.length > maxEntries`, that means
`currentIndex >= entries.length - maxEntries`. The provider currently trusts these invariants:
violating them can produce a negative transformed index and an undefined `currentEntry`. Despite
its name, `maxEntries: 0` currently retains every entry because `slice(-0)` is `slice(0)`. Prefer
{@link initialMemory} when starting from a URL rather than a prebuilt history snapshot.

## Ownership and lifetime

The Layer retains the supplied `entries` array as its initial snapshot; it does not clone it.
Callers must treat that array and its destinations as immutable. Later transitions install new
arrays in the provider RefSubject. A custom `commit` function is retained for the service lifetime.

## Property: base

The structural base path exposed by the active provider.

## Property: base: Why

Routers can establish a stable mount root separately from the changing current URL.

## Property: base: Ownership and lifetime

The string is read when the Layer is acquired and retained on the Navigation service.

## Property: commit

The backend hook that commits a prepared memory transition.

## Property: commit: Why

Advanced providers can preserve the shared state machine while controlling persistence and handler timing.

## Property: commit: Ownership and lifetime

The provider retains the function for its service lifetime and invokes its returned Effect once
per commit. Resources acquired by that Effect follow the active navigation fiber and its Scope.

## Property: currentIndex

The zero-based active position before initial tail retention.

## Property: currentIndex: Why

SSR snapshots and tests can restore traversal position instead of assuming the last entry, but
the selected entry must remain inside the retained tail.

## Property: currentIndex: Ownership and lifetime

The index is read during Layer acquisition. It must address `entries` and, when
`entries.length > maxEntries`, satisfy `currentIndex >= entries.length - maxEntries`. The
retention transform subtracts the evicted prefix length; violating this precondition produces a
negative index and leaves `currentEntry` undefined. No runtime validation is currently performed.

## Property: entries

The initial committed history snapshot in traversal order.

## Property: entries: Why

Back, forward, and keyed traversal need an explicit history model before retention is applied.

## Property: entries: Ownership and lifetime

The Layer retains this array by reference as the first history snapshot. Do not mutate it after
Layer acquisition; later provider updates replace the array rather than taking ownership of caller mutation.

## Property: maxEntries

The positive maximum number of history entries retained by the provider.

## Property: maxEntries: Why

A positive bound makes eviction deterministic: the provider keeps the newest tail and adjusts
the active index by the number of evicted entries.

## Property: maxEntries: Ownership and lifetime

The number is captured by the RefSubject transformation for the Navigation service lifetime and
must be greater than zero. No validation enforces that contract. `0` currently retains all
entries because JavaScript evaluates `slice(-0)` as `slice(0)`; it is not a zero-capacity mode.

## Property: origin

The absolute origin used to resolve relative destinations.

## Property: origin: Why

A single origin makes same-document classification and URL normalization consistent across providers.

## Property: origin: Ownership and lifetime

The string is read when the Layer is acquired and retained on the Navigation service.