Embedding API: opting out of middleware auto-seed

[rmakk]

Context

I'm embedding EmDash inside a larger system that wants to provide its own initial schema (different collections and field names than defaultSeed) via a custom applySeed() call right after the EmDash worker comes online. This works most of the time, but I've hit a race condition in the auto-seed path that I'd love to get maintainer guidance on before opening a PR.

What's happening

The astroEmdash middleware auto-applies defaultSeed on the very first DB hit when:

• _emdash_collections is empty, AND
• emdash:setup_complete is unset in _emdash_settings

If anything triggers a DB-touching request to the EmDash worker between deploy and my own seed-apply call, the auto-seed wins:

• An OAuth callback warm-up
• A health check from a load balancer
• An operator opening a browser tab
• Any plugin handler that runs on cold start and reads _emdash_collections

Once that happens, _emdash_collections has the default posts collection (with content field), and a subsequent applySeed({ schema, onConflict: 'skip' }) silently no-ops on the already-existing collection. The resulting DB ends up with the wrong schema (ec_posts.content exists; my ec_posts.body doesn't), and the first content insert fails with D1_ERROR: table ec_posts has no column named body.

Switching to onConflict: 'update' works as a salvage path because it lets my seed patch the auto-applied collection in place. But it's a workaround with rough edges:

• It assumes the field-add path can converge any divergent default → custom schema. That's true for shapes that only add fields, but breaks for renames, type changes, or required-field additions on a populated table.
• It silently masks the race instead of preventing it. A lot of debugging time before realizing the auto-seed had already run.
• It couples downstream schema safety to the assumption that EmDash's defaultSeed won't grow new fields/indexes that conflict.

Minimal repro

// EmDash app
import { astroEmdash } from 'emdash/astro';
export default defineConfig({ integrations: [astroEmdash({ ... })] });

// Downstream caller
await fetch(`${url}/healthz`); // warms the worker → auto-seed runs
await fetch(`${url}/_my_app/seed-apply`, {
  method: 'POST',
  body: JSON.stringify({ schema: customSchema }),
});
// → silently applies, but _emdash_collections already has defaultSeed

After the second POST, _emdash_collections still reflects defaultSeed, not customSchema.

I'd love guidance on which of these you'd accept

A few options I've considered, in order of intrusiveness:

1. Opt-out flag on astroEmdash()

astroEmdash({
  autoSeed: false, // embedder takes responsibility for the initial seed
});

When false, middleware skips the auto-seed branch and waits for an explicit applySeed call. Simple, additive, fully backwards-compatible. The embedder is responsible for ensuring applySeed runs before the first user-facing request — which is already a constraint they've taken on by setting the flag.

2. Atomic-bootstrap helper

Expose a function the embedder can call before the first request that writes BOTH _emdash_collections AND emdash:setup_complete in a single transaction:

import { bootstrapDatabase } from 'emdash/seed';
await bootstrapDatabase(db, { schema: customSchema });
// → writes collections + s

[MA2153]

I like option 1. If EmDash is creating the posts collection by default, you should at least be able to opt-out.