[atomiechen]

Why

Outgoing event validation previously knew only an event name and payload type. It could not describe a stable namespace or acknowledgement type, so runtime behavior and generated protocol descriptions had no shared, complete operation contract.

Changes

• Record local send and receive contracts by namespace, event, direction, payload, and declared ACK type.
• Add optional keyword-only namespace and ack_type to register_emit(). An unscoped registration retains its previous event-wide behavior; a scoped registration overrides it only in that namespace. ack_type is declarative and does not change call(response_model=...) validation.
• Add pydantic_socketio.asyncapi_schema(sio, *, title, version) to project those registrations into AsyncAPI 3.1. Socket.IO-specific event, role, namespace fallback, and ACK semantics live under x-pydantic-socketio.
• Remove the never-implemented schema() placeholder, which had only returned None and had no documented use. This is technically an API removal, with no working behavior to migrate.
• Keep lifecycle and catch-all handlers explicitly listed as omitted instead of representing them as concrete business events.

Verification

• Pytest: 63 passed on each Python 3.8–3.13; 63 passed with both python-socketio==5.12.1 and ==5.17.0.
• Ruff and Pyright pass. Tests cover all four server/client variants, monkey patching, namespace fallback/override, ACK shapes, real Socket.IO round-trip, and deterministic export keys.
• A document generated from real registrations passes the official AsyncAPI 3.1 JSON Schema and parser with zero diagnostics.
• The official AsyncAPI HTML template renders the generated document. A schema-only probe recovered the matching client emit/on operations, namespaces, payload examples, and ACK shapes.

Product boundary

The schema is useful for documentation and machine-readable contracts. Generic tooling currently renders multi-argument payloads as arrays and does not provide a ready-made Socket.IO client SDK from AsyncAPI 3.1. This PR does not add a generator, runtime dependency, wrapper, DI system, or documentation server.