API Reference Lucerna v#0.0.1-alpha.0

Lucerna SDK for Elixir — feature gates, experiments and identity.

401/403 — the key is unknown, revoked, or lacks the required grant.

Validated, immutable configuration for one Lucerna instance. Built once in Lucerna.start_link/1 — bad options raise ArgumentError at boot, never later. There is no application-env configuration by design: opts go to the supervision child spec.

Server-side gates reads. The hot path has no process: an ETS lookup, a pure evaluation, done. No call funnels through a mailbox.

The Gates evaluation engine — pure functions over a compiled runtime, no I/O and no processes. Ported from @lucerna/gates-core (sdks/core/src/evaluate.ts) onto the frozen bucketing contract in Lucerna.Gates.Hashing; the golden vectors in sdks/core/src/vectors.json pin parity.

The frozen bucketing contract (never change this)

The newest runtime document shape this engine understands. A document with a higher schemaVersion means the SDK needs an upgrade — keep the current runtime instead of half-reading it.

The boring ETS owner. Holds the snapshot table and does exactly two things: apply snapshots and settle the ready gate. All crash-prone work (HTTP, decode, backoff) lives in Lucerna.Gates.Sync — the supervisor's one_for_one strategy exists precisely so a Sync crash cannot take this table down with it.

The runtime poller: one conditional fetch of GET /sdk/v1/gates/runtime at boot (via handle_continue, so the supervisor is never blocked), then again every refresh_interval.

The transport seam. Any module implementing this behaviour can replace the bundled Finch adapter via the :http option — that is how tests inject a scripted fake and how exotic runtimes bring their own client.

Default transport: the Finch pool the Lucerna supervisor starts for its instance. adapter_opts is the Finch pool name.

The shared "who is the user" primitive — one immutable value, built once per request, that feeds both products: gates reads take it positionally, Lucerna.identify/1 sends it to People. Mirrors GatesIdentity / identity.current() in the JS SDKs and Lucerna::Identity in the Ruby gem.

Fire-and-forget outbound delivery: experiment exposures batched to POST /sdk/v1/events, identify payloads sent one-by-one to POST /sdk/v1/people/identify.

A transport or API failure. status is nil for network-level failures (timeout, refused connection), the HTTP status otherwise.

Trait normalization. Traits are always %{String.t() => String.t()} on the wire and in the engine — stringification happens at the boundary.