ekbatan 0.1.0__tar.gz

ekbatan-0.1.0/.agents/skills/ekbatan-py-examples/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: ekbatan-py-examples
+description: Maintain the ekbatan-py example applications. Use when adding, updating, auditing or verifying anything under ekbatan-py-examples across the PostgreSQL, MySQL, MariaDB, sharded, saga, job-worker and SQLite examples and their async twins, each built with uv, pip and Poetry.
+---
+
+# ekbatan-py examples
+
+Use this when a change affects an example application, its docs, its wiring, or consistency
+across the matrix.
+
+## First reads
+
+- `ekbatan-py-examples/README.md`.
+- The closest existing example for the same dialect.
+- `references/example-matrix.md`.
+- `docs/wiring.md` and `docs/wiring-fastapi.md`.
+
+## Matrix discipline
+
+Fourteen examples, **each carried three times** - `-uv-`, `-pip-`, `-poetry-` - as Java carries its
+examples per Gradle and Maven: 42 projects. Only the REST example is replicated per database, and
+every example has an async twin.
+
+| | |
+| --- | --- |
+| per database | `fastapi-wallet-rest-{build}-pg`, `-mysql`, `-mariadb` |
+| per database, async | `fastapi-wallet-rest-{build}-async-pg`, `-async-mysql`, `-async-mariadb`, `wallet-service-{build}-async-sqlite` |
+| one of a kind | `fastapi-wallet-rest-{build}-sharded-pg`, `fastapi-wallet-saga-{build}-pg`, `job-worker-{build}-pg`, `wallet-service-{build}-sqlite` |
+| one of a kind, async | `fastapi-wallet-rest-{build}-async-sharded-pg`, `fastapi-wallet-saga-{build}-async-pg`, `job-worker-{build}-async-pg` |
+
+**Two modes.** Every example has an async twin on `ekbatan.aio`, with the same tests plus a
+check that it really runs async (its drivers, its loop). The complete-project-setup page shows
+both for each database, and `scripts/check-setup-guide.py` builds both. A change to a sync
+example's behaviour goes into its async twin too, or the twin's README says why not; a new
+example gets an async twin. In the job worker's twin the jobs stay sync (every distributed job
+is) and their work runs on a `HandlerLoop` with `loop.run(...)`.
+
+**Edit only the uv project**, then run `uv run python scripts/sync-examples.py`: it writes the
+pip and Poetry twins (the same `src/`, byte for byte) and every project's `pyproject.toml`,
+`Makefile`, `.gitignore` and README build section. Never hand-edit a twin - `make lint` runs
+`sync-examples.py --check` and fails on any drift. When changing a base wallet behaviour, change
+all three REST databases' uv projects; those are not generated from one another.
+
+## An example is documentation
+
+- **mypy `--strict` runs over the examples' uv projects** (their twins are the same code),
+  because documentation that would not type-check is documentation that is wrong.
+- They import only the framework, the standard library and what each project's `pyproject.toml`
+  declares. `tests/test_structure.py` enforces it.
+- They are **not** shared with `tests/fixtures/`. The suite's domain exists to exercise every
+  shape worth exercising; an example exists to show what good code looks like. Coupled, every
+  coverage change lands in the documentation.
+- A claim in an example's README must be backed by its source. An example nobody runs rots -
+  and one did, silently, because this repository had no remote and CI had never executed.
+
+## Conventions
+
+- Actions are named exactly as Java names them: `WalletCreateAction`, `WalletDepositMoneyAction`, `WalletCloseAction`, `CreateNotificationAction`, `InitiateTransferAction` - no word-order rule, Java mixes model-first and verb-first. Each action's parameters are its nested `Params`.
+  Events are `WalletCreatedEvent`, `WalletMoneyDepositedEvent` - past tense, `Event` suffix. Handlers
+  end `EventHandler`, jobs end `Job`.
+- In a sync example, endpoints are plain `def`, never `async def`. FastAPI runs a plain `def` in
+  a threadpool; an `async def` calling into the synchronous framework blocks the whole event
+  loop. In an async twin every endpoint is `async def` and awaits `ekbatan.aio`.
+- Three pools per member - requests, jobs, locks - and the jobs pool is at least twice the worker
+  count.
+- A keyed lock lease must span `executor.execute(...)`, not just the read.
+- Generated `schema.py` is gitignored. Never commit one, and never edit one.
+- Forced types are set in `scripts/sync-examples.py` (`WALLET_FORCED`, `SAGA_FORCED`), which
+  writes every `pyproject.toml`; see `references/example-matrix.md#forced-types`. A converter's
+  module must not import `schema.py` - schemagen imports it before `schema.py` exists.
+
+- **UTC everywhere**, the framework's strong recommendation: an example takes time from the clock
+  (`self.clock.instant()`, `clock.instant()`), never `datetime.now()`; its migrations use `TIMESTAMP` (PostgreSQL)
+  or `DATETIME(6)` (MySQL, MariaDB), never `TIMESTAMPTZ`; its database runs in UTC. See
+  `docs/database/multi-database.md#always-utc`.
+- **Every model and entity defines `validate()`**: `Wallet.validate()` has `pass` with a one-line
+  reason (nothing beyond its types, as Java's constructor checks only for null),
+  `Notification.validate()` refuses a blank recipient or message, `TransferStep` has `pass`.
+- **Time kinds**: an event's time field is declared `Instant` (or `LocalDateTime` /
+  `OffsetDateTime`) from `ekbatan.time` - a plain `datetime` field is refused when the action
+  runs. The examples' events carry no time field, as Java's do not.
+- **Repository variables** are Java's field names in snake_case - `wallet_repository`,
+  `notification_repository`, never `wallets` - and so are the other wiring objects:
+  `database_registry`, `lock_provider`, `job_registry`.
+
+## Workflow
+
+1. `ls ekbatan-py-examples` to see the matrix.
+2. Read a known-good uv project for the dialect family before editing.
+3. Make the smallest mechanical cross-matrix edit possible, in the uv projects.
+4. `uv run python scripts/sync-examples.py` to carry it to the pip and Poetry twins.
+5. `make examples` - every project builds its wheel and tests it installed, so a file a build
+   tool leaves out fails here. Needs Docker, `poetry` on the path, and a Python 3.13+ (found
+   through uv).
+
+Use `ekbatan-py-verification` for the full matrix.

