-callback erase_player(PlayerId :: binary()) -> ok | {error, term()}.

Erase everything this extension holds about one player.

An extension foreign-keying into players.id must cascade or declare an erase path, and this is the erase path. Declare neither and installing the extension makes players undeletable: an undeclared on_delete lowers to no_action, so the first extension row for a player turns core's delete into a constraint violation.

Cascade is right for progress rows and wrong for a financial or audit row - the case that rejected a blanket cascade in the first place. An extension holding one exports this instead, and answers erasure in whatever way its own law requires: delete the rows, or null the player reference and keep the ledger. Core does not care which, only that the player row can then go.

Not an owns/0 key. owns/0 is a set of names, validated at build time and read by nothing at runtime; it reserves, it does not execute. Cascade is already declared where the database can enforce it - on_delete = cascade on the #kura_assoc, carried into the generated migration - and a second declaration of the same fact in the manifest could disagree with the schema that actually decides. So the two alternatives stay in the two places that enforce them: cascade on the column, erase here.

When it runs, and what a failure does

Core calls it inside its own transaction, before deleting any of its own rows, once per installed extension in dependency order. Do not open a transaction of your own.

Extensions before core, because an erase path may want to read what core still has (a player's stats, its identities) while writing its own summary row. Order between extensions is not load-bearing and is not promised beyond dependency order: extensions never foreign-key each other, only core.

Erasure is atomic across every extension, not best-effort with a report. Returning {error, Reason} or raising aborts the whole deletion: no extension's rows go, core's rows stay, the player survives, and one logged line names the extension and the reason. The alternative was considered and rejected. A best-effort erasure ends with the account gone and some extension's rows orphaned, or the reverse, and nothing durable saying which - a half-finished erasure that reports success is a worse answer to a data-subject request than one that fails loudly and can be retried. Every extension shares asobi_repo, so the single transaction that makes this true costs nothing to arrange.

The corollary is that an erase path doing work the transaction cannot undo - deleting a remote object, calling a third party - must be idempotent, because a later extension's failure will roll back everything around it and the whole deletion will be retried.

Idempotence is not reversibility, and the difference is the one hole in this contract. Extensions run first, so by the time a later extension refuses, or core's own audit insert fails, a remote delete has already happened and no rollback reaches it. The reachable end state is a player who still exists and whose remote data does not - and because a rolled-back attempt writes no audit row, nothing durable records that it happened. Ordering does not fix it: order between extensions is not promised, and core's audit insert follows all of them.

If you hold data outside this database, write the intent to erase it as a row in your own tables inside the transaction, and let a shigoto worker perform the remote call once that row has committed. Then the rollback takes the intent with it, and the irreversible step only ever runs after the erasure is final.

Core deletes a player in exactly one place, asobi_player_erase, so that is where this runs. asobi_guest_reaper is one caller of it and the ops route POST /api/v1/ops/players/:id/erase is another; both reach this callback through the same function, in the same position, under the same transaction. (asobi_guest_controller also deletes, but only a player row it inserted microseconds earlier and lost a race on, which no extension has been told about yet.) asobi_extension_erase is the seam.

Core's own foreign keys are all no_action and its erasure enumerates its children in code. A blanket ON DELETE CASCADE across core would fire below the transaction's control flow, so this callback would never run - which is the same reason the guide gives an extension author for not reaching for one.

-callback export_player(PlayerId :: binary()) -> {ok, #{binary() => term()}} | {error, term()}.

Export everything this extension holds about one player, keyed by the extension's own section names - mirroring core's per-table sections.

The read half of erase_player/1, and optional for a different reason. Erasure has a physical forcing function: skip it and the foreign key blocks the delete. An export callback has none, so for a long time there was deliberately no contract here - an extension that skipped it would have produced a silently incomplete export and nothing would have failed. What made one shippable is that the artefact itself now forces the answer: core's export names every installed extension, and one without this callback appears under a skipped marker rather than being silently absent, so a data subject or auditor can see exactly which extensions contributed and which did not.

Apply the same projection rule core does: positive allowlists via maps:with/2, never subtractive filters - an extension carrying a token or secret column is one schema field away from exporting it otherwise. And every row you return must be one this player owns - core cannot check that for you. Where one column holds several players' data, lift out this player's part rather than exporting the column whole, the way core exports only the requester's own choice from votes.votes_cast.

A missing callback is a marker; a failing one fails the export. Returning {error, Reason} or raising means data was promised and not delivered, which is exactly the silent incompleteness the marker exists to prevent, so the whole export fails and no artefact is produced. The sections must be JSON-encodable - the export is served as one JSON object, so a section json:encode/1 refuses fails the export the same way, attributed to this extension rather than surfacing as an unattributed 500 after the payload left the controller. There is no transaction: the export is a sequence of plain reads, and this runs in the same untransacted pass, after core's own sections. asobi_extension_export is the seam.

-callback requires() -> [name()].

The subsystems and extensions this extension calls, by name.

A bare list of names - core subsystems (economy, leaderboards, world, ...) and other installed extensions - never version ranges. Which versions are compatible is the dependency pin's job ({asobi, "~> 0.83.0"}, and the bundle's lockstep for a first-party set); this list says only that you call into a thing, never which of it. requires => [economy] says "I call into economy" and nothing about which economy.

Two things read it, and both run the same asobi_extensions:check/0:

• Refusal. rebar3 asobi check and the boot backstop reject a set where a required name resolves to nothing - neither a core subsystem nor an installed extension. A missing dependency is a build failure naming the extension and the name, not an undef the first time a client reaches the moved code.
• Boot order. A requirement on another extension must be backed by an OTP application dependency, so the resolver already lists the provider first (sup/0's start-order guarantee); a requirement whose provider is not ordered before it is refused, because boot would otherwise start them out of order. A requirement on an always-present core subsystem imposes no order.

The resolution set is the union of core's subsystem names and the installed extensions' names, and that union is what keeps requires/0 correct across an extraction: when a core subsystem later ships as its own package the name simply moves from the core side of the union to the extension side, and a requires on it stays satisfied - the bundle installs the package. This is the seam the Wave 3 tournaments->leaderboards dependency rides.

-callback routes() -> [route()].

The HTTP routes this extension serves. Core's router mounts them at boot; extensions never mount anything themselves.

This exists to preserve extracted REST surfaces and to receive server-to-server webhooks. A new client-facing feature should use rpc/0 instead: one rpc(method, params) symbol reaches every SDK with zero per-extension SDK work, while a new REST route has no SDK surface at all. That is a listing guideline, not a mechanical ban - "it is a webhook" is an accepted answer.

Every declared path is a derived http claim, validated like tables, rpc, lua and queues - but the comparison is structural rather than token equality: two paths collide when the routing tree cannot serve both, so /saves/:slot and /saves/:id are one claim, a literal sitting under another table's binding is caught, and so is a pattern that diverges from an existing route at a binding at any depth - the shape that lets one route swallow another's lookups. A collision with another extension, with a path any co-mounted application serves (core's own table, Nova's, nova_apps such as nova_resilience's /health), or with a privileged plane prefix (/api/v1/ops, /api/v1/auth, /api/v1/iap, /console, /ws) refuses boot; a declared route can never be silently shadowed first-compiled-wins.

An unmounted route - the extension absent, the path never declared - is absent from the table: 404, indistinguishable at the path level from a path that never meant anything. This discipline is path-level only: a mounted path answers a wrong-method request with 405 and an allow header, as every core route does, so which methods a declared path serves is enumerable. That trade is accepted - method behaviour follows HTTP rather than hiding.