emitEvents for Python (FastAPI + SQLAlchemy): generate a transactional domain-event spine

[cultron]

Summary

Extend the opt-in emitEvents capability (added for TypeScript in #79 / PR #80) to the Python (FastAPI + SQLAlchemy) generator, so that opted-in entities produce a durable domain-event spine written in the same transaction as the state change.

Today emitEvents is parsed and honored only by the TypeScript generator; the Python generator inherits the base no-op (generateDomainEvents returns []), so emitEvents is silently ignored for Python projects.

Reference

#79 / PR #80 is the reference spec. The TypeScript implementation generates (into autogen/events/): a DomainEvent entity (events table), an EntitySubscriber writing events transactionally, an app-overridable DomainEventMapper (event-type taxonomy + payload), a DomainEventRelay (drain/retry; publish() is the app-supplied delivery hook), and a @Global() module wired into the index barrel. Flag resolution is entity.emitEvents ?? <top-level emitEvents> ?? false (global default with per-entity opt-out). Keep the same naming and the same extension-point boundaries.

Language-specific mechanism

The durability lever is ORM-specific. For SQLAlchemy:

• Use session events (e.g. before_flush, or SessionEvents) to write the event row into the same session / unit of work as the state change, so it commits atomically. (after_commit is NOT transactional — avoid it for the durable write.)
• Map SQLAlchemy ORM insert/update/delete to created/updated/removed.
• Recursion guard: never emit for the DomainEvent model itself.
• Scope emission to the opted-in entities only.
• Provide the mapper + relay as overridable extension points (delivery left to the app); a DomainEvent model + events table; relay drains pending rows.

Scope / notes

• Mirror the TS resolution helper and opt-out semantics.
• Document that bulk/Core-level (non-ORM) statements bypass session ORM events (analogous to the raw-QueryBuilder caveat in Feature: opt-in emitEvents per entity — generate a transactional outbox + lifecycle EntitySubscriber #79).
• Consider whether Python codegen hardening should land first (Python generation is still maturing).
• Add generator tests mirroring the TS domain-events suite.

Environment

• @apso/cli — language: python (FastAPI + SQLAlchemy)
• Related: Feature: opt-in emitEvents per entity — generate a transactional outbox + lifecycle EntitySubscriber #79, PR feat: opt-in emitEvents — generate a transactional DomainEvent spine (#79) #80 (TypeScript implementation / reference spec)