ekbatan-0.1.0/.agents/skills/ekbatan-py-examples/references/example-matrix.md

@@ -0,0 +1,86 @@
+# Example matrix
+
+Fourteen examples, each built three ways - with uv, pip and Poetry - so 42 projects:
+`<stack>-<domain>-<style>-<build>[-variant]-<db>`, Java's own naming. Only the REST example is
+replicated per database, the same shape the Java port uses. Each follows the matching Java
+example piece for piece - model, actions, handler, jobs, endpoints, test cases - under Java's
+names; the REST examples and the job worker run two shards (global, Mexico) on two servers, as
+Java's do, the saga one database.
+
+| example (`{build}` = uv, pip, poetry) | dialect | shows | generates a schema |
+| --- | --- | --- | :---: |
+| `fastapi-wallet-rest-{build}-pg` | PostgreSQL x2 | the reference REST service, two shards | yes |
+| `fastapi-wallet-rest-{build}-mysql` | MySQL x2 | the same service, one dialect over | yes |
+| `fastapi-wallet-rest-{build}-mariadb` | MariaDB x2 | the same service again | yes |
+| `fastapi-wallet-rest-{build}-sharded-pg` | PostgreSQL x2 | the same code as `-pg`, as Java's sharded example is; its test follows a Mexican wallet | yes |
+| `fastapi-wallet-saga-{build}-pg` | PostgreSQL | choreography, compensation, and a 202 | yes |
+| `job-worker-{build}-pg` | PostgreSQL x2 | cluster-exclusive jobs, no HTTP at all | yes |
+| `wallet-service-{build}-sqlite` | SQLite x2 | the REST pieces run by a script. No container, no web stack | no |
+| `fastapi-wallet-rest-{build}-async-pg` | PostgreSQL x2 | the REST service on `ekbatan.aio` (asyncpg) | yes |
+| `fastapi-wallet-rest-{build}-async-mysql` | MySQL x2 | the same, on aiomysql | yes |
+| `fastapi-wallet-rest-{build}-async-mariadb` | MariaDB x2 | the same, on aiomysql | yes |
+| `wallet-service-{build}-async-sqlite` | SQLite x2 | the SQLite one on `ekbatan.aio` (aiosqlite) | no |
+| `fastapi-wallet-rest-{build}-async-sharded-pg` | PostgreSQL x2 | the sharded one on `ekbatan.aio` | yes |
+| `fastapi-wallet-saga-{build}-async-pg` | PostgreSQL | the saga, its later steps run by `async def` handlers on the handler loop | yes |
+| `job-worker-{build}-async-pg` | PostgreSQL x2 | the job worker, its jobs' work run on a worker loop (`HandlerLoop`), awaited | yes |
+
+Only the job worker has jobs of its own (`WalletStipendJob`, `WalletReportJob`), as in Java; the
+REST, saga and SQLite examples run just the fan-out and handling jobs.
+
+The uv project is the source; `scripts/sync-examples.py` writes the other two from it.
+
+## What each carries
+
+Every project is standalone - `cd` into it and `make` works, the way each Java example carries
+its own Gradle wrapper.
+
+```
+pyproject.toml    the build: uv_build, setuptools or poetry-core - and where ekbatan comes from;
+                  [tool.ekbatan.schemagen]: migrations, out, image, and its forced types
+Makefile          env, schema (bare `python -m ekbatan.schemagen`), test (the wheel, installed), run, clean
+.gitignore        the environment, the wheel, the generated schema.py
+README.md         what this example shows, and what to look at first
+src/<package>/    the package - the same name, and the same files, in all three builds:
+  app.py            the wiring, all of it in one place
+  api.py            the HTTP layer, and nothing else
+  model.py          the domain, with the small value classes the forced types read into
+  converters.py     the converters the forced types name; imports model.py, never schema.py
+  actions.py        the units of work
+  repository.py     the queries this application actually asks
+  handlers.py       the in-process event handlers
+  jobs.py           the distributed jobs (the job worker only)
+  ekbatan.yaml      the settings, read at startup
+  migrations/       V<version>__<desc>.sql files - migrated at startup, and the input to schemagen
+  schema.py         GENERATED, gitignored. Never commit or edit
+```
+
+The SQLite examples are the exception: a hand-written `schema.py`, committed. They have no
+migrations - `create_all` builds the tables from that file - so there is nothing for schemagen to
+read; their `schema.py` wraps the currency column in `CurrencyConverter` by hand.
+
+## Forced types
+
+Every generating example reads `CHAR(3)` columns as the app's own `Currency`, picked by type;
+the saga also reads its step column as an enum, picked by name:
+
+| example | by type (`include-types`) | by name (`include-expression`) |
+| --- | --- | --- |
+| REST (pg, mysql, mariadb, sharded-pg, and their async twins), job worker (both) | `CHAR\(3\)` -> `Currency` | - |
+| saga (both) | `CHAR\(3\)` -> `Currency` | `transfer_steps\.step` -> `TransferStepName` |
+
+The rules live in `scripts/sync-examples.py` (`Forced`, `WALLET_FORCED`, `SAGA_FORCED`), which
+writes every `pyproject.toml` - an edit to a project's own file is overwritten. Action parameters
+and events keep the plain text (`"currency": "EUR"`), because they are outbox JSON; the
+`state` columns are never converted, because the framework reads them as text.
+
+## The axes that do not exist here
+
+Java's matrix is 41 projects because it multiplies stack x build tool x dialect x runtime.
+Two of those axes collapse:
+
+- **stack** - there is no Spring/Quarkus/Micronaut split. FastAPI, or wire it yourself.
+- **runtime** - no native image. CPython has no counterpart.
+
+The **build tool** axis is kept: it decides what a wheel holds (Poetry drops a gitignored
+`schema.py`, setuptools drops the migrations and `ekbatan.yaml`), which only a built, installed
+wheel shows. The dialect axis is mirrored exactly, plus the four special cases.

