Data residency

Cloudflare Durable Object jurisdictions restrict where a DO runs and stores data, for GDPR, FedRAMP, or US data residency. Declare one on your schema and Lunora pins every DO the app reaches to that region.

import { defineSchema, defineTable, v } from "lunorash/server";

export const schema = defineSchema({
    messages: defineTable({ channelId: v.id("channels"), text: v.string() }).shardBy("channelId"),
}).jurisdiction("eu");

Supported values: "eu", "us", "fedramp" (Cloudflare adds more over time). It composes with .rls(...) and .extend(...) in any order.

What it pins

Codegen reads .jurisdiction(...) off the schema and threads it through the generated worker, so a single declaration pins every Durable Object the app reaches:

• Shard DOs: every shard-local table (__root__ and .shardBy(...)), so all reads, writes, and the live-query subscriptions over them stay in-region.
• Fan-out: cross-shard query coordination.
• ctx.scheduler: the SchedulerDO that owns runAfter / runAt / cron timers.
• ctx.containers: container DOs and their lifecycle reporting.
• Voice agents: each voice-enabled agent's VoiceSessionDO, which holds the live session for /_lunora/voice/<agent> (see Pinning auth and voice).
• DO-backed auth: when .auth() is wired with a namespace (the auth tables live in a Durable Object), that object is pinned too, so users, sessions, and credentials stay in-region — once acknowledged.
• @lunora/mail: inbound dispatch (dispatchToLunoraFunction) and the dev capture inbox (createMailerFromEnv) reach the app's shards, and follow the schema's jurisdiction with no option passed (see Pinning mail).

It does not pin, by design:

• .global() tables: these are D1-backed, not Durable Objects. D1 has its own location settings; the DO jurisdiction does not apply.
• D1-backed auth: when .auth() is wired with d1, better-auth stores users and sessions in D1, so they follow D1's residency, not this option. DO-backed auth is pinned, see above.
• Workflows and agent runs: defineWorkflow and defineAgent runs are Cloudflare Workflows, not Durable Objects, so the jurisdiction does not apply to their step state. Their reads and writes go back through the worker and land in the pinned shards.
• Outbound mail delivery: a send goes to Cloudflare Email or Resend, and mailer.queue() to a Cloudflare Queue. Neither is a Durable Object.

Pinning auth and voice

Voice sessions and DO-backed auth were not pinned by earlier releases, even with .jurisdiction(...) declared. Nothing about the upgrade changes your schema, so the drift gate below does not fire for either.

Voice: pinned automatically, nothing to move

A VoiceSessionDO keeps no storage of its own. It holds the live socket and the audio of the utterance in progress, and writes every transcript turn to the agent's thread tables, which are rows in the app's shards: already pinned, and covered by lunora export. So a declared jurisdiction pins voice sessions with no acknowledgement. The only effect is that sessions live at the deploy drop; clients reconnect into the pinned objects and continue the same threads.

DO-backed auth: acknowledge first

Pinning the auth object moves it the way a jurisdiction change moves everything else: it resolves to a new, empty object, and every user, account, session and credential stays in the un-pinned one until you copy them across. So it is pinned only on an explicit acknowledgement:

export const schema = defineSchema({/* … */}).jurisdiction("eu", { pinAuth: true });

Without it, codegen refuses a project that declares .jurisdiction(...) and has an .auth({ namespace }) (DO-backed auth), pointing at the declaration. It also refuses when it cannot tell — an .auth(…) whose options it cannot read — because for D1-mode auth the acknowledgement changes nothing. Until you acknowledge, DO-backed auth stays on the un-pinned object, where its data is.

DO-backed auth: copy, verify, then purge

lunora export does not read the auth object, so users and sessions need their own copy. Two admin operations do it, served by the deployed worker and gated by the admin bearer like every other __lunora_admin__:* op:

• __lunora_admin__:copyAuthToJurisdiction copies every table in the un-pinned auth object into the pinned one: better-auth's tables for whatever plugins you run, the auth audit log, the rate limiter, and any table a plugin adds later. A table the pinned object lacks is created from the un-pinned object's own definition, with its indexes. user goes first, then account and session, so sign-in works again as early as possible; the audit log and the rate limiter go last.
• __lunora_admin__:purgeUnpinnedAuth drops every table in the un-pinned object.

