update notes with patterns from real projects

async.md:
- add connection pool singleton pattern from follower-weight
- add postgres batch writes with unnest()

pydantic.md:
- add model_validator for side effects (logging setup)

firehose.md:
- replace generic batch example with realistic tap_consumer pattern
- show separate buffers, time-based flushing, pending acks

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

languages/python/ecosystem/pydantic.md

···
 
 from [coping with python's type system](https://blog.zzstoatzz.io/coping-with-python-type-system/)
 
+## model_validator for side effects
+
+run setup code when settings load:
+
+```python
+from typing import Self
+from pydantic import model_validator
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    debug: bool = False
+
+    @model_validator(mode="after")
+    def configure_logging(self) -> Self:
+        setup_logging(debug=self.debug)
+        return self
+
+settings = Settings()  # logging configured on import
+```
+
+the validator runs after all fields are set. use for side effects that depend on configuration values.
+
+from [bot/config.py](https://github.com/zzstoatzz/bot)
+
 ## when to use what
 
 pydantic models are heavier than they look - they do a lot of work on instantiation. for internal data you control, python's `dataclasses` are simpler:

languages/python/language/async.md

···
 at most `concurrency` delete operations run at once. the rest wait.
 
 from [pdsx/_internal/batch.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/_internal/batch.py)
+
+## connection pools
+
+module-level singleton pool, lazily initialized:
+
+```python
+_pool: asyncpg.Pool | None = None
+
+async def get_pool() -> asyncpg.Pool:
+    global _pool
+    if _pool is None:
+        _pool = await asyncpg.create_pool(db_url, min_size=2, max_size=10)
+    return _pool
+
+@asynccontextmanager
+async def get_conn() -> AsyncGenerator[asyncpg.Connection, None]:
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        yield conn
+```
+
+callers use `async with get_conn() as conn:` - pool handles connection lifecycle.
+
+## batch writes with unnest
+
+postgres `unnest()` turns arrays into rows. one round trip for thousands of inserts:
+
+```python
+async def batch_upsert_follows(follows: list[tuple[str, str, str]]) -> None:
+    follower_ids = [f[0] for f in follows]
+    rkeys = [f[1] for f in follows]
+    subject_ids = [f[2] for f in follows]
+
+    async with get_conn() as conn:
+        await conn.execute(
+            """
+            INSERT INTO follows (follower_id, rkey, subject_id)
+            SELECT * FROM unnest($1::bigint[], $2::text[], $3::bigint[])
+            ON CONFLICT (follower_id, rkey) DO UPDATE
+            SET subject_id = EXCLUDED.subject_id
+            """,
+            follower_ids, rkeys, subject_ids,
+        )
+```
+
+from [follower-weight/db.py](https://github.com/zzstoatzz/follower-weight)

protocols/atproto/firehose.md

···
 
 ## batch processing
 
-for high-volume consumption, batch writes:
+for high-volume consumption, batch by operation type and flush on size OR time:
 
 ```python
 BATCH_SIZE = 1000
-buffer = []
+FLUSH_INTERVAL = 2.0
 
-async for event in firehose.subscribe():
-    buffer.append(event)
-    if len(buffer) >= BATCH_SIZE:
-        await bulk_insert(buffer)
-        await ack_cursor(event.seq)  # ack AFTER persistence
-        buffer = []
+follow_batch: list[tuple[str, str, str]] = []  # (follower_did, rkey, subject_did)
+unfollow_batch: list[tuple[str, str]] = []     # (follower_did, rkey)
+pending_acks: set[int] = set()
+last_flush = time.monotonic()
+
+async def flush(ws):
+    if follow_batch:
+        await db.batch_upsert_follows(follow_batch)
+        follow_batch.clear()
+    if unfollow_batch:
+        await db.batch_delete_follows(unfollow_batch)
+        unfollow_batch.clear()
+    # ack AFTER persist
+    for ack_id in sorted(pending_acks):
+        await ws.send(json.dumps({"type": "ack", "id": ack_id}))
+    pending_acks.clear()
+
+while True:
+    try:
+        msg = await asyncio.wait_for(ws.recv(), timeout=0.1)
+    except asyncio.TimeoutError:
+        # time-based flush for low-volume periods
+        if time.monotonic() - last_flush > FLUSH_INTERVAL:
+            await flush(ws)
+            last_flush = time.monotonic()
+        continue
+
+    event = json.loads(msg)
+    # ... parse and append to appropriate batch ...
+    pending_acks.add(event["id"])
+
+    if len(follow_batch) >= BATCH_SIZE:
+        await flush(ws)
+        last_flush = time.monotonic()
 ```
 
-critical: acknowledge cursor only after successful persistence. if you crash, you'll replay from the last ack.
+critical: ack cursor only after successful persistence. if you crash, you replay from last ack.
 
-from [follower-weight](https://github.com/zzstoatzz/follower-weight) - batches 1000 events, acks after postgres commit.
+from [follower-weight/tap_consumer.py](https://github.com/zzstoatzz/follower-weight)
 
 ## cursor management