API Stability

guides/api_stability.md is the 1.x release contract for Rulestead's public API catalog. Symbols listed here are stable across minor and patch releases on the 1.x line. Symbols not listed here may change without notice, even if they are visible in source.

The boundary is intentionally asymmetric:

rulestead ships a broad runtime-facing public contract.
rulestead_admin ships a narrow host-facing mount contract.
Internal implementation details remain flexible behind those package boundaries.

Versioning & Deprecation Policy

Breaking-Change Table

Change Type	Version Required	Example
Removing a listed symbol	Major	Delete `fetch_flag/1`
Renaming a listed symbol	Major	Rename `evaluate/3` to `run/3`
Changing argument count of a listed symbol	Major	`enabled?/3` → `enabled?/2`
Adding a new public module	Minor	New `Rulestead.Hooks` module
Adding a new function to a listed module	Minor	Add `fetch_flag!/1`
Additive telemetry keys	Patch	New metadata key `:latency_band`
Doc-only changes	Patch	Clarify `@doc` for `evaluate/3`

Telemetry-Event Stability Rules

Events in the catalog below are stable for the 1.x line:

Adding a new event name is a minor change.
Removing or renaming an event name or any of its documented metadata keys is a breaking (major) change.
Additive metadata keys on existing events are a patch change.

Soft-Deprecation Policy

When a function will be superseded, the approach is:

Add a note to the @doc of the old function: "Soft-deprecated: use X/N instead. Will be removed in 2.0."
List the function in the Deprecations table below.
Do NOT use the @deprecated macro until all internal callers have been migrated — the mix compile --warnings-as-errors gate in scripts/ci/lint.sh would fail otherwise.

Worked example (docs-only — no real @deprecated here):

# In the @doc for the old function:
#
#   Soft-deprecated: use `evaluate/3` instead. Will be removed in 2.0.
#   The payload-first form provides richer context and result detail.

Deprecations

Function	Deprecated in	Removal target	Replacement
No deprecations in 1.x	—	—	—

Stable `rulestead` Modules

These modules are public in 1.x:

Rulestead
Rulestead.Context
Rulestead.Result
Rulestead.Error
Rulestead.Store
Rulestead.Admin.Policy
Rulestead.Telemetry
Rulestead.Config

The 1.x core module list above remains closed. Supported adopter facades (below) are additionally public on 1.x without opening implementation trees.

Supported adopter facades (post-GA)

`Rulestead.Runtime`

Supported keyed lookup for Phoenix apps using the snapshot cache. Closed function catalog:

evaluate/3
enabled?/3
get_value/4
get_variant/3
explain/3
diagnostics/1

Rulestead.Runtime.Cache, Rulestead.Runtime.Snapshot, and other Rulestead.Runtime.* implementation modules are not public.

`Rulestead.TestHelpers`

Supported Fake-backed test facade:

with_flag/3
put_flag/3
clear_flags/0
seed_bucket/3
assert_flag_evaluated/2

Backed by Rulestead.Fake for in-memory state. Rulestead.Fake.Control is not public.

Stable `Rulestead` Function Catalog

The root facade is a closed catalog in 1.x:

version/0
fetch_flag/1
fetch_flag/2
fetch_flag/3
fetch_flag!/3
fetch_flag!/2
create_flag/1
create_flag/2
update_flag/1
update_flag/2
update_flag/3
save_draft_ruleset/1
save_draft_ruleset!/1
publish_ruleset/1
publish_ruleset!/1
archive_flag/1
archive_flag!/1
engage_kill_switch/1
engage_kill_switch/3
engage_kill_switch/4
release_kill_switch/1
release_kill_switch/3
release_kill_switch/4
list_audit_events/0
list_audit_events/1
rollback_audit_event/1
rollback_audit_event/2
list_flags/0
list_flags/1
list_flags!/0
list_flags!/1
list_environments/0
list_environments/1
list_audiences/0
list_audiences/1
apply_audience_mutation/1
apply_audience_mutation/2
preview_audience_impact/1
preview_audience_impact/2
preview_audience_impact/3
list_audience_dependencies/0
list_audience_dependencies/1
record_evaluation/1
record_evaluation/3
evaluate/2
evaluate/3
evaluate!/2
evaluate!/3
enabled?/2
get_value/3
get_variant/2
explain/2
simulate_flag/3
simulate_flag/4
explain_flag/3
explain_flag/4
diagnostics/0