The copy takes a snapshot: each row as the un-pinned object held it when the copy read it. The pinned object records every row it copied. The copy call that reaches the end of every table, and the purge, compare a fingerprint of the un-pinned object against that record, so a copy re-run after it finished checks again. That check is the only thing that reconciles an update or delete made on the un-pinned object after its rows were read: when it finds one, the next copy re-scans the changed table and applies it — a changed row is updated and a deleted row is deleted in the pinned object, as long as the pinned object still holds the copied version.

Do this in a short maintenance window. Once the acknowledgement is deployed, sign-ins land in the pinned object, which is empty until the copy runs.

export const schema = defineSchema({/* … */}).jurisdiction("eu", { pinAuth: true });

lunora codegen && lunora deploy

LUNORA_ADMIN_TOKEN=… lunora run __lunora_admin__:copyAuthToJurisdiction \
  --url https://app.example.com

{
    "done": true,
    "tables": [
        { "table": "user", "sourceRows": 1840, "copied": 1840, "updated": 0, "deleted": 0, "unchanged": 0, "conflicts": 0, "targetRows": 1840 },
        { "table": "account", "sourceRows": 1840, "copied": 1840, "updated": 0, "deleted": 0, "unchanged": 0, "conflicts": 0, "targetRows": 1840 }
    ]
}

LUNORA_ADMIN_TOKEN=… lunora run __lunora_admin__:purgeUnpinnedAuth \
  --url https://app.example.com

Pinning mail

@lunora/mail has no Durable Object of its own. Its two shard paths call the app's __root__ shard:

• dispatchToLunoraFunction runs your inbound function there (for example inbound:onEmail), and that function writes to your own tables.
• In development, createMailerFromEnv records each captured message in the studio's Mail inbox, a table in the same shard.

The generated worker records the schema's jurisdiction when it loads, in the worker and in every Durable Object class it exports. Both paths read it and pin the SHARD namespace, so you do not pass anything. The jurisdiction option on each is only for a hand-written worker that does not use the generated defineApp. A value that contradicts the schema's throws.

Nothing to acknowledge. Before this, an app that declared a jurisdiction but did not pass it to mail sent mail's writes to the un-pinned __root__. The rest of the app reads the pinned one. So those rows were already out of the app's view, and pinning mail hides nothing the app could see. After the deploy, inbound functions write where your queries read, and captured dev mail shows in the studio inbox.

What stays behind. Rows written through the un-pinned path before the deploy stay in the un-pinned __root__: the rows your inbound function wrote there, and captured dev mail. lunora export reads the pinned shards only, so it does not include them. The mail that produced them has already been delivered or bounced. Mail has no outbox, retry state or suppression list in a Durable Object, and mailer.queue() uses a Cloudflare Queue.

Set it once: changing it strands data

A Durable Object name maps to a different ID in each jurisdiction. So toggling, changing, or removing .jurisdiction(...) on an app that has already deployed makes every shard, scheduler job, container, voice session, and DO-backed auth object resolve to a new, empty DO. The previous data stays in the old region's DOs and is no longer reachable through the worker. There is no in-place migration.

Because this is the most destructive change a schema can express, the pre-deploy drift gate flags it as breaking and blocks the deploy:

Durable Object jurisdiction changed from (none) to us — this re-homes every DO
and strands all existing shard, scheduler, and session-DO data in the old region
(no in-place migration; export then import to move it). Revert the change, or
override the gate to proceed intentionally.

Revert the change, or, if a region move is genuinely intended, follow the runbook below and override the gate explicitly.

Runbook: moving an app to a new jurisdiction

The only way to move existing data across jurisdictions is to export it while the worker can still read the old region, then import it after the worker is pinned to the new one. Order matters: once you deploy the jurisdiction change, the old DOs become unreachable through the worker.

Do this in a maintenance window: writes that land between the export and the import are not carried over.

LUNORA_ADMIN_TOKEN=… lunora export --prod --url https://app.example.com \
  --out backup.ndjson \
  --tables messages,channels,users   # scope to DO-backed tables

wc -l backup.ndjson

export const schema = defineSchema({
    // …
}).jurisdiction("us"); // was "eu"

lunora codegen

lunora deploy --allow-schema-drift --update-schema-baseline

LUNORA_ADMIN_TOKEN=… lunora import backup.ndjson --prod --url https://app.example.com