-spec check() -> {ok, [extension()]} | {error, [problem(), ...]}.

Discover, read and validate without memoising.

The build-time gate (rebar3 asobi check) and the boot backstop run exactly this, so the two can never disagree on anything derived from the loaded application set. The one env-dependent input is the co-mounted http reserved set, which reads nova_apps: the rebar3_asobi_check plugin sets it from the host's release sys_config before calling this, so the gate matches boot, and falls back to reserving nothing extra only when that config cannot be read - in which case boot, which does load sys.config, remains the backstop that refuses.

-spec describe([problem()]) -> [binary()].

Renders validation problems as lines a human can act on.

-spec emit(atom(), binary(), binary(), map()) -> ok | {error, asobi_error:object()}.

Push a named event to a player from an extension's own Erlang code.

Event is <domain>.<name>: each half is [A-Za-z0-9_-] (the exact charset asobi_ws_handler:is_event_name_char/1 allows, so an event name and a game.broadcast name are validated one way), a single dot separates them, and the whole is at most 64 bytes. domain must be an RPC prefix Extension owns - derived exactly as an error code's domain is (see asobi_extension). Data is always a JSON object; a non-map is a caller bug and fails the guard.

The ownership check is namespace hygiene, not an authorization boundary: it stops an extension minting events in a namespace it does not own, the same anti-collision rule its error codes obey. Any first-party extension could call asobi_presence:send/2 directly, so nothing downstream should treat a successful emit/4 as proof of a privilege.

On success the event reaches the player's live sessions as a module.event wire frame (asobi_ws_handler). This is an Erlang-only seam: only an extension's own code calls it, and it has no Lua binding.

Returns {error, asobi_error:object()}, never a crash, for: an event name outside the charset/shape or over 64 bytes (event.invalid_name); a domain Extension does not own (event.unowned_domain); Data that is not JSON-encodable (event.invalid_data); or encoded Data at or over 64 KiB (event.payload_too_large). Validating encodability here - one extra encode off the per-tick hot path - is what keeps a bad term from reaching the socket and dropping every one of the player's sessions.

-spec error_codes() -> #{asobi_error:code() => {pos_integer(), binary()}}.

Every error code the installed extensions mint, as Code => {Status, Message}.

asobi_error reads this rather than resolving, so building an error object never triggers discovery and never raises: before resolve/0 has run there are no extension codes, and resolve/0 runs inside Nova's boot, long before any request can fail.

-spec is_webhook_path([binary()]) -> boolean().

Whether a request path (as normalised segments, trim_all) is served by a mounted security => webhook route.

Read by asobi_rate_limit_plugin to pick the webhook bucket, so like rpc_methods/0 it reads the memoised table and never triggers discovery. Before resolve/0 has run there are no webhook routes and no traffic.

-spec lua_bindings() -> [binding()].

Every game.<ns>.<fn> binding the installed extensions declare, flattened.

asobi_lua_api filters this by the VM kind it is installing into and installs what remains. Flat rather than nested because every consumer wants one pass over bindings, not a walk over namespaces.

-spec ops_action(binary(), binary()) -> asobi_extension:ops_entry() | undefined.

The operator action Extension declares as Action, or undefined.

Read on two request paths - the capability check in asobi_ops_caps and the dispatch in asobi_ops_extension - so like rpc_methods/0 it reads the memoised table and never triggers discovery. undefined for an extension that is not installed and for an action it does not declare, which is one answer because they are one outcome: nothing to route to, and nothing to authorise.

-spec resolve() -> [extension()].

The installed extensions, in dependency order. Memoised.

Raises {asobi_extensions, Problems} on an invalid set, after logging the same problems in prose. A node that cannot say which extension owns a namespace must not serve traffic under either.

-spec rpc_methods() -> #{asobi_extension:method() => mfa()}.

Every RPC method the installed extensions declare, as Method => {M, F, A}.

asobi_rpc reads this rather than resolving, for the same reason error_codes/0 exists: dispatch is on a request path and must never trigger discovery. Before resolve/0 has run the table is empty, and resolve/0 runs inside Nova's boot, long before a socket exists.

Methods cannot collide across extensions. A method's prefix is a derived rpc claim, and validate/1 refuses two extensions claiming one prefix, so flattening the declared maps together cannot lose an entry.

-spec sup_specs(module()) -> [supervisor:child_spec()].

The child specs an extension wants asobi to supervise.

Called from asobi_extension_child_sup:init/1 rather than cached, so the running code always decides.

-spec validate([extension()]) -> ok | {error, [problem(), ...]}.

Namespace disjointness across the declared set, and against core's reserved names.

The claim set per namespace is owns/0 plus what the extension's own code already implies, and every kind derives:

So two extensions installing the same game.quests, or the same job queue, collide before either has bothered with owns/0.

The http kind alone compares structurally rather than by token equality: two paths collide when the routing tree cannot serve both - some request matches both patterns, or the patterns diverge at a binding at any depth, in which case routing_tree's commit-to-first-sibling lookup lets one swallow requests meant for the other (see paths_collide/2). Its reserved set is every co-mounted app's route table - core's own via asobi_router:core_routes/0, plus nova's and every app in nova_apps, which is what keeps /health and its siblings unclaimable - and a claim under a privileged plane prefix (asobi_extension_reserved:route_prefixes/0) is refused outright, whatever it would resolve to.

Tables and queues derive through asobi_extension_reserved, the same rule that finds core's own tables and queues, so a name core reserves and a name an extension claims can never be found two different ways.

That leaves owns/0 doing one job, and it is worth stating because it is no longer the source of anything: it is the closed-set assertion over what was derived. Naming a kind at all says "this is the complete set", and anything derived outside it is undeclared_claim - which is what turns a typo in owns.queues from an invisible no-op into a build failure. Nothing in owns/0 is load-bearing for collision detection any more.

requires/0 is checked here too, against the union of core's subsystem names (asobi_extension_reserved:core_capabilities/0) and the installed extensions' own names. It reads Extensions in the order given, which is the resolver's dependency order, so the extension-ordering rule is a position check rather than a second sort.