# `PtcRunner.TraceLog.Introspection.Holder`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/trace_log/introspection/holder.ex#L1)

Host-side owner of a loaded turn-log event list backing an introspection
grant (P2 of `docs/plans/sandbox-heap-rebaseline.md`).

`PtcRunner.TraceLog.Introspection.tools/2` starts one holder per path/list
source; the granted closures ask the holder for *projections*, so the
events never enter the sandbox process and a program's heap cost tracks
each result, not the log.

**Lifecycle:** the holder monitors the process that created the grant and
stops when it goes down, so a grant cannot leak past its session. The
reverse direction is isolated: a holder crash surfaces to callers as a
failed `query/3`, never as an exit signal into the owner.

**Bounds:** refuses event lists over `:max_bytes` (serialized size) at
load — fail closed with a clear error rather than silently truncating,
because an analysis over silently-dropped events would read as "covered
everything". (The live `PtcRunner.TraceLog.MemorySink` is different: its
ring-buffer eviction is the documented retention policy.)

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `query`

```elixir
@spec query(pid(), ([map()] -> term()), timeout()) :: term()
```

Runs `fun` over the held events inside the holder and returns its result.

`fun` must be host-trusted code; if it raises, the error is re-raised in
the caller and the holder survives.

# `start`

```elixir
@spec start(
  [map()],
  keyword()
) :: {:ok, pid()}
```

Starts a holder owning `events` for the calling process.

Options: `:max_bytes` — serialized-size load cap (default
67108864). Raises `ArgumentError` when the events exceed it.

---

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