# `PtcRunner.Kernel.EventSink`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/kernel/event_sink.ex#L1)

Bounded in-memory owner for canonical Kernel events.

The sink assigns schema version, run/trace identity, monotonic sequence, and
UTC timestamp. Producers supply only a canonical bounded event type and data
that normalize to JSON without key collisions. Per-event payload accounting
and aggregate accounting cover the payload and complete retained envelope,
respectively, so every retained event is consumable by `TraceLog`.

Under `:normal` policy, a full or unavailable sink ordinarily records or
projects loss without changing workflow execution. An internal normal sink
may opt into fail-closed owner loss so a session cannot continue without its
canonical recorder. Normal sinks reserve two measured terminal envelopes by
default. Private sinks reserve one `run-stopped` envelope so a capacity
refusal can retain a complete terminal trace.
Finalization atomically appends the bounded loss summary and `run-stopped`,
freezes the recorder, and returns the exact terminal batch and drop snapshot.
Runner and session startup atomically claim the recorder while retaining
`run-started`, so one configuration cannot execute twice or concurrently.
Later emits cannot mutate either snapshot. Drop accounting retains at most
sixteen event-type buckets plus a saturating `$overflow` count. The sink
monitors its owner and exits when the owner terminates.

Persistent JSONL storage is an explicit `PtcRunner.Kernel.TraceLog` operation
after collection, not an arbitrary callback in the runtime path.

# `policy`

```elixir
@type policy() :: :normal | :private
```

# `t`

```elixir
@type t() :: %PtcRunner.Kernel.EventSink{
  fail_closed?: boolean(),
  pid: pid(),
  policy: policy(),
  token: reference()
}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `dropped`

```elixir
@spec dropped(t()) :: map()
```

Returns dropped-event counts keyed by event type.

# `emit`

```elixir
@spec emit(t(), binary(), map()) ::
  :ok
  | {:error, :event_sink_error}
  | {:error,
     {:event_capture_limit_exceeded, :normal_event_count | :normal_event_bytes,
      pos_integer()}}
```

Emits one bounded event or applies the sink's loss policy.

# `events`

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

Returns retained canonical events in sequence order.

# `identity`

```elixir
@spec identity(t()) ::
  {:ok, %{run_id: binary(), trace_id: binary()}} | {:error, :event_sink_error}
```

Returns only this sink's run and trace identity to its token holder.

# `policy`

```elixir
@spec policy(t()) :: policy() | {:error, :event_sink_error}
```

Returns the configured loss policy.

# `required_terminal_payload_bytes`

```elixir
@spec required_terminal_payload_bytes(t(), map()) :: pos_integer() | :error
```

Returns the `event_payload_bytes` one terminal payload of `usage` needs.

Admission compares this against the effective limit, and the refusal reports
it, so the number a caller is told to raise to is the number that refused
them. Normal policy charges the saturated reachable drop map at its
conservative bound rather than at whatever the current run happens to hold.

# `start`

```elixir
@spec start(policy(), PtcRunner.Kernel.Limits.t(), keyword()) ::
  {:ok, t()} | {:error, :invalid_event_sink}
```

Starts a sink with one policy and the event bounds from `limits`.

Options are `:run_id`, `:trace_id`, `:owner`, and the internal normal-policy
`:terminal_reserve` and `:fail_closed`. Normal sinks default to the standard
two-event terminal reserve; private sinks reserve one terminal event. IDs
must be valid UTF-8 binaries from 1 through 256 bytes; a unique run ID is
generated when omitted and is also the default trace ID.

# `stop`

```elixir
@spec stop(t()) :: :ok
```

Stops the sink. Calling it after owner-driven shutdown is harmless.

---

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