fix: move HTTP publish retention to the background scheduler

[guangyu-reflexio]

Summary

HTTP publishes currently run the embedded library's retention sweep after committing admission and reading coverage. A due sweep checks all capped tables before returning the response. Move that housekeeping to the server's existing retention scheduler so HTTP acknowledgement no longer waits for those queries.

Changes

• Mark server publishing with a context-local scheduler ownership scope; skip inline retention before touching the embedded throttle, and reset ownership on exit.
• Preserve direct embedded cleanup, including calls that defer learning, and record the helper's duration as retention_ms.
• Document scheduler ownership and cadence: positive caps enable startup; successful ticks use the configured interval (24 hours by default), with bounded retries after failures. Caps can be exceeded between sweeps.

Test Plan

• OSS suite: 6,350 passed, 14 skipped, 6 subtests passed.
• E2E tier: 48 passed; 87 optional/live-provider cases skipped.
• Focused regressions: 124 passed; final integration file: 3 passed.
• Real HTTP/SQLite coverage checks independent-connection durable acknowledgement, write-failure rollback, no inline retention probes, subsequent scheduler cap deletion, embedded deferred cleanup, and context isolation/reset.
• Removing the ownership guard makes the HTTP regression fail; the original implementation was restored and verified.
• Ruff and Pyright clean. TestSprite CLI unavailable.

Production latency attribution and the 5,000 ms target still require post-deployment measurement.

Summary by CodeRabbit

• Performance
  • HTTP publishing now returns after the interaction is durably accepted, without waiting for retention cleanup.
• Retention
  • Configured request caps are enforced by background cleanup. Caps may be exceeded between cleanup runs.
  • Embedded publishing continues to perform retention cleanup, limited to once every five minutes.

[chatgpt-codex-connector]

Codex Review Summary

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

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-26T06:11:03.364660Z	719b018	PR opened
🔒 Security Review	✅ Completed 2026-09-26T06:17:32.119315Z	719b018	PR opened

ℹ️ 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.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: ReflexioAI/reflexio/.coderabbit.yaml

Review profile: CHILL

Plan: Essentials

Run ID: 834547c5-dc75-49a0-a8f9-5ac281ff0d97

📥 Commits

Reviewing files that changed from the base of the PR and between d67fd31 and 719b018.

📒 Files selected for processing (5)

• developer.md
• reflexio/lib/_interactions.py
• reflexio/server/api_endpoints/publisher_api.py
• reflexio/server/services/storage/retention_sweep.py
• tests/server/services/test_publish_retention_integration.py

Included review availability: This review used your included allowance. Your plan provides up to 5 included reviews per hour; 1 remain after this review. Your free on-demand review promotion remains active until October 9, 2026 at 6:00 PM UTC.

---

📝 Walkthrough

Walkthrough

HTTP publishing now runs inside a scheduler-managed retention context, which skips the inline retention-cap sweep. The context resets on exit. Direct embedded publishes retain their throttled sweep behavior, and the post-publish sweep is measured in a named timing phase.

Changes

Publish retention handling

Layer / File(s)	Summary
Retention scope and direct-call behavior reflexio/server/services/storage/retention_sweep.py, tests/server/services/test_publish_retention_integration.py	A context manager marks scheduler-managed work, and the retention helper skips sweeps in that context. Tests cover embedded-call throttling and context reset behavior.
HTTP publish integration reflexio/server/api_endpoints/publisher_api.py, reflexio/lib/_interactions.py, tests/server/services/test_publish_retention_integration.py, developer.md	The HTTP endpoint enters the managed context around publishing. The post-publish sweep uses a named timing phase. Integration tests and documentation cover persistence, scheduler enforcement, and retention behavior.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Suggested reviewers: yyiilluu

Merge Risk: ⚪ Minimal · up to 719b0

HTTP publishing no longer waits for retention housekeeping, while configured row caps remain subject to scheduled enforcement. No identified issue prevents merging after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 44.44% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 4 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: moving HTTP publish retention work to the background scheduler.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 44.44% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 4 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}