# `PtcRunner.PreludeStore`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/prelude_store.ex#L1)

In-memory versioned store for source-bearing capability preludes.

V1 is deliberately prelude-specific and volatile: it provides `list/1`,
`history/2`, `read/2`, compile-on-write `write/4`, and explicit
`set_default/4` over a small handle backed by a single owner process and ETS
rows. Filesystem persistence remains a later plan chunk.

Bounds are fail-closed. `:max_versions` is the retained version window per
id, not a lifetime write count; version numbers remain monotonic while old
superseded rows may be pruned. A version selected with `set_default/4` is
retained alongside the latest-version window.
`:max_ids`, `:max_total_bytes`, and `:max_metadata_bytes` cap node-lifetime
store growth.

# `t`

```elixir
@type t() :: %PtcRunner.PreludeStore{opts: keyword(), pid: GenServer.server()}
```

# `history`

```elixir
@spec history(t(), String.t()) :: {:ok, [map()]} | {:error, map()}
```

Returns bounded summary rows for retained versions of one prelude id.

# `list`

```elixir
@spec list(t()) :: [map()]
```

Returns one bounded current row per prelude id, sorted by id.

# `new`

```elixir
@spec new(keyword()) :: {:ok, t()} | {:error, term()}
```

Starts a volatile in-memory prelude store and returns its handle.

# `read`

```elixir
@spec read(t(), String.t() | map()) ::
  {:ok, PtcRunner.PreludeCandidate.t()} | {:error, map()}
```

Reads a candidate by bare id, `id@version`, or `%{id, version, checksum}` ref.

# `set_default`

```elixir
@spec set_default(t(), String.t() | map()) :: {:ok, map()} | {:error, map()}
```

Moves the bare-id default/current pointer to an existing version.

`id` + `version` is the preferred explicit form. `id@version` or a
`%{id, version, checksum}` ref are also accepted for checksum-pinned default
changes.

# `set_default`

```elixir
@spec set_default(t(), String.t(), pos_integer()) :: {:ok, map()} | {:error, map()}
@spec set_default(t(), String.t() | map(), map()) :: {:ok, map()} | {:error, map()}
```

# `set_default`

```elixir
@spec set_default(t(), String.t(), pos_integer(), map()) ::
  {:ok, map()} | {:error, map()}
```

# `write`

```elixir
@spec write(t(), String.t(), String.t(), map()) :: {:ok, map()} | {:error, map()}
```

Compiles and appends a new prelude version.

The compiled namespace list must be exactly `[id]`. Stored source and metadata
are untrusted; public projections bound and filter them.

---

*Consult [api-reference.md](api-reference.md) for complete listing*