fix: Request-scoped session exposes no post-commit hook, so module caches refresh against uncommitted state

[antosubash]

Closes #268

Headless Pi worker

This is a draft pull request created from an issue carrying the approval label.
It is never merged automatically and requires human review.

Agent summary

Summary

• Added RequestSession.on_commit(callback) supporting sync and async callbacks.
• Callbacks run only after successful commits; rollback/read-only/failed commits discard them.
• Callback failures are logged without affecting committed responses or later callbacks.
• Exported the new session/callback types and documented usage.

Changed areas

• DB session/finalization runtime
• Framework DB public API
• Session documentation and changelog
• Transaction/session tests

Verification

• uv run pytest framework/db/tests — 69 passed
• Ruff format/check — passed
• uv run ty check ... — passed
• uv run python scripts/check_file_size.py — passed
• git diff --check — passed

Visual evidence: none required.

Risks/blockers: none.

Local visual evidence

When requested, screenshots, traces, videos, and GIFs are stored only under the worker worktree's ignored
.qa/issues/268/ directory. GitHub CLI cannot attach those files; inspect them on the worker host
or attach selected evidence manually.

[cloudflare-workers-and-pages]

Deploying simple-module-python with    Cloudflare Pages

Latest commit:	fab80a8
Status:	✅  Deploy successful!
Preview URL:	https://0cd17bf4.simple-module-python.pages.dev
Branch Preview URL:	https://pi-issue-268-request-scoped.simple-module-python.pages.dev

View logs

[antosubash]

✅ CI checks passed for this pull request.

[antosubash]

✅ CI checks passed for this pull request.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
🔒 Security Review	✅ Completed 2026-09-04T21:15:58.267057Z	fab80a8	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.