Skip to content
Emdash Mika Docs

Maintenance

Mika registers a maintenance cron task through the EmDash plugin lifecycle.

Use this page when wiring or interpreting Mika’s mika_maintenance cron task. Do not use it as a scheduler guarantee: the host adapter or platform must run EmDash scheduled tasks.

The descriptor/runtime split matters:

  • mikaPlugin() writes maintenance options into the EmDash plugin descriptor;
  • createPlugin() registers, cancels, and executes the live cron handler;
  • createMikaMaintenanceRunner() runs one sweep over the configured subtasks.

The built-in cron task name is mika_maintenance. The default schedule is * * * * *, unless the host passes maintenance.schedule.

The task can:

  • drain the email outbox;
  • reclaim exhausted email outbox leases;
  • purge retained raw webhook provider payloads;
  • clean up expired ACP checkout sessions;
  • release expired stock reservations;
  • purge expired ephemeral rows;
  • process queued account-delete requests;
  • reclaim exhausted workflow leases.

Each subtask has dependencies. Stock release uses the Mika admin API or a host-provided release function. Email draining requires an emailOutboxRunner. ACP session cleanup requires an ACP session store with cleanupExpired() or a host-provided cleanup function. Repository-backed cleanup uses the host repositories. Missing dependencies produce skipped task results rather than magically running without host wiring.

Host deployments must ensure EmDash scheduled tasks run in the target adapter or platform.

In task results, skipped usually means the host did not provide the repository or runner that a subtask needs. It is different from failed.

Runtime Inputs

Section titled “Runtime Inputs”
Input Used by
api or releaseExpiredReservations Stock reservation release. createPlugin() passes the Mika API by default.
emailOutboxRunner Email outbox delivery. Without it, the email outbox task is skipped.
acpSessionStore or cleanupExpiredAcpSessions ACP checkout-session expiry and terminal-session purge.
purgeExpiredEphemeralRecords Optional custom expired ephemeral purge. Otherwise repositories can provide it.
repositories.ephemeral Expired token/session purge and account-delete token cleanup.
repositories.ops Stuck email reclaim, raw webhook payload purge, account-delete queues, account-delete step recording, email redaction during account delete, and exhausted workflow lease reclamation.
repositories.account Account-delete subscription checks plus entitlement, license, and customer anonymization.
repositories.ledger Account-delete order anonymization.
repositories.session Account-delete active checkout checks.
repositories.stock Expired stock reservation release and account-delete reservation release.
now Deterministic clock for the maintenance sweep.

MikaMaintenanceRunOptions can override now, emailLimit, stuckEmailLimit, rawProviderPayloadLimit, rawProviderPayloadRetentionDays, acpSessionLimit, accountDeleteLimit, and stuckWorkflowLimit for one run.

Task Results

Section titled “Task Results”

createMikaMaintenanceRunner().runOnce() returns a MikaMaintenanceRunResult with one result per subtask:

Task key Completed result
emailOutbox MikaEmailOutboxRunResult counters: scanned, leased, sent, failed, skipped, leaseMissed, leaseLost, hasMore, plus per-email items whose statuses include lease_missed and lease_lost.
stuckEmails Counts scanned and reclaimed exhausted email leases.
rawProviderPayloads Counts scanned and purged retained raw webhook payloads older than the retention cutoff.
acpSessions Counts scanned, expired, purged, and hasMore for ACP checkout session cleanup.
stockReservations Counts scanned reservations, released reservations, and affected stock items.
ephemeralRecords Count of purged expired ephemeral records.
accountDeleteRequests Counts scanned, completed, failed, hasMore, and per-request items. Completed items include tokens deleted, reservations released, emails redacted, customer anonymization, order anonymization, entitlement anonymization, and license anonymization counts.
stuckWorkflows Counts scanned and reclaimed exhausted workflow leases.

Each task can be completed, failed, or skipped. The plugin logs a summarized result. Stock reservation failure is rethrown from the cron handler so the host scheduler can observe the failed run.

Account-delete processing records each completed cleanup step in request metadata before continuing. If a later step fails after cleanup has started, Mika records the error but leaves the queued request retryable so the next maintenance run can resume completed steps instead of repeating them.

Host Responsibilities

Section titled “Host Responsibilities”

The host must provide durable repositories, an email sender, ACP session cleanup, and retention choices if it expects all maintenance tasks to run. It also owns scheduler execution in production: GitHub Pages does not run cron jobs by itself, and serverless/edge deployments need platform-specific scheduled execution.

For EmDash plugin lifecycle background, see the official EmDash plugin guide.

Source Anchors

Section titled “Source Anchors”
  • ⓟ ../emdash-mika/src/plugin.ts
  • ⓟ ../emdash-mika/src/api/maintenance.ts
  • ⓟ ../emdash-mika/src/api/email-outbox.ts