Public helpers outside the root facade:

Rulestead.Telemetry.span/3
Rulestead.Telemetry.execute/3
Rulestead.Telemetry.attach_many/4
Rulestead.Telemetry.detach/1
Rulestead.Telemetry.base_metadata/2
Rulestead.Telemetry.metadata/1
Rulestead.Telemetry.base_metadata/3
Rulestead.Telemetry.result_metadata/2
Rulestead.Telemetry.result_metadata/3
Rulestead.Telemetry.runtime_metadata/1
Rulestead.Telemetry.runtime_metadata/2
Rulestead.Telemetry.command_metadata/1
Rulestead.Telemetry.command_metadata/2
Rulestead.Config.load/0
Rulestead.Config.schema/0
Rulestead.Config.defaults/0
Rulestead.Config.validate/0
Rulestead.Config.validate/1
Rulestead.Config.validate!/0
Rulestead.Config.validate!/1
Rulestead.Config.load/1

Stable Struct Fields

`%Rulestead.Context{}`

:actor
:targeting_key
:tenant_key
:environment
:attributes
:request_id
:session_id
:strict?

Construction and normalization helpers are public:

Rulestead.Context.new/1
Rulestead.Context.normalize/1

`%Rulestead.Result{}`

:value
:enabled?
:variant
:reason
:matched_rule
:flag_key
:flag_version
:cache_age_ms
:debug_trace

Construction and normalization helpers are public:

Rulestead.Result.new/1
Rulestead.Result.normalize/1

Closed :reason atoms:

:rule_match
:default
:targeting_key_missing
:flag_off
:error

`%Rulestead.Error{}`

:__exception__
:domain
:type
:message
:metadata
:details
:cause
:plug_status

Public helpers:

Rulestead.Error.new/1
Rulestead.Error.normalize/1
Rulestead.Error.domains/0
Rulestead.Error.leaf_types/0

The standard Elixir exception hooks generated for %Rulestead.Error{} remain available when the error is raised or normalized.

Closed :domain atoms:

:evaluation
:ruleset
:kill_switch
:config
:store
:auth

Closed :type atoms:

:flag_not_found
:environment_not_found
:snapshot_not_found
:ruleset_not_found
:missing_targeting_key
:repo_not_configured
:repo_ambiguous
:store_not_configured
:store_adapter_invalid
:store_unavailable
:invalid_command
:invalid_ruleset
:variant_weights_invalid
:invalid_value_projection
:malformed_runtime_data
:flag_archived
:unauthorized
:kill_switch_active
:not_implemented

Jason.Encoder for %Rulestead.Error{} is part of the contract, and it must continue to exclude :cause.

Stable Behavior Seams

`Rulestead.Store`

The store behavior is public. Its callback catalog is closed in 1.x:

fetch_flag/1
fetch_snapshot/1
create_flag/1
update_flag/1
save_draft_ruleset/1
publish_ruleset/1
archive_flag/1
list_flags/1
list_environments/1
list_audiences/1
apply_audience_mutation/1
preview_audience_impact/1
list_audience_dependencies/1
record_evaluation/1
engage_kill_switch/1
release_kill_switch/1
list_audit_events/1
rollback_audit_event/1

`Rulestead.Admin.Policy`

The admin policy seam is public and intentionally small. The decision callbacks are the core of the seam:

can?/4
allow_self_approval?/4
change_request_required?/4

Hosts own authorization. Rulestead does not ship a bundled auth stack. can?/4 maps host actors to the canonical Rulestead operator role model (Viewer, Editor, Admin) and specific workflow actions.

Role vocabulary is also introspectable via four read-only catalog helpers:

governance_actions/0
viewer_actions/0
editor_actions/0
admin_actions/0

These helpers return the closed atom catalogs for each role. They are read-only introspection functions, not decision callbacks. Use them in your can?/4 implementation to stay in sync with the canonical role vocabulary.

Stable Lifecycle Verification Seams

Lifecycle verification in this repo may rely on these public seams:

shared README and guide content
mix rulestead.lifecycle text and JSON behavior
mounted admin route, query, and mount semantics such as ?env=
documented queue-to-review navigation semantics

