feat(extensions): the extension machinery - behaviour, registry, supervision, build gate

[Taure]

Wave 3 of the extension architecture: the machinery an extension plugs into.
No extension exists yet (asobi_quests is Wave 4), so everything here is
exercised by fixture extensions under test/extensions/, and the whole thing
is inert when nothing is installed.

Built against asobi-ecosystem/docs/design/extension-architecture.md and ADRs
0002-0005.

What is here

asobi_extension - the behaviour. info/0 is required; rpc/0, lua/0,
sup/0 and owns/0 are -optional_callbacks defaulting to empty, because
several are frequently empty and owns/0 earns nothing until a second
extension exists.

asobi_extensions:resolve/0 - a pure memoised function over
persistent_term. Not a process, not a supervised child, not a step in a boot
sequence.

I verified the boot-order claim rather than taking it on trust:
nova_sup:init/1 calls setup_cowboy/1 -> start_cowboy/1 ->
nova_router:compile(...), all inside init/1
(_build/default/lib/nova/src/nova_sup.erl:82 and :145-152), and nova is
in asobi's applications list, so the whole route table compiles before
asobi_app:start/2 runs. The first caller is asobi_router:routes/1, at
which point no asobi process exists. It holds.

Ordering falls out of discovery rather than being applied afterwards: the
closure walk is post-order, so each application is emitted after everything it
depends on, which is OTP's own start order, with ties in the host's
declaration order. Nothing sorts it afterwards.