ekbatan-0.1.0/.agents/skills/ekbatan-py-maintainer/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: ekbatan-py-maintainer
+description: Maintain and evolve the ekbatan-py persistence and action framework. Use for implementing or reviewing changes to the core, repositories, actions, outbox behaviour, sharding, keyed locks, distributed jobs, migrations, schemagen, docs that describe framework semantics, or release-facing library behaviour.
+---
+
+# ekbatan-py maintainer
+
+Use this when modifying the framework itself, not an application that depends on it.
+
+## First reads
+
+- `AGENTS.md` - architecture, conventions and the durable rules.
+- `DIVERGENCE.md` before "fixing" something that looks wrong. It may be deliberate.
+- `docs/SHORTCOMINGS.md` before claiming parity with the Java port.
+- The relevant page under `docs/` when changing behaviour that is documented.
+- `references/architecture-map.md` for a compact refresher.
+
+## This is a port
+
+`../ekbatan` is the reference implementation, and the two are expected to interoperate on the
+same tables. **Read the Java file whole before changing the Python counterpart.** Every defect
+this port found in its own code was found that way.
+
+**Never commit in the Java repository.** Write the files and say what is ready. Defects found in
+the Java while porting go in an openspec change, not a code change.
+
+## Rules
+
+- A library, not an application.
+- Domain objects stay immutable. A mutation returns a new instance. This is load-bearing: the
+  plan holds references, and the executor writes them after `perform()` returns.
+- Every concrete `Model` and `Entity` defines `validate(self) -> None` - its one place for rules
+  beyond its types, `pass` when it has none (AGENTS.md "Every model and entity defines
+  `validate()`"). It is abstract and refused at class definition; ekbatan runs its built-in
+  checks then `validate()` on every row made, and wraps a model's own `__post_init__`.
+- `Action.perform()` declares intent. It stages on the plan; the executor persists afterwards.
+- No nested or composable actions.
+- Preserve optimistic locking. Every update carries `WHERE version = ?`.
+- SQLAlchemy **Core**, used as a typed statement builder. Never introduce `Session`, an identity
+  map, autoflush or lazy loading - two units of work fighting over one transaction is the worst
+  thing that could happen to this design.
+- Keep PostgreSQL, MySQL and MariaDB aligned unless a dialect difference is intentional and
+  documented. SQLite is not a production dialect and proves less than it looks like it proves.
+- **The framework never converts time** (hard rule, AGENTS.md "Time: the framework never
+  converts it"): every time is written and read exactly as given; no `astimezone`/`tzinfo`
+  normalisation anywhere in `src/` (`tests/unit/test_time_as_is.py` guards it). The default
+  `SystemClock().instant()` is UTC with no zone attached. Changing this needs the user's OK.
+- `timestamp_column()`, never a zoned type. `DATETIME(6)`, never bare `DATETIME`. It is only a
+  column type: zone-less, microseconds.
+- **UTC everywhere is the strong recommendation** - the user's job, not the framework's - in
+  code, docs and examples alike: time from the clock (`clock.instant()`, `self.clock.instant()`), never
+  `datetime.now()` (local time); `TIMESTAMP`,
+  never `TIMESTAMPTZ`; the database in UTC or each session put on it via `data_source_properties`.
+  Say so wherever timestamps come up. Guide: `docs/database/multi-database.md#always-utc`.
+- Params and payload JSON is the text Java's default Jackson 3 mapper writes, byte for byte
+  (camelCase keys, decimals as numbers); `ekbatan._json` and `parity-probes/G-domain-model/` hold it.
+- **Time kinds** (`ekbatan.time`, AGENTS.md "Time kinds"): `Instant`, `LocalDateTime`,
+  `OffsetDateTime` are `NewType` labels over `datetime`. `clock.instant()` is the one clock
+  reading (no `now()`); models' dates and framework-written times are `Instant`; event and params
+  JSON is written by the declared label and a plain `datetime` field is refused; schemagen types
+  zone-less timestamps `Instant`, a forced `LocalDateTime` as such, `TIMESTAMPTZ` `OffsetDateTime`.
+- Nothing in `src/` may import a web framework. `tests/test_structure.py` enforces it.
+- The ambient transaction is a `ContextVar`. Work handed to a pool does not inherit it, and that
+  is correct.
+- Migrations are `V<version>__<description>.sql` and `R__<description>.sql` files, run the way
+  Flyway runs them; `validate_scripts` checks them with no database. On MySQL and MariaDB keep
+  one schema change per file - each commits on its own, and a failure after one is recorded and
+  blocks until `repair()`. `docs/MIGRATOR-LEDGER.md` settles every behaviour against Flyway 12;
+  a change to the migrator updates it, and `scripts/flyway-parity.py` reruns the comparison.
+
+## Workflow
+
+1. Map the change to the owning module before editing.
+2. Read nearby code and tests. Prefer local patterns over new abstractions.
+3. Write the test so it **fails for the right reason** first. Reinstate the bug and watch it go
+   red before believing it - several "passing" tests here turned out to assert nothing.
+4. Keep changes narrow. No unrelated refactors.
+5. Update `docs/` when public semantics change, and record a new divergence in `DIVERGENCE.md`
+   or a step backwards in `docs/SHORTCOMINGS.md`.
+6. Run focused tests, then the broader suite.
+
+## Checks
+
+- Fast loop: `make test`
+- Anything touching SQL: `make test-all` - dialects disagree, and SQLite agrees with everyone.
+- `make lint` covers ruff, mypy `--strict` over `src` *and* the examples, and the docs link
+  checker.
+- Examples or generated schemas: `make examples`.

ekbatan-0.1.0/.agents/skills/ekbatan-py-maintainer/references/architecture-map.md

@@ -0,0 +1,76 @@
+# Architecture map
+
+A compact orientation. `AGENTS.md` remains the source of truth.
+
+## The core idea
+
+A persistence and action framework. It stores state changes and domain events atomically, so the
+database can act as a reliable outbox.
+
+An **action** declares intent. During `perform()` it reads repositories and stages immutable
+snapshots on a **plan**. After `perform()` returns, the **executor** opens the transaction and
+writes the domain rows and the event rows together.
+
+## The layout
+
+```
+src/ekbatan/
+  domain.py          Model, Entity, ModelEvent, the builders
+  ids.py             Id, ShardedId, TypedValue
+  sharding.py        ShardIdentifier, the strategies, the bit layout
+  repository.py      Repository, ModelRepository, EntityRepository, RepositoryRegistry
+  persistence.py     DatabaseRegistry, TransactionManager, Transaction
+  config.py          DataSourceConfig, ShardConfig, ShardingConfig
+  schema.py          the framework's tables, the column helpers, Converter/converted()/sql_type()
+  errors.py          the exception hierarchy
+  clock.py           Clock, SystemClock, VirtualClock
+  migrations.py      SQL migrations on yoyo: files, checks, history, one call per layout
+  schemagen/         table definitions from a migrated database: _config (pyproject, forced
+                     types: name, converter, sqlalchemy-type), _types (the type table; an
+                     unknown type is sql_type("...")), _reflect, _render, _records (the
+                     typed `<Table>Record` beside each table)
+  codegen.py         typed builders, generated per model
+  streaming.py       ActionEvent - the consumer-side view of an outbox row
+  accounting.py      statement counting, so cost claims are checkable
+  action/            action, plan, executor, registry, persister, outbox
+  events/            handler, fanout, dispatch, jobs, notification, config
+  locks/             base, sql, redis, inprocess, _holder
+  distributedjobs/   DistributedJob, JobRegistry, JobsConfig
+db-scheduler/        a separate distribution: the port of kagkarlsson/db-scheduler
+ekbatan-py-examples/ seven examples x uv/pip/Poetry: 21 standalone projects
+website/             Astro. The only part that does not run through uv
+```
+
+## Invariants
+
+- Domain objects are frozen dataclasses. A mutation returns a new instance.
+- Only a `Model` emits events. An `Entity` does not.
+- Every persistable carries a `version`, and every update checks it.
+- Reads filter soft-deleted rows once, in the framework.
+- Every repository writes `to_record` / `from_record`, typed by the table's record - a `dict`
+  subclass schemagen writes beside the table (`WalletsRecord` beside `WALLETS`), with a
+  keyword `__init__`, `__getitem__` overloads for mypy only, and a `column_<name>()` method per
+  column (`EKB-0485`); repositories are `ModelRepository[Wallet, WalletsRecord,
+  UUID]` - the key is the type the id column holds, as Java's `DB_ID`: a read by id takes
+  `wallet.id.value`, and a forced type converting the id column makes the typed id the key
+  (`EKB-0541`). `columns_by_field_name` /
+  `model_by_field_name` are the by-name mapping, chosen in a line, never a default.
+- `to_record` builds the record by keyword - `WalletsRecord(id=..., version=..., ...)`; a column
+  whose name is no Python name has a sanitized keyword (`class_=`, `order_date=`, `_2fa=`), and
+  one the database fills defaults to `UNSET` (left out of the record and the INSERT). The INSERT
+  is given that very dict. `from_record` reads `record.column_x()` (the preferred way;
+  `record["x"]` is fine too, equally type-checked); the framework hands it the record class on every read path.
+- The ambient transaction is a `ContextVar`, so it is per-thread and per-task.
+- Opening a transaction inside another one opens a **second** transaction on a second
+  connection, as Java's does (`EKB-0301`). Repository calls inside a block join it; nested blocks
+  do not. Do not nest.
+- Cross-shard is refused unless asked for, because atomic-across-databases does not exist.
+
+## Where the two ports differ
+
+`DIVERGENCE.md` is the complete list. The ones that bite most often:
+
+- no virtual threads, so fan-out, dispatch and the lock watchdog are sequential or thread-backed;
+- the framework is synchronous, and blocking is not free under asyncio;
+- retry matching is by `isinstance` here and exact by class in Java;
+- this port has no graceful shutdown on a signal, and no pool leak detection.

ekbatan-0.1.0/.agents/skills/ekbatan-py-verification/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: ekbatan-py-verification
+description: Choose and run ekbatan-py verification. Use when asked to test, validate, run CI-equivalent checks, run the examples, run the dialect matrix, inspect the GitHub Actions workflows, or decide which commands prove a change.
+---
+
+# ekbatan-py verification
+
+Test planning and execution in this repository.
+
+## First reads
+
+- `references/test-matrix.md`.
+- `.github/workflows/ci.yml` for what CI runs on every push, and `heavy-verification.yml` for
+  what runs nightly - the examples and the setup guide.
+- `Makefile` - every command this repository has, in one place.
+
+## Default strategy
+
+1. **Focused tests first.** `uv run pytest tests/unit/test_plan.py -k stages`.
+2. **The fast loop** when shared code changed:
+
+   ```bash
+   make test          # unit, then the whole suite on SQLite
+   ```
+
+3. **The dialect matrix** whenever the change touches SQL. Not optional - dialects disagree, and
+   SQLite agrees with everyone:
+
+   ```bash
+   make test-all      # PostgreSQL, MySQL and MariaDB. Needs Docker
+   ```
+
+4. **The examples** when they or the generated schemas changed:
+
+   ```bash
+   make examples      # all 21: each regenerates its schema, builds its wheel, tests it installed
+   ```
+
+## Reporting
+
+Report exactly what ran and what did not. Distinguish:
+
+- unit tests (no database at all);
+- the SQLite suite;
+- each of PostgreSQL, MySQL and MariaDB;
+- the non-UTC PostgreSQL pass, which is where timestamp defects hide;
+- the examples' own tests;
+- lint, mypy and the docs link checker.
+
+**Do not claim the suite passes when only SQLite ran.** SQLite's types are advisory, so a mapping
+bug it accepts will fail in production. The claim that this framework works is a claim about the
+three real dialects.
+
+If a command fails on Docker, sandboxing or network access, say so rather than reporting a pass.
+
+## Traps this suite has already fallen into
+
+Each was a real bug in the tests, found by running:
+
+- **MariaDB announcing itself as MySQL.** The container hands back a `mysql+pymysql` url. The
+  scheme must be rewritten to `mariadb+pymysql` or "the MariaDB suite" tests MySQL.
+- **A frozen clock makes outbox rows tie.** `event_date` is the only ordering key, so under
+  `VirtualClock` every row of a run ties and order falls back to a random uuid. Assert on
+  `action_name` or `action_id`.
+- **`str(engine.url)` masks the password**, so a "separate connection" built from it connects to
+  nothing.
+- **A module-scoped container shares state between tests.** Truncate in the fixture.
+
+## CI
+
+Six jobs: lint and types, the fast suite, the examples, a tracing pass, the three dialects, and
+PostgreSQL again under `TZ=America/New_York`. The website has its own workflow, triggered by
+`docs/**` as well as `website/**`.

ekbatan-0.1.0/.agents/skills/ekbatan-py-verification/references/test-matrix.md

@@ -0,0 +1,68 @@
+# Test matrix
+
+## What exists
+
+| | count | needs Docker |
+| --- | ---: | :---: |
+| `tests/unit/` | 250 | no |
+| `tests/integration/`, on one dialect | 322 | for all but SQLite |
+| the whole suite on SQLite | 578 | no |
+| the whole suite on four dialects | 1,370 | yes |
+| the examples' own tests | 78 | yes |
+
+264 of the tests are parametrised over the dialect, which is why `--dialects=all` multiplies.
+
+## Commands
+
+```bash
+uv run pytest tests/unit              # no database at all, about a second
+make test                             # unit, then everything on SQLite
+uv run pytest --dialects=postgres     # one dialect, in a container
+make test-all                         # all four
+make examples                         # regenerates schemas first
+make lint                             # ruff, mypy --strict, and the docs link checker
+```
+
+`--dialects` takes `sqlite`, `postgres`, `mysql`, `mariadb` or `all`, comma-separated.
+
+## What proves what
+
+| the change touches | run |
+| --- | --- |
+| pure logic, a plan, a builder | `tests/unit` |
+| any SQL | **`make test-all`.** Not optional |
+| timestamps | `make test-all`, and note CI also runs PostgreSQL under a non-UTC process |
+| `schemagen` | `pytest tests/unit/test_schemagen_config.py tests/unit/test_schema_converters.py tests/unit/test_schemagen_records.py tests/unit/test_typed_records_mypy.py`, `pytest tests/integration/test_schemagen*.py --dialects=all` (every type on every database; converters; the pgvector test pulls `pgvector/pgvector:pg17` and runs on PostgreSQL only), then `make examples` |
+| an example | `make examples` |
+| the docs | `make lint` - it checks every relative link |
+| the website | `cd website && npm run build && npm run check` |
+
+## Why SQLite is not enough
+
+It is the default because a suite needing a daemon is a suite people stop running. It is **not a
+production dialect**:
+
+- no `SKIP LOCKED`, so the scheduler and the SQL keyed lock degrade to single-process behaviour;
+- types are advisory, so a mapping bug PostgreSQL rejects loudly can pass here;
+- no real write concurrency.
+
+SQLite passing is necessary and not sufficient.
+
+## CI
+
+Three workflows on GitHub (`ekbatan-io/ekbatan-py`), each modelled on its Java twin:
+
+- **CI** (`ci.yml`) on every push and pull request to main, except a push that only touches
+  `website/**`: lint and types, the fast suite, the whole suite under gevent, a tracing pass that
+  asserts the span names, the three real dialects in a matrix, PostgreSQL with `ekbatan.aio` on
+  psycopg's async mode, and PostgreSQL again under `TZ=America/New_York` - which is the job that
+  would catch a driver inferring a zoned type. Python is pinned to 3.14.
+- **Website** (`deploy-website.yml`) on a push that touches `website/**` or `docs/**`: builds the
+  site for `/ekbatan-py/`, runs its checks and the Python ones that read it, and deploys it to
+  GitHub Pages.
+- **Heavy Verification** (`heavy-verification.yml`) nightly, after midnight UTC, if main changed
+  the day before - or by hand, where `force` skips that test: every example, and the setup guide
+  followed as written for every database, installer and mode.
+
+The tracing job is the only one that installs the OpenTelemetry SDK. Every other job proves the
+framework runs without it.

ekbatan-0.1.0/.claude/skills/ekbatan-py-examples/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: ekbatan-py-examples
+description: Maintain the ekbatan-py example applications. Use when adding, updating, auditing or verifying anything under ekbatan-py-examples across the PostgreSQL, MySQL, MariaDB, sharded, saga, job-worker and SQLite examples and their async twins, each built with uv, pip and Poetry.
+---
+
+# ekbatan-py examples
+
+Use this when a change affects an example application, its docs, its wiring, or consistency
+across the matrix.
+
+## First reads
+
+- `ekbatan-py-examples/README.md`.
+- The closest existing example for the same dialect.
+- `references/example-matrix.md`.
+- `docs/wiring.md` and `docs/wiring-fastapi.md`.
+
+## Matrix discipline
+
+Fourteen examples, **each carried three times** - `-uv-`, `-pip-`, `-poetry-` - as Java carries its
+examples per Gradle and Maven: 42 projects. Only the REST example is replicated per database, and
+every example has an async twin.
+
+| | |
+| --- | --- |
+| per database | `fastapi-wallet-rest-{build}-pg`, `-mysql`, `-mariadb` |
+| per database, async | `fastapi-wallet-rest-{build}-async-pg`, `-async-mysql`, `-async-mariadb`, `wallet-service-{build}-async-sqlite` |
+| one of a kind | `fastapi-wallet-rest-{build}-sharded-pg`, `fastapi-wallet-saga-{build}-pg`, `job-worker-{build}-pg`, `wallet-service-{build}-sqlite` |
+| one of a kind, async | `fastapi-wallet-rest-{build}-async-sharded-pg`, `fastapi-wallet-saga-{build}-async-pg`, `job-worker-{build}-async-pg` |
+
+**Two modes.** Every example has an async twin on `ekbatan.aio`, with the same tests plus a
+check that it really runs async (its drivers, its loop). The complete-project-setup page shows
+both for each database, and `scripts/check-setup-guide.py` builds both. A change to a sync
+example's behaviour goes into its async twin too, or the twin's README says why not; a new
+example gets an async twin. In the job worker's twin the jobs stay sync (every distributed job
+is) and their work runs on a `HandlerLoop` with `loop.run(...)`.
+
+**Edit only the uv project**, then run `uv run python scripts/sync-examples.py`: it writes the
+pip and Poetry twins (the same `src/`, byte for byte) and every project's `pyproject.toml`,
+`Makefile`, `.gitignore` and README build section. Never hand-edit a twin - `make lint` runs
+`sync-examples.py --check` and fails on any drift. When changing a base wallet behaviour, change
+all three REST databases' uv projects; those are not generated from one another.
+
+## An example is documentation
+
+- **mypy `--strict` runs over the examples' uv projects** (their twins are the same code),
+  because documentation that would not type-check is documentation that is wrong.
+- They import only the framework, the standard library and what each project's `pyproject.toml`
+  declares. `tests/test_structure.py` enforces it.
+- They are **not** shared with `tests/fixtures/`. The suite's domain exists to exercise every
+  shape worth exercising; an example exists to show what good code looks like. Coupled, every
+  coverage change lands in the documentation.
+- A claim in an example's README must be backed by its source. An example nobody runs rots -
+  and one did, silently, because this repository had no remote and CI had never executed.
+
+## Conventions
+
+- Actions are named exactly as Java names them: `WalletCreateAction`, `WalletDepositMoneyAction`, `WalletCloseAction`, `CreateNotificationAction`, `InitiateTransferAction` - no word-order rule, Java mixes model-first and verb-first. Each action's parameters are its nested `Params`.
+  Events are `WalletCreatedEvent`, `WalletMoneyDepositedEvent` - past tense, `Event` suffix. Handlers
+  end `EventHandler`, jobs end `Job`.
+- In a sync example, endpoints are plain `def`, never `async def`. FastAPI runs a plain `def` in
+  a threadpool; an `async def` calling into the synchronous framework blocks the whole event
+  loop. In an async twin every endpoint is `async def` and awaits `ekbatan.aio`.
+- Three pools per member - requests, jobs, locks - and the jobs pool is at least twice the worker
+  count.
+- A keyed lock lease must span `executor.execute(...)`, not just the read.
+- Generated `schema.py` is gitignored. Never commit one, and never edit one.
+- Forced types are set in `scripts/sync-examples.py` (`WALLET_FORCED`, `SAGA_FORCED`), which
+  writes every `pyproject.toml`; see `references/example-matrix.md#forced-types`. A converter's
+  module must not import `schema.py` - schemagen imports it before `schema.py` exists.
+
+- **UTC everywhere**, the framework's strong recommendation: an example takes time from the clock
+  (`self.clock.instant()`, `clock.instant()`), never `datetime.now()`; its migrations use `TIMESTAMP` (PostgreSQL)
+  or `DATETIME(6)` (MySQL, MariaDB), never `TIMESTAMPTZ`; its database runs in UTC. See
+  `docs/database/multi-database.md#always-utc`.
+- **Every model and entity defines `validate()`**: `Wallet.validate()` has `pass` with a one-line
+  reason (nothing beyond its types, as Java's constructor checks only for null),
+  `Notification.validate()` refuses a blank recipient or message, `TransferStep` has `pass`.
+- **Time kinds**: an event's time field is declared `Instant` (or `LocalDateTime` /
+  `OffsetDateTime`) from `ekbatan.time` - a plain `datetime` field is refused when the action
+  runs. The examples' events carry no time field, as Java's do not.
+- **Repository variables** are Java's field names in snake_case - `wallet_repository`,
+  `notification_repository`, never `wallets` - and so are the other wiring objects:
+  `database_registry`, `lock_provider`, `job_registry`.
+
+## Workflow
+
+1. `ls ekbatan-py-examples` to see the matrix.
+2. Read a known-good uv project for the dialect family before editing.
+3. Make the smallest mechanical cross-matrix edit possible, in the uv projects.
+4. `uv run python scripts/sync-examples.py` to carry it to the pip and Poetry twins.
+5. `make examples` - every project builds its wheel and tests it installed, so a file a build
+   tool leaves out fails here. Needs Docker, `poetry` on the path, and a Python 3.13+ (found
+   through uv).
+
+Use `ekbatan-py-verification` for the full matrix.