feat(fal): declare endpoint billing components in deploy metadata

[dimi-fal]

Lets an endpoint declare the billable components it reports, so they can be published with the deployed revision without overriding build_metadata in every app.

class MyApp(fal.App):
    @fal.endpoint("/edit", billing=EDIT_BILLING)
    async def edit(self, input: EditInput) -> EditOutput: ...

Changes

• billing= on fal.endpoint takes any object (not a class) with a declaration() method.

• fal.BillingComponents (the TypedDict published per endpoint) and fal.BillingDeclaration (the protocol) are exported, so a declaration can be typed and mypy checks its version, schema_id and app:

  class Schema:
      def declaration(self) -> fal.BillingComponents: ...

• App.build_metadata() publishes the declarations under metadata["billing_components"][path], separately from the OpenAPI spec. Apps without billing declarations publish exactly what they did before.

• App.get_billing_components() returns the declarations per path.

• Each declaration is checked before publishing: exactly version (1), schema_id and an object JSON Schema app, and it must survive a JSON round trip unchanged. Deploy metadata travels as a protobuf Struct and then JSONB, so Decimal, sets, NaN and infinity are refused, as are tuples and non-string keys, which JSON would silently change. The schema's detailed shape and vocabulary (metrics, dimension values) are not checked here: the registry builds them, and the platform validates them when a revision is registered.

• WMA apps (fal.wma.App) build their metadata from App.build_metadata(), so their declarations are published too; asyncapi is rendered from that same OpenAPI document, with one app instance.

• Request handling and the OpenAPI spec are unchanged. billing= is rejected on websocket endpoints: they have no response headers to report components through. Session and websocket billing is tracked in BIL-676.

Validation

• New tests/unit/test_billing_declarations.py plus test_app.py, test_request_validation_errors.py and the WMA contract, example and SDK tests: 315 passed, including the six serialization cases. The registry's real declarations (xai-tts, the estimator tests) pass the check.
• A WMA example app builds one instance for build_metadata, and its published asyncapi equals asyncapi().
• tests/unit/wma: 554 passed. TestAioiceOrderlyTeardown::test_stock_close_emits_the_retry_race fails only when run with the whole suite (order-dependent); it passes alone and within its file.
• Ruff format/lint passed via pre-commit. The pre-commit mypy hook failed to start locally (typed_ast environment issue), so the pinned mypy 1.3.0 was run with the hook's arguments: no errors in the changed files. A typed caller returning fal.BillingComponents passes, and a wrong version is reported.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes deploy metadata shape and decorator validation, but request paths and OpenAPI stay unchanged; bad declarations fail at metadata build time rather than at runtime billing.

Overview
Endpoints can now declare billable component schemas via a new billing= argument on fal.endpoint, without touching OpenAPI or per-app build_metadata overrides.

Declarations are objects with a declaration() method returning fal.BillingComponents (version, schema_id, object JSON Schema app). App.build_metadata() adds billing_components keyed by path when any endpoint declares billing; apps without billing behave as before. check_declaration rejects malformed or non–JSON-round-trip-safe payloads before publish. Websocket routes cannot use billing=; the declaration lives on the endpoint function, not the hashed route signature.

fal.wma.App now builds metadata through super().build_metadata() (so WMA apps pick up billing too) and renders AsyncAPI from the same OpenAPI document via _render_asyncapi. BillingComponents and BillingDeclaration are exported from fal.

Unit tests cover metadata shape, OpenAPI stability, validation edge cases, and WMA integration.

^{Reviewed by Cursor Bugbot for commit aae74a6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[linear-code]

BIL-530

BIL-671

[cursor]

Stale Bugbot comment from a previous run.

[claude]

Findings marked 🟡 are optional suggestions and need no follow-up push.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b46cbe2. Configure here.}

[Gothos]

I approve the metadata changes in general. I do feel a stricter check for serialization on the metadata might be better (it just checks that is an object at the moment).