asobi_extension_sup + asobi_extension_child_sup - one
sub-supervisor per extension with its own restart budget (5 in 60 by default,
{extension_restart, #{intensity, period}} in app env).

Restart strategy, since you asked for the justification:

• one_for_one at both levels. Extensions are independent by construction;
  one restarting is never a reason to restart another.
• The sub-supervisor is transient, not permanent. A supervisor that
  exceeds its intensity exits shutdown, which a transient child is not
  restarted for. So an extension that has burned its own budget goes dark and
  stays dark, attributed by name. Restarting it would relay the same crash
  loop upwards until it reached asobi_sup (10 in 60, over eighteen children
  including the matchmaker and every live match) and took the node with it -
  the exact outcome this tree exists to prevent. Transient rather than
  temporary because a sub-supervisor killed for some other abnormal reason
  is a core-side fault, not an extension giving up.
• Intensity 3 in 60 at the top level. Extension failures never consume it,
  because a transient child exiting shutdown is not a restart. The budget
  covers asobi_extension_watch only, so nothing an extension does can
  exhaust it.

asobi_extension_watch - monitors the sub-supervisors and logs
extension_down with the extension's name, so "a feature stopped working and
nothing said so" is not a possible outcome. asobi_extension_sup:running/0
answers the same question on demand.

Namespace disjointness - owns/0 plus what the manifest already
implies: the prefixes in rpc/0 and the namespaces in lua/0. So two
extensions installing the same game.quests collide even before either has
bothered with owns/0. A conflict names both claimants by application name,
which is the thing a host edits.

Core's reserved list is derived from core rather than restated, so it cannot
drift:

• lua from asobi_lua_surface:reserved_namespaces/0 - the S7 list, plus
  game itself.
• tables from every core kura_schema module's table/0, found the same
  way asobi finds an extension's schemas.
• queues from every core shigoto_worker module's queue/0.
• rpc from the domains of asobi_error:codes/0, plus the Lua namespaces.
  An RPC prefix and an error-code domain are the same token by construction
  ({"code": "quests.name_taken"}), so an extension owning storage would
  mint codes inside core's closed code set.

rebar3 asobi check - the primary gate, running the same
asobi_extensions:check/0 the boot backstop runs, so the two cannot disagree.
Verified end to end against a scratch host project:

===> asobi: 3 extension(s), in migration order
===>   clans (game_clans, contract v1): 1 rpc method(s), 1 lua namespace(s)
===>   quests (game_quests, contract v1): 1 rpc method(s), 1 lua namespace(s)
===>   solo (game_solo, contract v1): 0 rpc method(s), 0 lua namespace(s)
===> asobi: game_solo declares neither rpc/0 nor lua/0, so nothing can call it

and on a collision, exit 1:

===> asobi: game_clans and game_quests both claim the table "quests". Namespaces are exclusive; rename one.
===> asobi: game_clans and game_quests both claim the RPC prefix "quests". ...
===> asobi: game_clans and game_quests both claim the Lua namespace "quests". ...

It also runs supervisor:check_childspecs/1 over sup/0, so a malformed child
spec is a build-time line naming the extension rather than a
failed_to_start_child out of Nova's boot.

asobi_readiness - the 503 not_ready seam. The route table compiles
during Nova's boot; kura_migrator:migrate/1 runs later, from
asobi_app:start/2, so an extension endpoint is reachable before its tables
exist. asobi_readiness:guard/0 returns ok or the error object, and
asobi_app:start/2 marks ready only on a successful migration. The RPC
dispatcher is Wave 2b and is not built here - guard/0 and its tests are,
so the dispatcher inherits a readiness contract rather than inventing one.

asobi_repo:migration_apps/0 - inert seam for kura's multi-application
migration discovery.

Inertness

With nothing installed: resolve/0 returns [] without computing the
reserved list at all, asobi_extension_sup is one idle supervisor with zero
children, no timers and no tables, and nothing sits on any request path. The
only always-on cost is one closure walk at boot, memoised.

All 1319 eunit tests pass, including the 1285 that predate this branch.

Design deviations

Three places where the document and reality disagreed.

1. kura 2.20 is published. The brief said 2.20.0 was not on Hex; it is -
   2.20.1, with migration_apps/0 as a documented optional kura_repo
   callback. I read the real implementation
   (kura_migrator:resolve_migration_apps/2) and found that kura adds the
   repo's own application itself and topologically sorts the result, so a
   callback returning [asobi | Extensions] restates an ordering kura already
   derives. asobi_repo:migration_apps/0 therefore returns the extensions
   only. I did not move the pin: ~> 2.17 to ~> 2.20 is a three-minor
   upgrade of the ORM under every core migration and deserves its own PR with a
   real-Postgres migration run. When that pin moves, this is the entire change

   • extension migrations then run inside core's transaction, under one
     advisory lock, in dependency order. Nothing else here changes.

2. rebar3 asobi check ships inside asobi, not as a rebar3_asobi
   package. The design points at rebar3_kura's structure, which is a separate
   repo depending on kura. Duplicating the validator there would break the
   ADR's requirement that build time and boot validate identically, so the
   provider lives in src/extensions/ and is declared to rebar3 through
   {env, [{providers, [rebar3_asobi_check]}]} in asobi.app.src - I
   confirmed empirically that rebar3 reads that key before falling back to a
   module named after the application, so the provider module needs no special
   name. The cost is real and should be said plainly: a host adding asobi to
   project_plugins builds asobi's whole dependency tree a second time under
   _build/default/plugins. Extracting a slim rebar3_asobi that depends on
   asobi is the follow-up if that cost bites. This also required two
   concessions in rebar.config: xref_ignores for rebar3's own API and
   {exclude_mods, [rebar3_asobi_check]} for dialyzer, both scoped to that one
   module.

3. rpc/0 and lua/0 are optional callbacks, though the design says
   "neither is optional". That sentence is about the design providing both
   consumption paths, not about the callback list; a half-written extension
   with neither is a legal state and failing the build on it would be hostile.
   rebar3 asobi check warns instead, naming the application and why
   nothing can call it. If the intent was a hard failure, say so and it is a
   one-line change.

Two smaller judgement calls worth flagging:

• asobi_extension_reserved raises if core's module list is unreadable
  rather than returning an empty reserved set. An empty set silently reserves
  nothing, which would let an extension claim players and pass the check.
  Fail closed and loud.
• asobi_router:routes/1 now calls resolve/0. Extensions contribute no
  routes; the call is there because the router is the earliest possible
  validation point, which is the whole reason resolve/0 has the shape it
  does.

Tests

34 new tests, all verified to fail when the implementation is reverted:

Reverted	Failing tests
validate/1 never reports	11
manifest shape checks never report	3
pre-order closure instead of post-order	1 (dependency_order_beats_alphabetical_order)
memoisation removed	1
manifest matched by _extension suffix only	1
no try/catch around manifest calls	1
a manifest's own claims not deduped	4
sup_specs/1 always empty	2
sub-supervisor permanent instead of transient	1 (a_spent_extension_goes_dark_alone)
asobi_extension_watch removed	1
readiness always open	2
reserved Lua list emptied	1
migration seam ignores extensions	1

Two assertions carry their weight only because of how the fixtures are
arranged, so they are worth stating: asobi_fixture_clans sorts before
asobi_fixture_quests alphabetically but depends on it, so the ordering test
distinguishes dependency order from a sort; and the "an app in asobi's closure
is not an extension" fixture carries a perfectly valid manifest module
belonging to a different application, so it would pass a suffix match and
fails only the name match.

asobi_sup_lua_children_tests:lua_children_start_last_test was pinning the
Lua children as the final two entries. Extensions start after them, so it is
now lua_children_start_after_core_and_before_extensions_test and pins the
exact three-entry tail instead - the same guard, restated.

Not built

• The RPC dispatcher (Wave 2b, explicitly out of scope). Only the readiness
  seam it will call.
• The Lua injector. The design's sequence lists it alongside
  asobi_extension_sup in step 3, but it was not in the brief's list and it
  means editing asobi_lua_api:install/2, the probe-VM pick/3 path and the
  namespace pre-creation order. lua/0 is fully validated here - shape,
  effects, VM kinds, disjointness, reserved names - so the injector consumes a
  checked declaration. It is the obvious next PR and it is not a one-liner.
• Moving the kura pin (see deviation 1).
• asobi_bundle.

Checks

rebar3 fmt --check, xref, dialyzer, ex_doc (zero warnings), full
eunit (1319 tests, 0 failures), and ct for asobi_api_SUITE and
asobi_lua_SUITE against the shared Postgres. Rebased onto main after #356
landed; the only conflict was one line in asobi_error's code table.

[github-actions]

🟡 Code Coverage — 73.8%

6042 of 8187 lines covered.