Those seams are public because they are part of the release-facing docs and host integration contract.

The following are still not public lifecycle API:

internal LiveView modules
DOM structure
CSS classes
test selectors
socket assigns

Use route, query, and mount behavior for lifecycle verification. Do not freeze implementation details that the mounted package intentionally keeps flexible.

Stable Telemetry Contract

The event catalog from Telemetry is part of the public release contract.

Event Catalog

[:rulestead, :eval, :decide, :start]
[:rulestead, :eval, :decide, :stop]
[:rulestead, :eval, :decide, :exception]
[:rulestead, :runtime, :cache, :hit]
[:rulestead, :runtime, :cache, :miss]
[:rulestead, :runtime, :cache, :refresh]
[:rulestead, :runtime, :cache, :stale_used]
[:rulestead, :runtime, :snapshot, :published]
[:rulestead, :runtime, :snapshot, :applied]
[:rulestead, :store, :read, :start]
[:rulestead, :store, :read, :stop]
[:rulestead, :store, :read, :exception]
[:rulestead, :store, :write, :start]
[:rulestead, :store, :write, :stop]
[:rulestead, :store, :write, :exception]
[:rulestead, :admin, :mutation, :start]
[:rulestead, :admin, :mutation, :stop]

Shared Metadata Keys

:flag_key
:flag_type
:environment
:snapshot_version
:cache_age_ms
:reason
:has_targeting_key?
:matched_rule_count

Documented bounded additions:

:operation
:source
:refresh_status
:audit_action
:error_kind

Telemetry remains redacted by default. Raw actor payloads, raw attributes, secret values, Plug structs, LiveView sockets, and Oban jobs are not part of the telemetry contract.

Stable Host Config Schema

Rulestead.Config defines the supported host-app schema under config :rulestead, :host.

Closed top-level keys:

:environment_key
:plug
:live_view
:oban
:runtime
:tenancy

Closed nested keys:

plug.context_assign
plug.targeting_key_sources
live_view.context_assign
live_view.targeting_key_sources
live_view.assign_flags_mode
oban.enabled
oban.context_key
oban.middlewares
runtime.api
runtime.notifier
runtime.health_peer_provider
runtime.pubsub
runtime.pubsub_topic
tenancy.module

Allowed live_view.assign_flags_mode values:

:enabled
:variant
:value
:evaluate

Other application env keys used internally by the library are not part of this host-facing stability contract unless they are documented here later.

Stable `rulestead_admin` Boundary

The admin package contract is intentionally narrow. The public package promise stops at the mount seam and documented host-facing conventions.

Public Admin Seam

RulesteadAdmin.Router.rulestead_admin/1
RulesteadAdmin.Router.rulestead_admin/2
required policy: option implementing Rulestead.Admin.Policy

Required Host Session Keys

"current_actor"
"rulestead_admin_environments"
"rulestead_admin_last_env"

Stable Host-Facing URL Conventions

The route family mounted beneath the chosen base path is public in 1.x:

/
/new
/audit
/:key
/:key/edit
/:key/rules
/:key/simulate
/:key/rollouts
/:key/kill
/:key/timeline

The env query parameter is the canonical environment selector across the mounted UI.

The admin package does not promise internal LiveView module names, DOM shape, or CSS structure. Host apps should integrate at the router, policy, session, and documented URL level only.

Non-Public Surface

The following are explicitly outside the 1.x compatibility promise:

post-GA facade support does not make governance, manifest, or admin LiveView modules public
RulesteadAdmin.Live.*
RulesteadAdmin.Components.*
socket assigns
DOM structure, CSS classes, and test selectors
internal helper modules in either package
internal runtime/cache/store implementation modules
generated telemetry handler table details
unpublished or undocumented modules visible only because they exist in source

These planned seams are also excluded from the stability contract until they ship as documented, tested, supported code:

Rulestead.RuleEngine
Rulestead.EvaluationCache
Rulestead.AuditStore
Rulestead.ActorResolver

If a future guide mentions planned seams for roadmap context, that mention does not make them public API.

The following exported helpers are visible for runtime mechanics but are not a supported public seam in v0.1.0:

Rulestead.Telemetry.dispatch/4

← Previous Page rulestead

Next Page → Upgrading