[post-v3 DX] Align authorization namespaces with programmatic plugin IDs

[olliethedev]

Context

Follow-up from the retained RC3 application validation in better-stack-web#37 and its full report.

This is a post-v3 incremental DX improvement. It must not block or reopen v3.

Friction

RC3 correctly infers registered client plugin IDs and typed authorization facts, but the vocabulary changes between the two surfaces:

plugins: {
  formBuilder: formBuilderClientPlugin(),
}

rules: ({ forms }) => [
  forms.form.render.when(...),
]

formBuilder is the canonical programmatic plugin ID while forms is the authorization catalog namespace. The types are safe, but the relationship is not visible at either call site. During real migration, the only reliable way to discover it was to inspect the permission declaration .d.ts files and trace which catalog supplied each facts shape.

Most first-party names happen to align (blog, cms, comments, media), making the one mismatch look accidental even if the domain namespace is intentional.

Proposed better alternative

Use the canonical programmatic plugin ID as the default authorization namespace and add a compatibility alias in a minor release:

rules: ({ formBuilder }) => [
  formBuilder.form.render.when(...),
]

Preferred implementation:

1. Give each permission catalog explicit typed metadata for pluginId and authorizationNamespace.
2. Expose the catalog under pluginId by default in defineAuthorization.
3. Keep forms as a deprecated typed alias through the next major release so this is incremental and non-breaking.
4. Include hover documentation on the alias explaining its owning plugin and replacement.
5. Export a typed catalog-to-plugin map for tooling/docs rather than requiring source inspection.

If domain namespaces must remain distinct, the fallback should still make the mapping explicit in autocomplete and generated reference docs; silent naming divergence is the part to remove.

Acceptance criteria

• A developer can move from a registered plugin ID to its permission catalog without inspecting package internals.
• First-party catalogs expose typed pluginId/namespace metadata.
• formBuilder is available as the primary rule callback key.
• Existing forms code remains source-compatible and receives a deprecation hint.
• Catalog facts remain inferred per operation exactly as in RC3.
• Type tests cover canonical keys, compatibility aliases, and invalid cross-plugin facts.
• The migration/reference docs show the mapping once in a generated table.

Release boundary

Post-v3 enhancement only. Do not hold v3 publication or change RC3 package contracts for this issue.