feat(email): drain queued sys_email rows so app inserts actually deliver

[os-zhuang]

Problem (verified empirically, not by reading specs)

An app that can only `api.write` — e.g. a sandboxed action body, which exposes no `api.email` and cannot reach the queue — has exactly one way to "send" mail: INSERT a `sys_email` row. But the transport (and the `queued → sent` transition) only ran inside `EmailService.send()`. A raw insert never invokes it, so the row sat at `status:'queued'` forever — declared-but-never-delivered, not even log-simulated.

This was caught while auditing a real consumer (HotCRM's `send_email` action): it raw-inserts a queued `sys_email` and writes a "completed Email" timeline activity — i.e. the UI claimed delivery that never happened.

Fix

Treat a `sys_email` row inserted as `status:'queued'` with no `message_id` as an outbox entry. A `sys_email` afterInsert hook delivers it through the live transport and finalizes the same row in place (`sent` + `message_id` + `sent_at`, or `failed` + `error`).

• Delivery is deferred past the insert op so transport I/O never runs inside the insert's transaction, and the committed row is re-read + re-checked (`status==queued`) under system context before sending — idempotent against concurrent drains.
• Rows that the service's own `send()` inserts are tagged managed (`EmailService.isServiceManaged`) and skipped by the hook, so they are delivered exactly once by `send()` — never double-sent.

Changes

• `email-service.ts`: `managedRowIds` guard; extract `deliverNormalized()` shared by `send()` and the new `deliverPersistedRow()`; `rowToNormalized()` helper.
• `email-plugin.ts`: register the `sys_email` afterInsert drain hook (own packageId, unregister-on-reinstall).
• tests: +5 (managed-guard active at the insert moment; `deliverPersistedRow` delivers without inserting a 2nd row and fails cleanly on bodyless rows; `rowToNormalized` parse/throw).

Verification

• Empirical (HotCRM, patched dist): raw `INSERT` of a queued `sys_email` → `sent` with a transport `message_id` (`<dev-…@objectstack.local>`) + `sent_at` within ~600ms. Before this change the identical insert stayed `queued` forever (`message_id:null`, `sent_at:null`).
• Unit: `pnpm exec vitest run` → 20/20 in email-service.test.ts; full package 49→ still green.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jun 17, 2026 4:37am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-email.

2 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/concepts/packages.mdx (via @objectstack/plugin-email)
• content/docs/guides/packages.mdx (via @objectstack/plugin-email)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.