Deployment And Maintenance

Use this guide when a deployed host needs Mika’s scheduled cleanup to run outside local dev.

Maintenance can drain the email outbox, reclaim exhausted email 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, and reclaim exhausted workflow leases when the host supplies the required API methods, repositories, stores, and runners.

Prerequisites

• mikaPlugin is registered.
• The deployment platform can run scheduled tasks.
• Repository ports are configured for the subtasks the host expects.
• Logs or alerts are available for skipped and failed runs.

Maintenance Task

mikaPlugin registers a cron maintenance task (mika_maintenance, default schedule * * * * *). Each maintenance subtask can complete, fail, or skip:

• email outbox draining runs only when an emailOutboxRunner is configured;
• stuck email lease reclaim runs only when repositories.ops is configured;
• raw provider payload purge runs only when repositories.ops is configured;
• ACP session cleanup runs only when an ACP session cleanup function or store cleanup method is configured;
• stock reservation release uses the configured Mika admin API or host release function;
• expired ephemeral purge runs only when the required repositories or purge service are configured;
• queued account-delete processing runs only when the required repositories are configured.
• stuck-workflow reclamation runs only when repositories.ops is configured.

Tune the schedule on the plugin:

mikaPlugin({
  api,
  maintenance: { enabled: true, schedule: "*/5 * * * *" },
});

mikaPlugin() descriptor options only cover the serializable maintenance toggle and schedule. Runtime dependencies such as maintenance.repositories, maintenance.emailOutboxRunner, and any ACP cleanup function or store should be passed to createPlugin() from the native plugin entrypoint, alongside the host api, so function values, stores, and repository objects are not serialized through astro.config.mjs.

The snippet below assumes the host backend module exports api, repositories, and optionally emailOutboxRunner. If those are created in separate server-only modules, import them from there instead.

src/plugins/mika-plugin.ts

import { createPlugin as createMikaPlugin } from "@bnomei/emdash-mika";
import type { MikaCreatePluginOptions } from "@bnomei/emdash-mika";
import { api, emailOutboxRunner, repositories } from "../lib/mika-api";

export function createPlugin(options: MikaCreatePluginOptions = {}) {
  const maintenance = options.maintenance ?? {};

  return createMikaPlugin({
    ...options,
    api,
    maintenance: { ...maintenance, repositories, emailOutboxRunner },
  });
}

EmDash runs the task on its scheduled cycle. On Cloudflare Workers, the host must wire the Worker scheduled() handler to EmDash’s scheduled-task runner so the same maintenance runs on a Cron Trigger. The current seeded worker.cf.ts sketch exports the Astro handler and PluginBridge; it does not implement that scheduled() handler for you. Hosts still own the scheduler, secrets, storage, retries, and observability, and should monitor skipped/failed subtasks.

Mika logs a structured summary for each run. Any failed subtask is logged as a warning; a failed stock reservation release is rethrown so the scheduler can notice the run failure.

The plugin task id is mika_maintenance. The default schedule is * * * * *; maintenance.enabled: false cancels registration, and maintenance.schedule overrides the cron string. The runtime hook ignores other task ids, passes event.scheduledAt into the maintenance clock, and lets each subtask complete, fail, or skip independently.

Verify

• The scheduler invokes the EmDash task id mika_maintenance.
• Stock reservation release runs even when optional email/account cleanup dependencies are absent.
• Optional subtasks report skipped, not failed, when the host did not provide their repositories, stores, cleanup functions, or runners.
• Account-delete processing can resume after a partial cleanup failure because completed step results are recorded before the request is retried.
• Scheduler logs and alerts surface failed subtasks.

Next: Deployment Matrix compares runtime choices. Maintenance lists the exact task result shape.

Source Anchors

• ⓟ ../emdash-mika/src/plugin.ts
• ⓟ ../emdash-mika/src/api/maintenance.ts
• ⓟ ../emdash-mika/src/api/email-outbox.ts
• ⓐ ../emdash-mika/src/templates/astro/examples/backend-provider.md
• ⓣ ../emdash-mika-template/src/plugins/mika-template-plugin.ts