@remit/config-transfer 0.0.9 → 0.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/config-transfer",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/binder.ts

@@ -1,17 +1,24 @@
 import { readConfigDocument } from "@remit/config-format";
-import type {
-	ConfigImportItem,
-	ConfigImportUnresolvedRefItem,
-	IAccountSettingRepository,
-	IConfigImportRepository,
-	IFilterRepository,
-	IMailboxRepository,
+import {
+	type ConfigImportItem,
+	type ConfigImportUnresolvedRefItem,
+	type CreateMailboxResult,
+	FILTER_NO_ACTION,
+	type FilterItem,
+	type IAccountSettingRepository,
+	type IConfigImportRepository,
+	type IFilterRepository,
+	type IMailboxRepository,
+	type MailboxItem,
 } from "@remit/data-ports";
 import { composeSettingName } from "@remit/data-ports/account-settings";
 import {
 	AccountSettingName,
 	ConfigImportRefKind,
 	ConfigImportState,
+	FilterDisabledReason,
+	FilterState,
+	MailboxSyncStatus,
 } from "@remit/domain-enums";
 import type { AppointFolderRole } from "./import-repositories.js";
 
@@ -19,12 +26,18 @@ export interface ConfigBinderRepositories {
 	configImport: Pick<IConfigImportRepository, "listByAccountConfig" | "update">;
 	accountSetting: Pick<IAccountSettingRepository, "upsert">;
 	filter: Pick<IFilterRepository, "listByAccountConfig" | "update">;
-	mailbox: Pick<IMailboxRepository, "listAllByAccount">;
+	mailbox: Pick<IMailboxRepository, "listAllByAccount" | "resolveAccountId">;
 }
 
+export type CreateImportedFolder = (
+	accountId: string,
+	folderPath: string,
+) => Promise<CreateMailboxResult>;
+
 export interface ConfigBinderDeps {
 	repositories: ConfigBinderRepositories;
 	appointFolderRole: AppointFolderRole;
+	createFolder: CreateImportedFolder;
 	now?: () => number;
 }
 
@@ -35,27 +48,34 @@ export interface ConfigBinderDeps {
 export interface BindResult {
 	bound: number;
 	dropped: number;
+	created: number;
+	disabled: number;
 	stillPending: number;
 }
 
 type RefState =
 	| { kind: "TargetGone" }
-	| { kind: "Waiting" }
-	| { kind: "Ready"; mailboxId: string };
+	| { kind: "Waiting"; mailboxId: string }
+	| { kind: "Ready"; mailboxId: string }
+	| { kind: "Absent" }
+	| { kind: "Refused"; reason: FilterItem["disabledReason"] };
 
 /**
  * Bind the folder references an import could not resolve, now that discovery
  * has produced this account's mailboxes.
  *
  * Every reference names a folder by IMAP path, because the ids are new on every
- * discovery. This runs where discovery ends, resolves what it can, writes the
- * row each reference belongs to, and drops it. An import whose last reference
- * is gone is Complete; the rest stay, and surface on `GET /config` until the
- * folder they name shows up or the person removes the expectation.
+ * discovery. A path discovery did not produce is a folder the account lacks,
+ * so the binder creates it through the folder-create mutation and waits for
+ * the server to confirm it (imap-mutations R1, R2: wait), binding to that row
+ * by id because the server may have normalized its path. A create the server
+ * refused, or a created folder that vanished, drops the reference and turns
+ * its filter off with the reason.
  *
  * Idempotent and replayable: every write is an upsert or an update onto a row
- * the import already created, so a second discovery finds nothing to do rather
- * than doing it again differently.
+ * the import already created, and a create is recorded on the reference before
+ * the next run, so a second discovery finds nothing to do rather than doing it
+ * again differently.
  */
 export const bindImportedFolders = async (
 	deps: ConfigBinderDeps,
@@ -64,48 +84,108 @@ export const bindImportedFolders = async (
 ): Promise<BindResult> => {
 	const { repositories } = deps;
 	const now = deps.now ?? Date.now;
+	const result: BindResult = {
+		bound: 0,
+		dropped: 0,
+		created: 0,
+		disabled: 0,
+		stillPending: 0,
+	};
 
 	const imports = (
 		await repositories.configImport.listByAccountConfig(accountConfigId)
 	).filter((row) => row.state === ConfigImportState.Pending);
-	if (imports.length === 0) return { bound: 0, dropped: 0, stillPending: 0 };
+	if (imports.length === 0) return result;
 
+	const mailboxes = await repositories.mailbox.listAllByAccount(accountId);
 	const byPath = new Map(
-		(await repositories.mailbox.listAllByAccount(accountId)).map(
-			(mailbox) => [mailbox.fullPath, mailbox.mailboxId] as const,
-		),
+		mailboxes.map((mailbox) => [mailbox.fullPath, mailbox] as const),
+	);
+	const byId = new Map(
+		mailboxes.map((mailbox) => [mailbox.mailboxId, mailbox] as const),
 	);
 
-	const filterIds = new Set(
+	const filtersById = new Map(
 		(await repositories.filter.listByAccountConfig(accountConfigId)).map(
-			(filter) => filter.filterId,
+			(filter) => [filter.filterId, filter] as const,
 		),
 	);
 
-	let bound = 0;
-	let dropped = 0;
-	let stillPending = 0;
+	const createdByPath = new Map<string, string>();
+	const createFolder = async (folderPath: string): Promise<string> => {
+		const held = createdByPath.get(folderPath);
+		if (held !== undefined) return held;
+		const created = await deps.createFolder(accountId, folderPath);
+		if (created.outcome === "PathTaken") return FILTER_NO_ACTION;
+		createdByPath.set(folderPath, created.mailbox.mailboxId);
+		result.created++;
+		return created.mailbox.mailboxId;
+	};
 
 	for (const row of imports) {
 		const document = readConfigDocument(row.document);
 		const remaining: ConfigImportUnresolvedRefItem[] = [];
+		let changed = false;
 
 		for (const ref of row.unresolvedRefs) {
-			const state = refStateOf(ref, accountId, byPath, filterIds);
+			const state = refStateOf(ref, accountId, byPath, byId, filtersById);
+			if (
+				(state.kind === "Ready" || state.kind === "Refused") &&
+				!movesIntoNothing(ref, filtersById)
+			) {
+				await settlePickedFolder(
+					repositories,
+					accountConfigId,
+					filtersById.get(ref.target),
+				);
+				result.dropped++;
+				changed = true;
+				continue;
+			}
 			if (state.kind === "TargetGone") {
-				dropped++;
+				result.dropped++;
+				changed = true;
 				continue;
 			}
 			if (state.kind === "Waiting") {
-				remaining.push(ref);
+				if (state.mailboxId !== ref.mailboxId) changed = true;
+				remaining.push({ ...ref, mailboxId: state.mailboxId });
 				continue;
 			}
-			await bindRef(deps, accountConfigId, ref, state.mailboxId, document);
-			bound++;
+			if (state.kind === "Absent") {
+				remaining.push({
+					...ref,
+					mailboxId: await createFolder(ref.folderPath),
+				});
+				changed = true;
+				continue;
+			}
+			if (state.kind === "Refused") {
+				if (ref.kind === ConfigImportRefKind.FilterAction) {
+					await repositories.filter.update(accountConfigId, ref.target, {
+						state: FilterState.Disabled,
+						disabledReason: state.reason,
+					});
+					result.disabled++;
+				}
+				result.dropped++;
+				changed = true;
+				continue;
+			}
+			await bindRef(
+				deps,
+				accountConfigId,
+				ref,
+				state.mailboxId,
+				document,
+				filtersById,
+			);
+			result.bound++;
+			changed = true;
 		}
 
-		stillPending += remaining.length;
-		if (remaining.length === row.unresolvedRefs.length) continue;
+		result.stillPending += remaining.length;
+		if (!changed) continue;
 
 		await repositories.configImport.update(row.importId, {
 			unresolvedRefs: remaining,
@@ -115,27 +195,116 @@ export const bindImportedFolders = async (
 		});
 	}
 
-	return { bound, dropped, stillPending };
+	return result;
+};
+
+export const disableFiltersMissingFolders = async (
+	repositories: {
+		filter: Pick<IFilterRepository, "listByAccountConfig" | "update">;
+		mailbox: Pick<IMailboxRepository, "resolveAccountId">;
+	},
+	accountConfigId: string,
+): Promise<number> => {
+	const filters =
+		await repositories.filter.listByAccountConfig(accountConfigId);
+	let disabled = 0;
+	for (const filter of filters) {
+		if (filter.state !== FilterState.Active) continue;
+		if (filter.actionMailboxId === FILTER_NO_ACTION) continue;
+		const owner = await repositories.mailbox.resolveAccountId(
+			filter.actionMailboxId,
+		);
+		if (owner !== null) continue;
+		await repositories.filter.update(accountConfigId, filter.filterId, {
+			state: FilterState.Disabled,
+			disabledReason: FilterDisabledReason.FolderMissing,
+		});
+		disabled++;
+	}
+	return disabled;
 };
 
 type BoundDocument = ReturnType<typeof readConfigDocument>;
 
+const FOLDERLESS_REASONS: ReadonlySet<FilterItem["disabledReason"]> = new Set([
+	FilterDisabledReason.AwaitingFolder,
+	FilterDisabledReason.FolderCreateFailed,
+]);
+
+const settlePickedFolder = async (
+	repositories: ConfigBinderRepositories,
+	accountConfigId: string,
+	filter: FilterItem | undefined,
+): Promise<void> => {
+	if (!filter || filter.state !== FilterState.Disabled) return;
+	if (!FOLDERLESS_REASONS.has(filter.disabledReason)) return;
+	await repositories.filter.update(accountConfigId, filter.filterId, {
+		disabledReason: FilterDisabledReason.UserDisabled,
+	});
+};
+
+const movesIntoNothing = (
+	ref: ConfigImportUnresolvedRefItem,
+	filtersById: ReadonlyMap<string, FilterItem>,
+): boolean =>
+	ref.kind !== ConfigImportRefKind.FilterAction ||
+	filtersById.get(ref.target)?.actionMailboxId === FILTER_NO_ACTION;
+
+const findByPath = (
+	folderPath: string,
+	byPath: ReadonlyMap<string, MailboxItem>,
+): MailboxItem | undefined => {
+	const exact = byPath.get(folderPath);
+	if (exact) return exact;
+	const prefix = byPath.get("INBOX")?.namespacePrefix ?? "";
+	if (prefix === "" || folderPath.startsWith(prefix)) return undefined;
+	return byPath.get(`${prefix}${folderPath}`);
+};
+
 const refStateOf = (
 	ref: ConfigImportUnresolvedRefItem,
 	accountId: string,
-	byPath: ReadonlyMap<string, string>,
-	filterIds: ReadonlySet<string>,
+	byPath: ReadonlyMap<string, MailboxItem>,
+	byId: ReadonlyMap<string, MailboxItem>,
+	filtersById: ReadonlyMap<string, FilterItem>,
 ): RefState => {
 	if (
 		ref.kind === ConfigImportRefKind.FilterAction &&
-		!filterIds.has(ref.target)
+		!filtersById.has(ref.target)
 	) {
 		return { kind: "TargetGone" };
 	}
-	const mailboxId =
-		ref.accountId === accountId ? byPath.get(ref.folderPath) : undefined;
-	if (mailboxId === undefined) return { kind: "Waiting" };
-	return { kind: "Ready", mailboxId };
+	if (ref.accountId !== accountId) {
+		return { kind: "Waiting", mailboxId: ref.mailboxId };
+	}
+	const created = byId.get(ref.mailboxId);
+	if (created) {
+		if (created.syncStatus === MailboxSyncStatus.synced) {
+			return { kind: "Ready", mailboxId: created.mailboxId };
+		}
+		if (
+			created.syncStatus === MailboxSyncStatus.failed &&
+			created.pendingPath === undefined
+		) {
+			return {
+				kind: "Refused",
+				reason: FilterDisabledReason.FolderCreateFailed,
+			};
+		}
+		return { kind: "Waiting", mailboxId: created.mailboxId };
+	}
+	const found = findByPath(ref.folderPath, byPath);
+	if (found?.syncStatus === MailboxSyncStatus.synced) {
+		return { kind: "Ready", mailboxId: found.mailboxId };
+	}
+	if (found) return { kind: "Waiting", mailboxId: FILTER_NO_ACTION };
+	if (ref.mailboxId !== FILTER_NO_ACTION) {
+		return {
+			kind: "Refused",
+			reason: FilterDisabledReason.FolderCreateFailed,
+		};
+	}
+	return { kind: "Absent" };
 };
 
 const bindRef = async (
@@ -144,11 +313,21 @@ const bindRef = async (
 	ref: ConfigImportUnresolvedRefItem,
 	mailboxId: string,
 	document: BoundDocument,
+	filtersById: ReadonlyMap<string, FilterItem>,
 ): Promise<void> => {
 	const { repositories } = deps;
 	if (ref.kind === ConfigImportRefKind.FilterAction) {
+		const awaiting =
+			filtersById.get(ref.target)?.disabledReason ===
+			FilterDisabledReason.AwaitingFolder;
 		await repositories.filter.update(accountConfigId, ref.target, {
 			actionMailboxId: mailboxId,
+			...(awaiting
+				? {
+						state: FilterState.Active,
+						disabledReason: FilterDisabledReason.None,
+					}
+				: {}),
 		});
 		return;
 	}

package/src/fixtures.ts

@@ -79,6 +79,7 @@ export const makeMailbox = (
 		Pick<MailboxItem, "mailboxId" | "accountId" | "fullPath">,
 ): MailboxItem => ({
 	namespaceType: "personal",
+	syncFailureReason: "",
 	namespacePrefix: "",
 	hierarchyDelimiter: ".",
 	uidValidity: 1,
@@ -128,6 +129,7 @@ export const makeFilter = (
 	accountConfigId: ACCOUNT_CONFIG_ID,
 	scope: "Standing",
 	state: "Active",
+	disabledReason: "None",
 	hasAnchor: false,
 	ruleChangedAt: NOW,
 	actionChangedAt: NOW,

package/src/import.test.ts

@@ -17,7 +17,11 @@ import {
 	composeFolderRoleAppointmentName,
 } from "@remit/data-ports/folder-role";
 import { deriveAddressId } from "@remit/data-ports/id";
-import { bindImportedFolders, pendingImportOf } from "./binder.js";
+import {
+	bindImportedFolders,
+	disableFiltersMissingFolders,
+	pendingImportOf,
+} from "./binder.js";
 import { readConfigForExport } from "./export.js";
 import {
 	ACCOUNT_CONFIG_ID,
@@ -185,6 +189,9 @@ const repositoriesOf = (store: Store, accountConfigId: string): any => {
 		mailbox: {
 			listAllByAccount: async (accountId: string) =>
 				store.mailboxes.filter((mailbox) => mailbox.accountId === accountId),
+			resolveAccountId: async (mailboxId: string) =>
+				store.mailboxes.find((mailbox) => mailbox.mailboxId === mailboxId)
+					?.accountId ?? null,
 		},
 		label: {
 			listByAccountConfig: async () => [...store.labels],
@@ -353,6 +360,38 @@ const appointFolderRoleInto =
 		);
 	};
 
+const createFolderInto =
+	(store: Store) =>
+	async (
+		accountId: string,
+		fullPath: string,
+	): Promise<{ outcome: "Created"; mailbox: MailboxItem }> => {
+		const row = makeMailbox({
+			mailboxId: nextId("mbx"),
+			accountId,
+			fullPath,
+			syncStatus: "pending",
+		});
+		store.mailboxes.push(row);
+		return { outcome: "Created", mailbox: row };
+	};
+
+const settle = (
+	store: Store,
+	fullPath: string,
+	syncStatus: MailboxItem["syncStatus"],
+	confirmedPath: string = fullPath,
+): MailboxItem => {
+	const at = store.mailboxes.findIndex(
+		(mailbox) =>
+			mailbox.fullPath === fullPath && mailbox.syncStatus === "pending",
+	);
+	assert.notEqual(at, -1, `no pending create for ${fullPath}`);
+	const next = { ...store.mailboxes[at], syncStatus, fullPath: confirmedPath };
+	store.mailboxes[at] = next;
+	return next;
+};
+
 /**
  * A transaction that actually rolls back. The backend's `writeSet` discards
  * every write on a throw, so a fake that merely called through would let an
@@ -602,6 +641,7 @@ test("a configuration survives an export, an import and a discovery unchanged",
 	const binder = {
 		repositories: repositoriesOf(store, TARGET_CONFIG_ID),
 		appointFolderRole: appointFolderRoleInto(store),
+		createFolder: createFolderInto(store),
 		now: () => NOW,
 	};
 	await bindImportedFolders(binder, TARGET_CONFIG_ID, PASSWORD_ACCOUNT_ID);
@@ -828,7 +868,7 @@ test("a flag that arrives at the sentinel is stored at the sentinel", async () =
 	assert.equal(legacy?.flags?.category?.setAt, 0);
 });
 
-test("a folder no mailbox answers to yet is kept, then bound when discovery finds it", async () => {
+test("a folder discovery did not produce is created, and bound once the server confirms it", async () => {
 	const document = await exportSource();
 	const store = emptyStore();
 
@@ -849,6 +889,7 @@ test("a folder no mailbox answers to yet is kept, then bound when discovery find
 	const binder = {
 		repositories: repositoriesOf(store, TARGET_CONFIG_ID),
 		appointFolderRole: appointFolderRoleInto(store),
+		createFolder: createFolderInto(store),
 		now: () => NOW,
 	};
 	const first = await bindImportedFolders(
@@ -858,6 +899,7 @@ test("a folder no mailbox answers to yet is kept, then bound when discovery find
 	);
 
 	assert.equal(first.bound > 0, true);
+	assert.equal(first.created, 2);
 	assert.equal(first.stillPending > 0, true);
 	const invoices = store.mailboxes.find(
 		(mailbox) => mailbox.fullPath === "INBOX.Facturen",
@@ -868,16 +910,28 @@ test("a folder no mailbox answers to yet is kept, then bound when discovery find
 		invoices?.mailboxId,
 	);
 
-	// Replayable: a second discovery over the same folders changes nothing.
+	// Replayable: a second discovery over the same folders creates nothing again.
 	const again = await bindImportedFolders(
 		binder,
 		TARGET_CONFIG_ID,
 		PASSWORD_ACCOUNT_ID,
 	);
 	assert.equal(again.bound, 0);
+	assert.equal(again.created, 0);
+	assert.equal(
+		store.mailboxes.filter((mailbox) => mailbox.fullPath === "INBOX.Sent")
+			.length,
+		1,
+	);
 	assert.equal(store.imports[0].state, "Pending");
 
-	discover(store, PASSWORD_ACCOUNT_ID, ["INBOX.Sent", "INBOX.Lists.dev-null"]);
+	settle(store, "INBOX.Sent", "synced");
+	const lists = settle(
+		store,
+		"INBOX.Lists.dev-null",
+		"synced",
+		"INBOX.Lists.dev-null-normalized",
+	);
 	discover(store, OAUTH_ACCOUNT_ID, ["INBOX"]);
 	await bindImportedFolders(binder, TARGET_CONFIG_ID, PASSWORD_ACCOUNT_ID);
 
@@ -890,15 +944,499 @@ test("a folder no mailbox answers to yet is kept, then bound when discovery find
 		)?.value.kind,
 		"String",
 	);
-	const lists = store.mailboxes.find(
-		(mailbox) => mailbox.fullPath === "INBOX.Lists.dev-null",
-	);
 	assert.equal(
-		store.settings.get(`MailboxDisplayName#${lists?.mailboxId}`)?.value.value,
+		store.settings.get(`MailboxDisplayName#${lists.mailboxId}`)?.value.value,
 		"dev/null",
 	);
 });
 
+test("a filter whose folder is missing lands disabled, awaiting the folder, and the report says so", async () => {
+	const document = await exportSource();
+	const store = emptyStore();
+
+	const report = reportOf(await apply(store, document));
+
+	const invoices = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.equal(invoices?.state, "Disabled");
+	assert.equal(invoices?.disabledReason, "AwaitingFolder");
+	assert.match(
+		report.items.find((item) => item.key === "Invoices to Facturen")?.reason ??
+			"",
+		/Off until "INBOX\.Facturen" exists/,
+	);
+});
+
+test("the dry run names the filters an apply would leave off", async () => {
+	const document = await exportSource();
+	const store = emptyStore();
+
+	const outcome = await importConfig(depsOf(store, TARGET_CONFIG_ID), {
+		accountConfigId: TARGET_CONFIG_ID,
+		userId: TARGET_USER_ID,
+		document,
+		mode: "validate",
+		onExisting: "abort",
+	});
+
+	assert.match(
+		reportOf(outcome).items.find((item) => item.key === "Invoices to Facturen")
+			?.reason ?? "",
+		/Off until "INBOX\.Facturen" exists/,
+	);
+});
+
+test("an imported filter turns on once the folder the binder created settles, under the path the server chose", async () => {
+	const document = await exportSource();
+	const store = emptyStore();
+	await apply(store, document);
+
+	discover(store, PASSWORD_ACCOUNT_ID, ["INBOX", "INBOX.Sent"]);
+	const binder = {
+		repositories: repositoriesOf(store, TARGET_CONFIG_ID),
+		appointFolderRole: appointFolderRoleInto(store),
+		createFolder: createFolderInto(store),
+		now: () => NOW,
+	};
+	await bindImportedFolders(binder, TARGET_CONFIG_ID, PASSWORD_ACCOUNT_ID);
+
+	const waiting = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.equal(waiting?.state, "Disabled");
+	assert.equal(waiting?.disabledReason, "AwaitingFolder");
+	assert.equal(waiting?.actionMailboxId, "None");
+
+	const created = settle(store, "INBOX.Facturen", "synced", "INBOX/Facturen");
+	await bindImportedFolders(binder, TARGET_CONFIG_ID, PASSWORD_ACCOUNT_ID);
+
+	const bound = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.equal(bound?.state, "Active");
+	assert.equal(bound?.disabledReason, "None");
+	assert.equal(bound?.actionMailboxId, created.mailboxId);
+});
+
+test("a folder the server refused to create turns its filter off with FolderCreateFailed", async () => {
+	const document = await exportSource();
+	const store = emptyStore();
+	await apply(store, document);
+
+	discover(store, PASSWORD_ACCOUNT_ID, ["INBOX", "INBOX.Sent"]);
+	const binder = {
+		repositories: repositoriesOf(store, TARGET_CONFIG_ID),
+		appointFolderRole: appointFolderRoleInto(store),
+		createFolder: createFolderInto(store),
+		now: () => NOW,
+	};
+	await bindImportedFolders(binder, TARGET_CONFIG_ID, PASSWORD_ACCOUNT_ID);
+	settle(store, "INBOX.Facturen", "failed");
+
+	const result = await bindImportedFolders(
+		binder,
+		TARGET_CONFIG_ID,
+		PASSWORD_ACCOUNT_ID,
+	);
+
+	assert.equal(result.disabled, 1);
+	const refused = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.equal(refused?.state, "Disabled");
+	assert.equal(refused?.disabledReason, "FolderCreateFailed");
+	assert.equal(
+		pendingImportOf(store.imports)?.folderPaths.includes("INBOX.Facturen") ??
+			false,
+		false,
+	);
+});
+
+test("a created folder that disappears before it settles means the create never landed", async () => {
+	const document = await exportSource();
+	const store = emptyStore();
+	await apply(store, document);
+
+	discover(store, PASSWORD_ACCOUNT_ID, ["INBOX", "INBOX.Sent"]);
+	const binder = {
+		repositories: repositoriesOf(store, TARGET_CONFIG_ID),
+		appointFolderRole: appointFolderRoleInto(store),
+		createFolder: createFolderInto(store),
+		now: () => NOW,
+	};
+	await bindImportedFolders(binder, TARGET_CONFIG_ID, PASSWORD_ACCOUNT_ID);
+	store.mailboxes = store.mailboxes.filter(
+		(mailbox) => mailbox.fullPath !== "INBOX.Facturen",
+	);
+
+	const result = await bindImportedFolders(
+		binder,
+		TARGET_CONFIG_ID,
+		PASSWORD_ACCOUNT_ID,
+	);
+
+	assert.equal(result.disabled, 1);
+	const refused = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.equal(refused?.state, "Disabled");
+	assert.equal(refused?.disabledReason, "FolderCreateFailed");
+});
+
+test("a create that finds its path already taken binds the existing folder on the next sync", async () => {
+	const document = await exportSource();
+	const store = emptyStore();
+	await apply(store, document);
+
+	discover(store, PASSWORD_ACCOUNT_ID, ["INBOX", "INBOX.Sent"]);
+	const binder = {
+		repositories: repositoriesOf(store, TARGET_CONFIG_ID),
+		appointFolderRole: appointFolderRoleInto(store),
+		createFolder: async () => ({ outcome: "PathTaken" as const }),
+		now: () => NOW,
+	};
+	const first = await bindImportedFolders(
+		binder,
+		TARGET_CONFIG_ID,
+		PASSWORD_ACCOUNT_ID,
+	);
+
+	assert.equal(first.created, 0);
+	assert.equal(
+		store.imports[0].unresolvedRefs.find(
+			(ref) => ref.folderPath === "INBOX.Facturen",
+		)?.mailboxId,
+		"None",
+	);
+
+	discover(store, PASSWORD_ACCOUNT_ID, ["INBOX.Facturen"]);
+	await bindImportedFolders(binder, TARGET_CONFIG_ID, PASSWORD_ACCOUNT_ID);
+
+	const existing = store.mailboxes.find(
+		(mailbox) => mailbox.fullPath === "INBOX.Facturen",
+	);
+	const bound = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.equal(bound?.state, "Active");
+	assert.equal(bound?.actionMailboxId, existing?.mailboxId);
+});
+
+const withUnprefixedPaths = async () => {
+	const document = (await exportSource()) as unknown as {
+		accounts: {
+			folderRoles: { role: string; folderPath: string }[];
+		}[];
+		filters: { actionFolder: { folderPath: string } | null }[];
+	};
+	for (const filter of document.filters) {
+		if (filter.actionFolder?.folderPath === "INBOX.Facturen") {
+			filter.actionFolder.folderPath = "Facturen";
+		}
+	}
+	for (const account of document.accounts) {
+		for (const role of account.folderRoles) {
+			if (role.folderPath === "INBOX.Sent") role.folderPath = "Sent";
+		}
+	}
+	return document;
+};
+
+const discoverUnderInbox = (store: Store, paths: readonly string[]): void => {
+	for (const fullPath of ["INBOX", ...paths]) {
+		store.mailboxes.push(
+			makeMailbox({
+				mailboxId: nextId("mbx"),
+				accountId: PASSWORD_ACCOUNT_ID,
+				fullPath,
+				namespacePrefix: "INBOX.",
+			}),
+		);
+	}
+};
+
+test("a folder the account already holds under its namespace is bound, not created", async () => {
+	const store = emptyStore();
+	await apply(store, await withUnprefixedPaths());
+
+	discoverUnderInbox(store, ["INBOX.Facturen", "INBOX.Sent"]);
+	const result = await bindImportedFolders(
+		{
+			repositories: repositoriesOf(store, TARGET_CONFIG_ID),
+			appointFolderRole: appointFolderRoleInto(store),
+			createFolder: createFolderInto(store),
+			now: () => NOW,
+		},
+		TARGET_CONFIG_ID,
+		PASSWORD_ACCOUNT_ID,
+	);
+
+	const facturen = store.mailboxes.find(
+		(mailbox) => mailbox.fullPath === "INBOX.Facturen",
+	);
+	const sent = store.mailboxes.find(
+		(mailbox) => mailbox.fullPath === "INBOX.Sent",
+	);
+	assert.equal(
+		store.mailboxes.some((mailbox) => mailbox.fullPath === "Facturen"),
+		false,
+	);
+	assert.equal(result.disabled, 0);
+	const bound = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.equal(bound?.state, "Active");
+	assert.equal(bound?.actionMailboxId, facturen?.mailboxId);
+	assert.equal(
+		store.settings.get(
+			composeFolderRoleAppointmentName(PASSWORD_ACCOUNT_ID, "Sent"),
+		)?.value.value,
+		sent?.mailboxId,
+	);
+});
+
+test("a created folder the worker folds into one the server already held binds to that one", async () => {
+	const store = emptyStore();
+	await apply(store, await withUnprefixedPaths());
+
+	discoverUnderInbox(store, ["INBOX.Sent"]);
+	const binder = {
+		repositories: repositoriesOf(store, TARGET_CONFIG_ID),
+		appointFolderRole: appointFolderRoleInto(store),
+		createFolder: createFolderInto(store),
+		now: () => NOW,
+	};
+	const first = await bindImportedFolders(
+		binder,
+		TARGET_CONFIG_ID,
+		PASSWORD_ACCOUNT_ID,
+	);
+	assert.equal(first.created > 0, true);
+
+	store.mailboxes = store.mailboxes.filter(
+		(mailbox) => mailbox.fullPath !== "Facturen",
+	);
+	const holder = makeMailbox({
+		mailboxId: nextId("mbx"),
+		accountId: PASSWORD_ACCOUNT_ID,
+		fullPath: "INBOX.Facturen",
+		namespacePrefix: "INBOX.",
+	});
+	store.mailboxes.push(holder);
+
+	const second = await bindImportedFolders(
+		binder,
+		TARGET_CONFIG_ID,
+		PASSWORD_ACCOUNT_ID,
+	);
+
+	assert.equal(second.disabled, 0);
+	const bound = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.equal(bound?.state, "Active");
+	assert.equal(bound?.disabledReason, "None");
+	assert.equal(bound?.actionMailboxId, holder.mailboxId);
+});
+
+test("a filter the user pointed at a folder keeps it when the imported folder appears", async () => {
+	const document = await exportSource();
+	const store = emptyStore();
+	await apply(store, document);
+
+	const invoices = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.ok(invoices);
+	invoices.actionMailboxId = "mbx-picked";
+
+	discover(store, PASSWORD_ACCOUNT_ID, [
+		"INBOX",
+		"INBOX.Sent",
+		"INBOX.Facturen",
+	]);
+	await bindImportedFolders(
+		{
+			repositories: repositoriesOf(store, TARGET_CONFIG_ID),
+			appointFolderRole: appointFolderRoleInto(store),
+			createFolder: createFolderInto(store),
+			now: () => NOW,
+		},
+		TARGET_CONFIG_ID,
+		PASSWORD_ACCOUNT_ID,
+	);
+
+	const picked = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.equal(picked?.actionMailboxId, "mbx-picked");
+	assert.equal(picked?.state, "Disabled");
+	assert.equal(picked?.disabledReason, "UserDisabled");
+	assert.equal(
+		store.imports[0].unresolvedRefs.some(
+			(ref) => ref.target === invoices.filterId,
+		),
+		false,
+	);
+});
+
+test("a filter the user already turned on with their own folder survives the import's failed create", async () => {
+	const document = await exportSource();
+	const store = emptyStore();
+	await apply(store, document);
+
+	discover(store, PASSWORD_ACCOUNT_ID, ["INBOX", "INBOX.Sent"]);
+	const binder = {
+		repositories: repositoriesOf(store, TARGET_CONFIG_ID),
+		appointFolderRole: appointFolderRoleInto(store),
+		createFolder: createFolderInto(store),
+		now: () => NOW,
+	};
+	await bindImportedFolders(binder, TARGET_CONFIG_ID, PASSWORD_ACCOUNT_ID);
+
+	const invoices = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.ok(invoices);
+	Object.assign(invoices, {
+		actionMailboxId: "mbx-picked",
+		state: "Active",
+		disabledReason: "None",
+	});
+	settle(store, "INBOX.Facturen", "failed");
+
+	const result = await bindImportedFolders(
+		binder,
+		TARGET_CONFIG_ID,
+		PASSWORD_ACCOUNT_ID,
+	);
+
+	assert.equal(result.disabled, 0);
+	const kept = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.equal(kept?.state, "Active");
+	assert.equal(kept?.actionMailboxId, "mbx-picked");
+});
+
+test("a failed rename of the created folder is not read as a failed create", async () => {
+	const document = await exportSource();
+	const store = emptyStore();
+	await apply(store, document);
+
+	discover(store, PASSWORD_ACCOUNT_ID, ["INBOX", "INBOX.Sent"]);
+	const binder = {
+		repositories: repositoriesOf(store, TARGET_CONFIG_ID),
+		appointFolderRole: appointFolderRoleInto(store),
+		createFolder: createFolderInto(store),
+		now: () => NOW,
+	};
+	await bindImportedFolders(binder, TARGET_CONFIG_ID, PASSWORD_ACCOUNT_ID);
+	const created = settle(store, "INBOX.Facturen", "failed");
+	Object.assign(created, { pendingPath: "INBOX.Invoices" });
+
+	const result = await bindImportedFolders(
+		binder,
+		TARGET_CONFIG_ID,
+		PASSWORD_ACCOUNT_ID,
+	);
+
+	assert.equal(result.disabled, 0);
+	const waiting = store.filters.find(
+		(filter) => filter.name === "Invoices to Facturen",
+	);
+	assert.equal(waiting?.disabledReason, "AwaitingFolder");
+	assert.equal(
+		store.imports[0].unresolvedRefs.some(
+			(ref) => ref.mailboxId === created.mailboxId,
+		),
+		true,
+	);
+});
+
+test("a folder still pending on the server is waited for, never bound", async () => {
+	const document = await exportSource();
+	const store = emptyStore();
+	await apply(store, document);
+
+	store.mailboxes.push(
+		makeMailbox({
+			mailboxId: nextId("mbx"),
+			accountId: PASSWORD_ACCOUNT_ID,
+			fullPath: "INBOX.Facturen",
+			syncStatus: "pending",
+		}),
+	);
+	discover(store, PASSWORD_ACCOUNT_ID, ["INBOX", "INBOX.Sent"]);
+	const result = await bindImportedFolders(
+		{
+			repositories: repositoriesOf(store, TARGET_CONFIG_ID),
+			appointFolderRole: appointFolderRoleInto(store),
+			createFolder: createFolderInto(store),
+			now: () => NOW,
+		},
+		TARGET_CONFIG_ID,
+		PASSWORD_ACCOUNT_ID,
+	);
+
+	assert.equal(
+		store.mailboxes.filter((mailbox) => mailbox.fullPath === "INBOX.Facturen")
+			.length,
+		1,
+	);
+	assert.equal(result.stillPending > 0, true);
+	assert.equal(
+		store.filters.find((filter) => filter.name === "Invoices to Facturen")
+			?.actionMailboxId,
+		"None",
+	);
+});
+
+test("a running filter whose folder another client deleted turns off with FolderMissing", async () => {
+	const store = emptyStore();
+	store.mailboxes.push(
+		makeMailbox({
+			mailboxId: INVOICES_ID,
+			accountId: PASSWORD_ACCOUNT_ID,
+			fullPath: "INBOX.Facturen",
+		}),
+	);
+	store.filters.push(
+		makeFilter({
+			filterId: "flt-live",
+			name: "Live",
+			actionMailboxId: INVOICES_ID,
+		}),
+		makeFilter({
+			filterId: "flt-gone",
+			name: "Gone",
+			actionMailboxId: LISTS_ID,
+		}),
+		makeFilter({
+			filterId: "flt-off",
+			name: "Off",
+			state: "Disabled",
+			disabledReason: "UserDisabled",
+			actionMailboxId: SENT_ID,
+		}),
+	);
+
+	const disabled = await disableFiltersMissingFolders(
+		repositoriesOf(store, TARGET_CONFIG_ID),
+		TARGET_CONFIG_ID,
+	);
+
+	assert.equal(disabled, 1);
+	const byId = new Map(
+		store.filters.map((filter) => [filter.filterId, filter]),
+	);
+	assert.equal(byId.get("flt-live")?.state, "Active");
+	assert.equal(byId.get("flt-gone")?.state, "Disabled");
+	assert.equal(byId.get("flt-gone")?.disabledReason, "FolderMissing");
+	assert.equal(byId.get("flt-off")?.disabledReason, "UserDisabled");
+});
+
 test("an import with no folders to wait for is complete the moment it lands", async () => {
 	const document = await exportSource();
 	const store = emptyStore();
@@ -1226,12 +1764,19 @@ test("a binder run on a configuration with no import does nothing", async () =>
 		{
 			repositories: repositoriesOf(store, TARGET_CONFIG_ID),
 			appointFolderRole: appointFolderRoleInto(store),
+			createFolder: createFolderInto(store),
 			now: () => NOW,
 		},
 		TARGET_CONFIG_ID,
 		PASSWORD_ACCOUNT_ID,
 	);
-	assert.deepEqual(result, { bound: 0, dropped: 0, stillPending: 0 });
+	assert.deepEqual(result, {
+		bound: 0,
+		dropped: 0,
+		created: 0,
+		disabled: 0,
+		stillPending: 0,
+	});
 	assert.equal(pendingImportOf([]), undefined);
 });
 
@@ -1258,6 +1803,7 @@ test("a filter deleted before its folder is discovered drops its reference inste
 	const binder = {
 		repositories: repositoriesOf(store, TARGET_CONFIG_ID),
 		appointFolderRole: appointFolderRoleInto(store),
+		createFolder: createFolderInto(store),
 		now: () => NOW,
 	};
 
@@ -1282,7 +1828,13 @@ test("a filter deleted before its folder is discovered drops its reference inste
 		TARGET_CONFIG_ID,
 		PASSWORD_ACCOUNT_ID,
 	);
-	assert.deepEqual(again, { bound: 0, dropped: 0, stillPending: 0 });
+	assert.deepEqual(again, {
+		bound: 0,
+		dropped: 0,
+		created: 0,
+		disabled: 0,
+		stillPending: 0,
+	});
 });
 
 test("a deleted filter's reference is dropped even when its folder never appears", async () => {
@@ -1303,6 +1855,7 @@ test("a deleted filter's reference is dropped even when its folder never appears
 		{
 			repositories: repositoriesOf(store, TARGET_CONFIG_ID),
 			appointFolderRole: appointFolderRoleInto(store),
+			createFolder: createFolderInto(store),
 			now: () => NOW,
 		},
 		TARGET_CONFIG_ID,

package/src/import.ts

@@ -26,6 +26,8 @@ import {
 	ConfigImportRefKind,
 	ConfigImportState,
 	ConnectionState,
+	FilterDisabledReason,
+	FilterState,
 } from "@remit/domain-enums";
 import { carriesUserFlag } from "./export.js";
 import type { ConfigImportDeps } from "./import-repositories.js";
@@ -62,6 +64,15 @@ export interface ImportConfigInput {
 
 const normalize = (value: string): string => value.trim().toLowerCase();
 
+const filterFolderPendingMessage = (name: string, folderPath: string): string =>
+	`Filter "${name}" files mail into "${folderPath}", which this account does not hold yet. The folder is created on the mail server when the account next syncs, and the filter stays off until the server confirms it.`;
+
+const folderPendingMessage = (folderPath: string): string =>
+	`"${folderPath}" is not a folder this account holds yet. It is created on the mail server when the account next syncs, and the setting is bound once the server confirms it.`;
+
+const awaitingFolderReason = (folderPath: string): string =>
+	`Off until "${folderPath}" exists on the mail server.`;
+
 /**
  * The version a document claims, read straight off the raw input. The parse
  * failed, so this is the only honest answer the report can give — and a report
@@ -564,6 +575,12 @@ const applyDocument = async (
 					: (labelIdByName.get(normalize(filter.actionLabelName)) ?? NO_ACTION),
 			actionMailboxId: folder.actionMailboxId,
 			hasAnchor: filter.anchor !== null,
+			...(folder.pending
+				? {
+						state: FilterState.Disabled,
+						disabledReason: FilterDisabledReason.AwaitingFolder,
+					}
+				: {}),
 		};
 
 		const held = existingFilterByName.get(key);
@@ -587,11 +604,14 @@ const applyDocument = async (
 				).filterId;
 
 		filterIdByName.set(key, filterId);
-		record(
-			ConfigImportSection.Filters,
-			filter.name,
-			held ? ConfigImportVerdict.Updated : ConfigImportVerdict.Created,
-		);
+		items.push({
+			section: ConfigImportSection.Filters,
+			key: filter.name,
+			verdict: held ? ConfigImportVerdict.Updated : ConfigImportVerdict.Created,
+			...(folder.pending && filter.actionFolder
+				? { reason: awaitingFolderReason(filter.actionFolder.folderPath) }
+				: {}),
+		});
 
 		if (folder.pending && filter.actionFolder) {
 			unresolvedRefs.push({
@@ -601,11 +621,15 @@ const applyDocument = async (
 					filter.actionFolder.accountId,
 				folderPath: filter.actionFolder.folderPath,
 				target: filterId,
+				mailboxId: NO_ACTION,
 			});
 			warnings.push(
 				problem(
 					"folder_not_found_yet",
-					`Filter "${filter.name}" files mail into "${filter.actionFolder.folderPath}", which this account does not hold yet. It is bound once the folder list has been read.`,
+					filterFolderPendingMessage(
+						filter.name,
+						filter.actionFolder.folderPath,
+					),
 					{ filter: filter.name, folderPath: filter.actionFolder.folderPath },
 				),
 			);
@@ -699,11 +723,10 @@ const applyDocument = async (
 	for (const ref of unresolvedRefs) {
 		if (ref.kind === ConfigImportRefKind.FilterAction) continue;
 		warnings.push(
-			problem(
-				"folder_not_found_yet",
-				`"${ref.folderPath}" is not a folder this account holds yet. It is bound once the folder list has been read.`,
-				{ folderPath: ref.folderPath, accountId: ref.accountId },
-			),
+			problem("folder_not_found_yet", folderPendingMessage(ref.folderPath), {
+				folderPath: ref.folderPath,
+				accountId: ref.accountId,
+			}),
 		);
 	}
 
@@ -861,6 +884,7 @@ class SettingWriter {
 					accountId,
 					folderPath: role.folderPath,
 					target: role.role,
+					mailboxId: NO_ACTION,
 				});
 				continue;
 			}
@@ -881,6 +905,7 @@ class SettingWriter {
 					accountId,
 					folderPath: override.folderPath,
 					target: override.folderPath,
+					mailboxId: NO_ACTION,
 				});
 				continue;
 			}
@@ -1102,10 +1127,19 @@ const plan = (
 		});
 	}
 	for (const filter of document.filters) {
+		const { actionFolder } = filter;
+		const awaiting =
+			actionFolder !== null &&
+			!foldersFor(existing, liveAccountId, actionFolder.accountId).has(
+				actionFolder.folderPath,
+			);
 		items.push({
 			section: ConfigImportSection.Filters,
 			key: filter.name,
 			verdict: verdict(heldFilters.has(normalize(filter.name))),
+			...(awaiting && actionFolder
+				? { reason: awaitingFolderReason(actionFolder.folderPath) }
+				: {}),
 		});
 	}
 	for (const entry of document.addressFlags) {
@@ -1139,7 +1173,7 @@ const plan = (
 		warnings.push(
 			problem(
 				"folder_not_found_yet",
-				`Filter "${filter.name}" files mail into "${actionFolder.folderPath}", which this account does not hold yet. It is bound once the folder list has been read.`,
+				filterFolderPendingMessage(filter.name, actionFolder.folderPath),
 				{ filter: filter.name, folderPath: actionFolder.folderPath },
 			),
 		);
@@ -1155,11 +1189,10 @@ const plan = (
 		for (const folderPath of paths) {
 			if (folders.has(folderPath)) continue;
 			warnings.push(
-				problem(
-					"folder_not_found_yet",
-					`"${folderPath}" is not a folder this account holds yet. It is bound once the folder list has been read.`,
-					{ folderPath, accountId },
-				),
+				problem("folder_not_found_yet", folderPendingMessage(folderPath), {
+					folderPath,
+					accountId,
+				}),
 			);
 		}
 	}

package/src/index.ts

@@ -3,6 +3,8 @@ export {
 	bindImportedFolders,
 	type ConfigBinderDeps,
 	type ConfigBinderRepositories,
+	type CreateImportedFolder,
+	disableFiltersMissingFolders,
 	pendingImportOf,
 } from "./binder.js";
 export {