API design: separate command, query, job, and authority semantics

[devallibus]

Summary

#[webtau::command] is a strong local-runtime abstraction, but it risks becoming muddy if it is stretched to cover read-only queries, async heavy jobs, and shared/meta authority semantics without a clearer model.

Why this matters

• Local in-process state mutation and remote/shared authority do not have the same semantics.
• A cleaner split will make metadata, generated clients, and validation tooling easier to build.
• Avoiding semantic overload now is cheaper than untangling it later.

Suggested scope

• Write an API design note that distinguishes at least these execution classes:
  • local command
  • query/view
  • async job
  • shared/meta authority
• Decide whether these should be separate attributes, generated layers, or a more structured target model.
• Prototype the smallest viable path rather than over-designing the full matrix.

Acceptance criteria

• The project has a documented opinion on how these semantics differ.
• The design avoids pretending that local &mut State calls and remote/shared reducers are the same thing.
• The chosen model supports typed metadata and generated clients cleanly.
• There is a migration or coexistence story for the current #[webtau::command] surface.

Related

• Brainstorming: evolve gametau from runtime portability to execution-topology portability #154
• webtau: add runtime info / capability introspection API #129
• Macros/tooling: emit command metadata and optional typed clients from webtau commands #139